Skip to content

Commit ddefb6c

Browse files
peterbaepeterbae
committed
more doc changes, including the forward link for 6.4 download page.
1 parent 988dfb7 commit ddefb6c

28 files changed

Lines changed: 131 additions & 66 deletions

File tree

‎docs/connect/jdbc/connecting-using-azure-active-directory-authentication.md‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,15 @@ ms.workload: "On Demand"
2222
# Connecting using Azure Active Directory Authentication
2323
This article provides information on how to develop Java applications to use the Azure Active Directory authentication feature with Microsoft JDBC Driver 6.0 (or higher) for SQL Server.
2424

25-
You can use Azure Active Directory (AAD) authentication which is a mechanism of connecting to Azure SQL Database v12 using identities in Azure Active Directory. Use Azure Active Directory authentication to centrally manage identities of database users and as an alternative to SQL Server authentication. The JDBC Driver allows you to specify your Azure Active Directory credentials in the JDBC connection string to connect to Azure SQL DB. For information on how to configure Azure Active Directory authentication visit [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/).
25+
You can use Azure Active Directory (AAD) authentication, which is a mechanism of connecting to Azure SQL Database v12 using identities in Azure Active Directory. Use Azure Active Directory authentication to centrally manage identities of database users and as an alternative to SQL Server authentication. The JDBC Driver allows you to specify your Azure Active Directory credentials in the JDBC connection string to connect to Azure SQL DB. For information on how to configure Azure Active Directory authentication visit [Connecting to SQL Database By Using Azure Active Directory Authentication](https://azure.microsoft.com/documentation/articles/sql-database-aad-authentication/).
2626

2727
Two new connection properties have been added to support Azure Active Directory Authentication:
28-
* **authentication**: Use this property to indicate which SQL authentication method to use for connection. Possible values are: **ActiveDirectoryIntegrated**, **ActiveDirectoryPassword**, **SqlPassword** and the default **NotSpecified**.
28+
* **authentication**: Use this property to indicate which SQL authentication method to use for connection. Possible values are: **ActiveDirectoryIntegrated**, **ActiveDirectoryPassword**, **SqlPassword**, and the default **NotSpecified**.
2929
* Use 'authentication=ActiveDirectoryIntegrated' to connect to a SQL Database using integrated Windows authentication. To use this authentication mode you need to federate the on-premise Active Directory Federation
30-
Services (ADFS) with Azure AD in the cloud. Once this is setup as well as a Kerberos ticket, you can access Azure SQL DB without being prompted for credentials when you are logged in a domain joined machine.
30+
Services (ADFS) with Azure AD in the cloud. Once this is set up as well as a Kerberos ticket, you can access Azure SQL DB without being prompted for credentials when you are logged in a domain joined machine.
3131
* Use 'authentication=ActiveDirectoryPassword' to connect to a SQL Database using an Azure AD principal name and password.
3232
* Use 'authentication=SqlPassword' to connect to a SQL Server using userName/user and password properties.
33-
* Use 'authentication=NotSpecified' or leave it as default if none of these authentication methods is needed.
33+
* Use 'authentication=NotSpecified' or leave it as default if none of these authentication methods are needed.
3434

3535
* **accessToken**: Use this property to connect to a SQL database using an access token. accessToken can only be set using the Properties parameter of the getConnection() method in the DriverManager class. It cannot be used in the connection URL.
3636

@@ -41,12 +41,14 @@ For details see the authentication property on the [Setting the Connection Prope
4141
Please make sure that the following components are installed on the client machine:
4242
* Java 7 or above
4343
* Microsoft JDBC Driver 6.0 (or higher) for SQL Server
44-
* If you are using the access token based authentication mode, you will need [azure-activedirectory-library-for-java](https://github.com/AzureAD/azure-activedirectory-library-for-java) and its dependencies to run the examples from this article. See **Connecting using Access Token** section for more details.
45-
* If you are using the ActiveDirectoryPassword authentication mode you will need [azure-activedirectory-library-for-java](https://github.com/AzureAD/azure-activedirectory-library-for-java) and its dependencies. See **Connecting using ActiveDirectoryPassword Authentication Mode** section for more details.
46-
* If you are using the ActiveDirectoryIntegrated mode, you will need azure-activedirectory-library-for-java and its dependencies. See **Connecting using ActiveDirectoryIntegrated Authentication Mode** section for more details.
44+
* If you are using the access token-based authentication mode, you need [azure-activedirectory-library-for-java](https://github.com/AzureAD/azure-activedirectory-library-for-java) and its dependencies to run the examples from this article. See **Connecting using Access Token** section for more details.
45+
* If you are using the ActiveDirectoryPassword authentication mode, you need [azure-activedirectory-library-for-java](https://github.com/AzureAD/azure-activedirectory-library-for-java) and its dependencies. See **Connecting using ActiveDirectoryPassword Authentication Mode** section for more details.
46+
* If you are using the ActiveDirectoryIntegrated mode, you need azure-activedirectory-library-for-java and its dependencies. See **Connecting using ActiveDirectoryIntegrated Authentication Mode** section for more details.
4747

4848
## Connecting using ActiveDirectoryIntegrated Authentication Mode
49-
**Note:** As of version 6.4, Microsoft JDBC Driver no longer needs sqljdbc_auth.dll or the Active Directory Authentication Library for SQL Server (ADALSQL.DLL) for ActiveDirectoryIntegrated Authentication. Instead, the driver requires a Kerberos ticket to work with ActiveDirectoryIntegrated Authentication. See **Set Kerberos ticket on Windows, Linux And Mac** for more details.
49+
With version 6.4, Microsoft JDBC Driver adds support for ActiveDirectoryIntegrated Authentication using a Kerberos ticket on multiple platforms (Windows/Linux and Mac).
50+
See **Set Kerberos ticket on Windows, Linux And Mac** for more details. Alternatively, on Windows, sqljdbc_auth.dll can also be used for ActiveDirectoryIntegrated Authentication with JDBC Driver.
51+
**Note:** If you are using an older version of the driver, please check this [link](../../connect/jdbc/dependency.md) for the respective dependencies that are required to use this authentication mode.
5052

5153
The following example shows how to use 'authentication=ActiveDirectoryIntegrated' mode. Run this example on a domain joined machine that is federated with Azure Active Directory. A contained database user representing your Azure AD principal, or one of the groups, you belong to, must exist in the database and must have the CONNECT permission.
5254

@@ -91,7 +93,7 @@ You have successfully logged on as: <your domain user name>
9193

9294
### Set Kerberos ticket on Windows, Linux And Mac
9395

94-
You will need to setup a Kerberos ticket linking your current user to a Windows domain account. A summary of key steps are included below.
96+
You need to set up a Kerberos ticket linking your current user to a Windows domain account. A summary of key steps is included below.
9597

9698
#### Windows
9799
JDK comes with `kinit` which you can use to get a TGT from KDC (Key Distribution Center) on a domain joined machine that is federated with Azure Active Directory.
@@ -193,13 +195,13 @@ You have successfully logged on as: <your user name>
193195
```
194196

195197
> [!NOTE]
196-
> A contained user database must exist and a contained database user representing the specified Azure AD user or one of the groups, the specified Azure AD user belongs to, must exist in the database and must have the CONNECT permission (except for Azure Active Directory server admin or group)
198+
> A contained user database must exist and a contained database user representing the specified Azure AD user or one of the groups, the specified Azure AD user belongs to, must exist in the database, and must have the CONNECT permission (except for Azure Active Directory server admin or group)
197199
198200

199201
## Connecting using Access Token
200202
Applications/services can retrieve an access token from the Azure Active Directory and use that to connect to SQL Azure Database. Note that accessToken can only be set using the Properties parameter of the getConnection() method in the DriverManager class. It cannot be used in the connection string.
201203

202-
The example below contains a simple Java application that connects to Azure SQL Database using access token based authentication. Before building and running the example, perform the following steps:
204+
The example below contains a simple Java application that connects to Azure SQL Database using access token-based authentication. Before building and running the example, perform the following steps:
203205
1. Create an application account in Azure Active Directory for your service.
204206
1. Sign in to the Azure management portal
205207
2. Click on Azure Active Directory in the left hand navigation
@@ -210,15 +212,15 @@ The example below contains a simple Java application that connects to Azure SQL
210212
7. Enter mytokentest as a friendly name for the application, select "Web Application and/or Web API", and click next.
211213
8. Assuming this application is a daemon/service and not a web application, it doesn't have a sign-in URL or app ID URI. For these two fields, enter http://mytokentest
212214
9. While still in the Azure portal, click the Configure tab of your application
213-
10. Find the Client ID value and copy it aside, you will need this later when configuring your application ( i.e. a4bbfe26-dbaa-4fec-8ef5-223d229f647d). See the snapshot below.
215+
10. Find the Client ID value and copy it aside, you need this later when configuring your application (for example, a4bbfe26-dbaa-4fec-8ef5-223d229f647d). See the snapshot below.
214216
11. Under section “Keys”, select the duration of the key, save the configuration, and copy the key for later use. This is the client Secret.
215217
12. On the bottom, click on “view endpoints”, and copy the URL under “OAUTH 2.0 AUTHORIZATION ENDPOINT” for later use. This is the STS URL.
216218

217219

218220
![JDBC_AAD_Token](../../connect/jdbc/media/jdbc_aad_token.png)
219221

220222

221-
2. Logon to your Azure SQL Server’s user database as an Azure Active Directory admin and using a T-SQL command
223+
2. Log on to your Azure SQL Server’s user database as an Azure Active Directory admin and using a T-SQL command
222224
provision a contained database user for your application principal. See the [Connecting to SQL Database or SQL Data Warehouse By Using Azure Active Directory Authentication](https://azure.microsoft.com/en-us/documentation/articles/sql-database-aad-authentication/)
223225
for more details on how to create an Azure Active Directory admin and a contained database user.
224226

‎docs/connect/jdbc/dependency.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,16 +23,16 @@ ms.workload: "On Demand"
2323
# Feature dependencies of Microsoft JDBC Driver for SQL Server
2424
[!INCLUDE[Driver_JDBC_Download](../../includes/driver_jdbc_download.md)]
2525

26-
This project has the following dependencies :
26+
This project has the following dependencies:
2727

2828
#### Compile Time:
2929
- `azure-keyvault` : Azure Key Vault Provider for Always Encrypted Azure Key Vault feature (optional)
3030
- `adal4j` : Azure ActiveDirectory Library for Java for Azure Active Directory Authentication feature and Azure Key Vault feature (optional)
3131

3232
#### Test Time:
33-
Specific projects that require either of the above two features will need to explicitly declare the respective dependencies in their pom file:
33+
Specific projects that require either of the above two features need to explicitly declare the respective dependencies in their pom file:
3434

35-
***For Example:*** If you are using *Azure Active Directory Authentication feature* then you need to redeclare *adal4j* dependency in your project's pom file. Please see the following snippet:
35+
***For Example:*** If you are using *Azure Active Directory Authentication feature*, then you need to redeclare *adal4j* dependency in your project's pom file. Please see the following snippet:
3636
```xml
3737
<dependency>
3838
<groupId>com.microsoft.sqlserver</groupId>
@@ -77,16 +77,16 @@ Specific projects that require either of the above two features will need to exp
7777
- Dependency versions: Azure-Keyvault (version 0.9.7), Adal4j (version 1.3.0) and their dependencies ( [Sample application](../../connect/jdbc/AKVSample6.0.0.md))
7878
- JDBC Driver version 6.2.2 and above (including the latest 6.4.0)
7979
- Dependency versions: Azure-Keyvault (version 1.0.0), Adal4j (version 1.4.0) and their dependencies ([Sample Application](../../connect/jdbc/AKVSample6.4.0.md))
80-
- **Note:** As of v6.2.2, the azure-keyvault-java dependency is updated to version 1.0.0. However, the new version is not compatible with the previous version (version 0.9.7) and therefore breaks the existing implementation in the driver. The new implementation in the driver requires API changes which in turn break client programs that use the Azure Key Vault feature.
80+
- **Note:** As of v6.2.2, the azure-keyvault-java dependency is updated to version 1.0.0. However, the new version is not compatible with the previous version (version 0.9.7) and therefore breaks the existing implementation in the driver. The new implementation in the driver requires API changes, which in turn break client programs that use the Azure Key Vault feature.
8181

8282

8383
#### Azure Active Directory Authentication:
8484
- JDBC Driver version 6.0.0
85-
- Dependency versions: Adal4j (version 1.3.0) and its dependencies
85+
- Dependency versions: Adal4j (version 1.3.0), and its dependencies
8686
- In this version of the driver, you can connect using *ActiveDirectoryIntegrated* Authentication Mode only on a Windows operating system and using sqljdbc_auth.dll and Active Directory Authentication Library for SQL Server (ADALSQL.DLL).
8787
- JDBC Driver version 6.4.0
8888
- Dependency versions: Adal4j (version 1.4.0) and its dependencies
89-
- In this version of the driver, your application does not require using ADALSQL.DLL. Depending on the operating systems. For **Non-Windows operating systems**, the driver requires Kerberos ticket to work with ActiveDirectoryIntegrated Authentication. See **Set Kerberos ticket on Windows, Linux And Mac** for more details. For **Windows operating systems**, driver by default will check if sqljdbc_auth.dll is loaded and does not require Kerberos ticket setup or adal4j dependency . However, If sqljdbc_auth.dll is not loaded, driver behaves the same way as non-Windows operating systems and would require setup which is described in the following example.
89+
- In this version of the driver, your application does not require using ADALSQL.DLL. Depending on the operating systems. For **Non-Windows operating systems**, the driver requires Kerberos ticket to work with ActiveDirectoryIntegrated Authentication. See **Set Kerberos ticket on Windows, Linux And Mac** for more details. For **Windows operating systems**, driver by default checks if sqljdbc_auth.dll is loaded and does not require Kerberos ticket setup or adal4j dependency. However, If sqljdbc_auth.dll is not loaded, driver behaves the same way as non-Windows operating systems and would require setup which is described in the following example.
9090
A sample application using this feature can be found [here](../../connect/jdbc/connecting-using-azure-active-directory-authentication.md).
9191
## See Also
9292
[JDBC Driver GitHub Repository](https://github.com/microsoft/mssql-jdbc)

‎docs/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ ms.workload: "Active"
2424
![Download-DownArrow-Circled](../../ssdt/media/download.png)[To download JDBC driver](../sql-connection-libraries.md#anchor-20-drivers-relational-access)
2525

2626
## Using the JDBC Driver with Maven Central
27-
The JDBC Driver can be added to a Maven project by adding it as a dependency in the POM.xml file with the code below:
27+
The JDBC Driver can be added to a Maven project by adding it as a dependency in the POM.xml file with the following code:
2828

2929
```xml
3030
<dependency>
@@ -35,13 +35,14 @@ The JDBC Driver can be added to a Maven project by adding it as a dependency in
3535
```
3636

3737
## Download previous versions of JDBC Drivers for SQL Server
38+
* [Microsoft JDBC Driver 6.4 for SQL Server](http://go.microsoft.com/fwlink/?linkid=868290)
3839
* [Microsoft JDBC Driver 6.2 for SQL Server](http://go.microsoft.com/fwlink/?linkid=852460)
3940
* [Microsoft JDBC Driver 6.0 for SQL Server](http://go.microsoft.com/fwlink/?LinkId=245496)
4041
* [Microsoft JDBC Driver 4.2 for SQL Server](http://go.microsoft.com/fwlink/?linkid=841534)
4142
* [Microsoft JDBC Driver 4.1 for SQL Server](http://go.microsoft.com/fwlink/?linkid=841533)
4243
* [Microsoft JDBC Driver 4.0 for SQL Server](http://go.microsoft.com/fwlink/?linkid=841532)
4344

4445
## Unsupported Drivers
45-
Unsupported driver versions are not available for download here. We are continually improving our Java connectivity support. As such we highly recommend that you work with the latest version of our JDBC driver.
46+
Unsupported driver versions are not available for download here. We are continually improving the Java connectivity support. As such we highly recommend that you work with the latest version of Microsoft JDBC driver.
4647

4748

‎docs/connect/jdbc/fips-mode.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ Use the following snippet to import the SSL certificate and store it in a workin
7474
````
7575

7676

77-
In the following example, we are importing an Azure SSL Certificate in PKCS12 format with BouncyCastle Provider. The certificate is imported in the working directory named _MyTrustStore_PKCS12_ by using the following snippet:
77+
The following example is importing an Azure SSL Certificate in PKCS12 format with BouncyCastle Provider. The certificate is imported in the working directory named _MyTrustStore_PKCS12_ by using the following snippet:
7878

7979
` saveGenericKeyStore(BCFIPS, PKCS12, "SQLAzure SSL Certificate Name", "SQLAzure.cer"); `
8080

@@ -89,7 +89,7 @@ In order to run the JDBC Driver in FIPS-compliant mode, configure connection pro
8989
|Property|Type|Default|Description|Notes|
9090
|---|---|---|---|---|
9191
|encrypt|boolean ["true / false"]|"false"|For FIPS enabled JVM encrypt property should be **true**||
92-
|TrustServerCertificate|boolean ["true / false"]|"false"|For FIPS we need to validate certificate chain, so we should use **"false"** value for this property. ||
92+
|TrustServerCertificate|boolean ["true / false"]|"false"|For FIPS, the user needs to validate certificate chain, so the user should use **"false"** value for this property. ||
9393
|trustStore|String|null|Your Java Keystore file path where you imported your certificate. If you install certificate on your system, then no need to pass anything. Driver uses cacerts or jssecacerts files.||
9494
|trustStorePassword|String|null|The password used to check the integrity of the trustStore data.||
9595
|fips|boolean ["true / false"]|"false"|For fips enabled JVM this property should be **true**|Added in 6.1.4 (Stable release 6.2.2)||

0 commit comments

Comments
 (0)