Authentication settings for the Databricks JDBC Driver

The Databricks JDBC Driver supports multiple authentication methods depending on your use case. This page describes how to configure each method and lists the required connection properties.

To configure authentication for the Databricks JDBC Driver, use one of the following methods:

• OAuth 2.0 token pass-through (including token federation with external identity providers)
• OAuth user-to-machine (U2M) authentication
• OAuth machine-to-machine (M2M) authentication
• Databricks personal access token

OAuth 2.0 token pass-through

The JDBC driver accepts OAuth tokens in the Auth_AccessToken property. You can pass either a Databricks OAuth token directly, or a JSON Web Token (JWT) from an external identity provider. If you pass an external IdP token, Databricks automatically exchanges it for a Databricks token using token federation.

In the following examples, replace the following placeholders:

• <oauth-token> with a Databricks OAuth 2.0 token or an external IdP JWT.
• To get the values for <server-hostname> and <http-path>, see Configure a connection to Databricks using the Databricks JDBC Driver.

The required properties are:

• AuthMech set to 11 (OAuth 2.0 authentication)
• Auth_Flow set to 0 (token pass-through mode)
• Auth_AccessToken set to a Databricks OAuth token or an external IdP JWT

See Authentication properties.

For a JDBC connection URL:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>

In Java code:

Java

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "0");
p.put("Auth_AccessToken", "<oauth-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Token federation with an external identity provider

If you authenticate with a token from an external identity provider such as Okta, Microsoft Entra ID, Keycloak, or any OIDC-compliant IdP, Databricks performs the token exchange automatically. The JDBC configuration is the same as token pass-through. Pass the IdP token in Auth_AccessToken and the driver handles the rest.

Before using token federation, you must:

1. Create a federation policy in your Databricks account that trusts the external IdP. A federation policy specifies the issuer URL, expected audience values, and the JWT claim used to map to a Databricks user. See Authenticate access to Databricks using OAuth token federation.
2. Verify that a matching Databricks user exists. The user's email or other identifier must match the subject_claim value in the JWT.
3. Verify that the IdP's OIDC discovery endpoint is publicly reachable so Databricks can fetch signing keys to verify the token.

OAuth user-to-machine (U2M) authentication

OAuth U2M authentication lets you sign in to Databricks through a browser. The driver opens a browser window, you authenticate, and the driver receives an OAuth token. The driver uses the built-in OAuth client ID databricks-sql-jdbc.

This authentication type has no prerequisites. Tokens have a default lifetime of one hour and refresh automatically when they expire.

note

OAuth U2M works only with locally run applications. It doesn't work with server-based or cloud-based applications.

In the following examples, replace the following placeholders:

• <passphrase> with a passphrase of your choice. The driver uses this key for refresh token encryption.
• To get the values for <server-hostname> and <http-path>, see Configure a connection to Databricks using the Databricks JDBC Driver.

The required properties are:

• AuthMech set to 11 (OAuth 2.0 authentication)
• Auth_Flow set to 2 (U2M browser-based mode)
• TokenCachePassPhrase set to the passphrase used to encrypt your cached OAuth U2M credentials. This prevents repeated browser-based authentications. To opt out of token caching, set EnableTokenCache to 0.

See Authentication properties.

In a JDBC connection URL:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=2;TokenCachePassPhrase=<passphrase>;EnableTokenCache=0

In Java code:

Java

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "2");
p.put("TokenCachePassPhrase", "<passphrase>");
p.put("EnableTokenCache", "0");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

OAuth machine-to-machine (M2M) authentication

The JDBC driver supports OAuth machine-to-machine (M2M) authentication using a Databricks service principal, also called OAuth 2.0 client credentials authentication. See Authorize service principal access to Databricks with OAuth.

To configure M2M authentication:

1. Create a Databricks service principal in your Databricks workspace. See Authorize service principal access to Databricks with OAuth.
2. Create an OAuth secret for the service principal. Note the UUID or Application ID and the Secret value.
3. Give the service principal access to your cluster or warehouse. See Compute permissions or Manage a SQL warehouse.

In the following examples, replace the following placeholders:

• <service-principal-application-id> with the service principal's UUID or Application ID.
• <service-principal-oauth-secret> with the service principal's OAuth Secret.
• To get the values for <server-hostname> and <http-path>, see Configure a connection to Databricks using the Databricks JDBC Driver.

The required properties are:

• AuthMech set to 11 (OAuth 2.0 authentication)
• Auth_Flow set to 1 (M2M client credentials mode)
• OAuth2ClientID set to the service principal's UUID or Application ID value
• OAuth2Secret set to the service principal's OAuth Secret value

See Authentication properties.

In a JDBC connection URL:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=11;Auth_Flow=1;OAuth2ClientId=<service-principal-application-id>;OAuth2Secret=<service-principal-oauth-secret>

In Java code:

Java

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "11");
p.put("Auth_Flow", "1");
p.put("OAuth2ClientId", "<service-principal-application-id>");
p.put("OAuth2Secret", "<service-principal-oauth-secret>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...

Databricks personal access token

note

Personal access tokens are best for testing scenarios. Databricks recommends more secure authentication types for production scenarios.

To create a Databricks personal access token, follow the steps in Create personal access tokens for workspace users.

In the following examples, replace the following placeholders:

• <personal-access-token> with the Databricks personal access token for your workspace user.
• To get the values for <server-hostname> and <http-path>, see Configure a connection to Databricks using the Databricks JDBC Driver.

The required properties are:

• AuthMech set to 3 (token authentication)
• UID set to the literal string token
• PWD or password set to your Databricks personal access token value

See Authentication properties.

In a JDBC connection URL:

jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;AuthMech=3;UID=token;PWD=<personal-access-token>

In Java code:

Java

// ...
String url = "jdbc:databricks://<server-hostname>:443";
Properties p = new java.util.Properties();
p.put("httpPath", "<http-path>");
p.put("AuthMech", "3");
p.put("UID", "token");
p.put("PWD", "<personal-access-token>");
// ...
Connection conn = DriverManager.getConnection(url, p);
// ...