Skip to main content

Authenticate to 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 interactive access to Databricks resources with a user account using OAuth for the workspace-level authorization instructions to obtain OAuth tokens.

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

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
%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())
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