Authenticate to database instance
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 obtain an OAuth token from the Lakebase database instance and use it to authenticate to the database instance. An OAuth token is needed if you are connecting to your database from psql or a notebook.
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.
Considerations before you begin
-
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
As the database owner, you can obtain an OAuth token from the UI. 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:
- From the Database instance details page, click Get OAuth Token. A flag indicates when the token has been created.
- Click Copy OAuthToken to copy the token to your clipboard. You must substitute this value into the provided connection string in the next step.
- Click the copy icon that follows the provided Connection string.
Alternatively, if you would like to use Databricks CLI to obtain an OAuth token, see OAuth user-to-machine (U2M) authentication.
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.
- Configure a service principal with indefinitely lived credentials. For instructions, see Authorize unattended access to Databricks resources with a service principal using OAuth.
- Mint new OAuth tokens as the service principal over REST. For instructions, see Manually generate a workspace-level access token.
- 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.
Next steps
After obtaining an OAuth token, you can connect to your database instance: