Skip to main content

Authenticate to a database instance

Preview

This feature is in Public Preview in the following regions: us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-southeast-2, eu-central-1, us-east-2, 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 user access to Databricks with 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 service principal access to Databricks with 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 as Databricks group​

Groups and group memberships are not synced from Databricks into Postgres and neither are Unity Catalog permissions. However, after a Databricks group is added into Postgres, any 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 Databricks group identity can authenticate to Postgres and log in as the Databricks group Postgres role.

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

Bash
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 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.

    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