Skip to main content

Authenticate to database instance

Preview

This feature is in Public Preview in the following regions: us-east-1, , us-east-2, us-west-21, eu-west-2, ap-southeast-1, ap-southeast-2, eu-central-1, ap-south-1.

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 Databricks identities.
  2. Use native Postgres roles with passwords.

Authenticate with Databricks identities​

When you authenticate as a 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 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 Databricks identity users, see Authorize interactive access to Databricks resources with a user account using OAuth for the workspace-level authorization instructions to obtain OAuth tokens.

When your database instance Status is Available, use the 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.

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 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 unattended access to Databricks resources with a service principal using OAuth.
  2. Mint new OAuth tokens as the service principal.

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.
    Bash
     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.
    JSON
    {
      "expiration_time": "2025-08-24T14:15:22Z",
      "token": "<string>"
    }
note

Rotate OAuth tokens before hourly expiration:

  • Check the expiration time of the OAuth token on each use and refresh when needed.
  • Alternatively, set up a background thread to refresh the current OAuth token periodically.

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.

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

Last updated on