Share via

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

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

In the following examples, replace the following placeholders:

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 Azure 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:

// ...
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, Azure 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 Azure 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 an Azure Databricks user. See Authenticate access to Azure Databricks using OAuth token federation.
  2. Verify that a matching Azure 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 Azure Databricks can fetch signing keys to verify the token.

OAuth user-to-machine (U2M) authentication

OAuth U2M authentication lets you sign in to Azure 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:

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:

// ...
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 one of the following principals or identity. See Authorize service principal access to Azure Databricks with OAuth.

M2M using Databricks managed service principal

To configure authentication using a Databricks managed service principal:

  1. Create a Databricks managed service-principal and assign it to Databricks accounts and workspaces.

  2. Create a Databricks OAuth secret for the service principal. See Manually generate OAuth M2M access tokens.

  3. Grant access permissions to clusters and SQL warehouses.

  4. Add the following properties to your existing JDBC connection URL or java.util.Properties object:

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

    See Authentication properties.

M2M using Azure managed service principal

To configure authentication using an Azure managed service principal:

  1. Create a Databricks OAuth secret for the service principal. See Manually generate OAuth M2M access tokens.

  2. Grant access permissions to clusters and SQL warehouses.

  3. Add the following properties to your existing JDBC connection URL or java.util.Properties object:

    • AuthMech set to 11 (OAuth 2.0 authentication)
    • Auth_Flow set to 1 (M2M client credentials mode)
    • OAuth2ClientID set to the service principal's Application (client) ID value
    • AzureTenantID set to the Azure tenant ID found in Azure Active Directory
    • OAuth2Secret set to the service principal's Databricks OAuth secret

    See Authentication properties.

M2M using Azure managed identities

To configure authentication using Azure managed identities:

  1. Configure managed identities for your Azure resources.

  2. Grant access permissions to clusters and SQL warehouses.

  3. Add the following properties to your existing JDBC connection URL or java.util.Properties object:

    • AuthMech set to 11 (OAuth 2.0 authentication)
    • Auth_Flow set to 3 (managed identity mode)
    • OAuth2ClientID set to the Client ID of the managed identity. This is required only if you're using a user-assigned managed identity.
    • Azure_workspace_resource_id set to your Databricks workspace's Azure Resource ID

    See Authentication properties.

Databricks personal access token

Note

Personal access tokens are best for testing scenarios. Azure 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:

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:

// ...
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);
// ...
  • Last updated on