Authenticate to a database instance

This page describes how to authenticate to a Lakebase database instance. There are two ways to authenticate:

1. Obtain an OAuth token and authenticate using Azure Databricks identities.
2. Use native Postgres roles with passwords.

Authenticate with Azure Databricks identities

When you authenticate as a Azure Databricks identity, you need to generate an OAuth token and use it as a password when connecting to Postgres.

Considerations before you begin

• OAuth tokens expire after one hour, but expiration is enforced only at login. Open connections remain active even if the token expires. However, any PostgreSQL command that requires authentication fails if the token has expired.

• OAuth tokens used for Postgres authentication are workspace-scoped and should belong to the same workspace that owns the database instance. Cross-workspace token authentication is not supported. To learn more about authentication, see Authentication for the Databricks CLI.

• Token-based authentication requires a plaintext password, so only SSL connections are allowed. Ensure that the client library you use to access Postgres with token-based authentication is configured to establish an SSL connection.

Obtain an OAuth token in a user-to-machine flow

If you are a database owner, admin, or your Azure Databricks identity has a corresponding Postgres role for the database instance, you can obtain an OAuth token from the UI, the Databricks CLI, or one of the Databricks SDKs. You can restrict the scope of the token appropriately using the Databricks CLI.

For other Azure Databricks identity users, see Authorize user access to Azure Databricks with OAuth for the workspace-level authorization instructions to obtain OAuth tokens.

UI

When your database instance Status is Available, use the Azure Databricks UI to obtain an OAuth token:

1. From the Database instance details page, click Get OAuth Token. A flag indicates when the token has been created.
2. Click Copy OAuthToken to copy the token to your clipboard. You must substitute this value into the provided connection string in the next step.
3. Click the copy icon that follows the provided Connection string.

CLI

When your database instance Status is Available, use the Databricks CLI v0.256.0 and later to obtain an OAuth token:

1. Use the following command to fetch a token.

    databricks database generate-database-credential \
      --request-id $(uuidgen) \
      --json '{
        "instance_names": ["db-instance-name"]
      }'
   

2. This generates a response in the following format. Copy the token from the response.

   {
     "expiration_time": "2025-08-24T14:15:22Z",
     "token": "<string>"
   }
   

For more information about using the Databricks CLI to obtain an OAuth token, see OAuth user-to-machine (U2M) authentication.

Python SDK

You can generate an OAuth token using the Databricks SDK for Python. Azure Databricks SDK bindings are available in Databricks SDK for Python version v0.56.0.

If you are running with an older version of the SDK, run these commands first.

%pip install --upgrade databricks-sdk
%restart_python

The Databricks SDK for Python generates a secure OAuth token, cred, for your database instance. Enter your credentials where needed.

from databricks.sdk import WorkspaceClient
import uuid

w = WorkspaceClient()

instance_name = "<YOUR INSTANCE>"

cred = w.database.generate_database_credential(request_id=str(uuid.uuid4()), instance_names=[instance_name])

Java SDK

You can generate an OAuth token using the Databricks SDK for Java. Database SDK bindings are available in Databricks SDK for Java version v0.53.0 or above. If you are running with an older version of the SDK, you might need to refresh the imported SDK. For more information, see here.

%scala

import com.databricks.sdk.WorkspaceClient
import com.databricks.sdk.service.database.GetDatabaseInstanceRequest
import com.databricks.sdk.service.database.GenerateDatabaseCredentialRequest
import com.databricks.sdk.service.database.DatabaseInstance
import com.databricks.sdk.service.database.DatabaseCredential
import java.util.Collections
import java.util.UUID

val w = new WorkspaceClient()

val instanceName = "<YOUR INSTANCE>"

// Generate database credential
val cred = w.database().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setRequestId(UUID.randomUUID().toString())
        .setInstanceNames(Collections.singletonList(instanceName))
)

// Print out credential details
System.out.println("Credential: " + cred.getToken())

Obtain an OAuth token in a machine-to-machine flow

To enable secure, automated (machine-to-machine) access to the database instance, you must obtain an OAuth token using a Azure Databricks service principal. This process involves configuring the service principal, generating credentials, and minting OAuth tokens for authentication.

1. Configure a service principal with indefinitely lived credentials. For instructions, see Authorize service principal access to Azure Databricks with OAuth.

2. Mint new OAuth tokens as the service principal.

   CLI

   When your database instance Status is Available, use the Databricks CLI v0.256.0 and later to obtain an OAuth token:

   1. Use the following command to fetch a token.

        databricks database generate-database-credential \
          --request-id $(uuidgen) \
          --json '{
            "instance_names": ["db-instance-name"]
          }'
      

   2. This generates a response in the following format. Copy the token from the response.

      {
        "expiration_time": "2025-08-24T14:15:22Z",
        "token": "<string>"
      }
      

   Python SDK

   You can generate an OAuth token using the Databricks SDK for Python. Azure Databricks SDK bindings are available in Databricks SDK for Python version v0.56.0.

   If you are running with an older version of the SDK, run these commands first.

   %pip install --upgrade databricks-sdk
   %restart_python
   

   The Databricks SDK for Python generates a secure OAuth token, cred, for your database instance. Enter your database instance name where needed.

   from databricks.sdk import WorkspaceClient
   import uuid
   
   w = WorkspaceClient(
     host          = "https://<YOUR WORKSPACE URL>/",
     client_id     = "<YOUR SERVICE PRINCIPAL ID>",
     client_secret = "REDACTED"
   )
   
   instance_name = "<YOUR INSTANCE>"
   
   cred = w.database.generate_database_credential(request_id=str(uuid.uuid4()), instance_names=[instance_name])
   

   Java SDK

   You can generate an OAuth token using the Databricks SDK for Java. Database SDK bindings are available in Databricks SDK for Java version v0.53.0 or above. If you are running with an older version of the SDK, you might need update to a newer SDK. For more information, see here.

   %scala
   
   import com.databricks.sdk.WorkspaceClient
   import com.databricks.sdk.core.DatabricksConfig
   import com.databricks.sdk.service.database.GetDatabaseInstanceRequest
   import com.databricks.sdk.service.database.GenerateDatabaseCredentialRequest
   import com.databricks.sdk.service.database.DatabaseInstance
   import com.databricks.sdk.service.database.DatabaseCredential
   import java.util.Collections
   import java.util.UUID
   
   val config = new DatabricksConfig() // See https://github.com/databricks/databricks-sdk-java#authentication
   val w = new WorkspaceClient(config)
   
   val instanceName = "<YOUR INSTANCE>"
   
   // Generate database credential
   val cred = w.database().generateDatabaseCredential(
       new GenerateDatabaseCredentialRequest()
           .setRequestId(UUID.randomUUID().toString())
           .setInstanceNames(Collections.singletonList(instanceName))
   )
   
   // Print out credential details
   System.out.println("Credential: " + cred.getToken())
   

Troubleshoot token identity

If your token's identity does not match the security label, you might receive a error message like the following.

A valid oauth token was supplied but the token's identity "<USER>" did not match the security label configured for role "<SERVICE PRINCIPAL>". Please ensure that the token is generated for the correct databricks identity.

Run the following command to check which Azure Databricks identity is returned:

CLI

databricks current-user me

Python SDK

w.current_user.me().user_name

Java SDK

w.currentUser.me().getUserName()

If the expected identity is not returned, verify that the correct credentials were used when initializing the workspace client.

Authenticate with Microsoft Entra ID

For Azure Databricks, Microsoft Entra ID identities and tokens can also be used to authenticate to Azure Databricks APIs. Use these APIs to obtain a token to authenticate to Postgres.

See Manage users, service principals, and groups for how to manage Microsoft Entra ID managed identities in Azure Databricks. Users, groups, and service principals from Microsoft Entra ID can be created in Azure Databricks. Once these identities are added to Azure Databricks, you can add them to the database instance as described in Manage Postgres roles.

To retrieve Microsoft Entra ID tokens, see the following:

• Get Microsoft Entra ID tokens for Users.
• Get Microsoft Entra ID tokens for service principals

Authenticate as Azure Databricks group

Groups and group memberships are not synced from Azure Databricks into Postgres and neither are Unity Catalog permissions. However, after a Azure Databricks group is added into Postgres, any Azure Databricks user in the group can log in as the group using the user's password. This allows you to manage permissions at the group level in Postgres. Any direct or indirect member (user or service principal) of the Azure Databricks group identity can authenticate to Postgres and log in as the Azure Databricks group Postgres role.

When authenticating as a group identity using a user or service principal token, group membership is validated only at the time of authentication. Any open connection with a group member token remains open if the member is removed from the group after authentication. Any new connection request from a removed group member is rejected during authentication.

export PGPASSWORD='<OAuth token of a group member>'
export GROUPROLENAME=<pg-case-sensitive-group-role-name>

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUPROLENAME

Only groups assigned to the Azure Databricks workspace of the database instance are supported for group-based Postgres login. To learn how to assign a group to a workspace, see Assign a group to a workspace.

Authenticate with Postgres roles and passwords

If you have clients that do not support credential rotation after one hour, you can create native Postgres roles with passwords:

1. Click Compute in the workspace sidebar.

2. Click the Database instances tab.

3. Select the database instance you want to update.

4. Click Edit in the upper-right.

5. Turn on Enable Postgres Native Role Login.

6. Click Save.

7. Log into Postgres, or use the SQL Editor, to create a role with a password.

   CREATE ROLE new_role LOGIN PASSWORD 'your strong password';
   

8. Grant additional Postgres permissions to the new role. See grant privileges to Postgres roles using PostgreSQL.

Next steps

After obtaining a credential (OAuth token or password), you can connect to your database instance:

• Access a database instance from SQL clients
• Use a notebook to access a database instance