Skip to main content

About authentication

Beta

Lakebase Postgres (Autoscaling Beta) is the next version of Lakebase, available for evaluation only. For production workloads, use Lakebase Public Preview. See choosing between versions to understand which version is right for you.

Learn how authentication works in Lakebase database projects. For step-by-step connection instructions, see Connection overview.

Overview​

Lakebase supports two authentication methods, each designed for different use cases:

OAuth token authentication: Uses Databricks identities with time-limited OAuth tokens. Best for:

  • Interactive sessions where you can refresh tokens
  • Workspace-integrated workflows
  • When you want authentication managed by Databricks

Native Postgres password authentication: Uses traditional Postgres roles with passwords. Best for:

  • Applications that cannot refresh credentials hourly
  • Long-running processes
  • Tools that don't support token rotation
note

Databricks identities and Postgres roles are separate systems with no automatic synchronization. To allow a Databricks identity to access the database through Postgres, you must create a corresponding Postgres role. See Create and manage Postgres roles.

Connection timeouts​

All database connections are subject to the following limits regardless of authentication method:

  • 24-hour idle timeout: Connections with no activity for 24 hours are automatically closed.
  • 3-day maximum connection life: Connections that have been alive for more than 3 days may be closed regardless of activity.

Design your applications to handle connection timeouts gracefully by implementing connection retry logic with appropriate timeout settings.

OAuth token authentication​

OAuth token authentication allows you to connect using your Databricks identity. You generate a time-limited OAuth token from the Lakebase UI and use it as a password when connecting to Postgres.

The project owner's OAuth role is created automatically. To enable OAuth authentication for other Databricks identities, you must create their Postgres roles using the databricks_auth extension and SQL. See Create an OAuth role for a DB identity using SQL.

How OAuth tokens work​

  • Token lifetime: OAuth tokens expire after one hour.
  • Expiration enforcement: Token expiration is enforced only at login. Open connections remain active even after the token expires.
  • Re-authentication: Any Postgres query or command fails if the token has expired.
  • Token refresh: For interactive sessions, generate a new token from the UI when needed.

Requirements and limitations​

  • Corresponding Postgres role required: Your Databricks identity must have a corresponding Postgres role. The project owner's role is created automatically. For other Databricks identities, create their roles using the databricks_auth extension.
  • Workspace scoping: OAuth tokens are workspace-scoped and must belong to the same workspace that owns the database project. Cross-workspace token authentication is not supported.
  • SSL required: Token-based authentication requires SSL connections. All clients must be configured to use SSL (typically sslmode=require).

Getting an OAuth token​

OAuth tokens can be obtained from the Lakebase UI. For detailed instructions, see Connect with an OAuth role.

Postgres password authentication​

Native Postgres password authentication uses traditional Postgres roles with passwords. Unlike OAuth tokens, these passwords do not expire after one hour, making them suitable for applications that cannot handle frequent credential rotation.

When to use Postgres passwords​

Use Postgres password authentication when:

  • Your application or tool cannot refresh credentials every hour
  • You have long-running processes that need stable credentials
  • Your client library doesn't support OAuth token rotation
  • You need traditional database authentication for compatibility

How Postgres passwords work​

  • Password lifetime: Passwords do not expire automatically
  • No workspace integration: Authentication is handled by Postgres, not Databricks workspace authentication
  • Manual management: Passwords must be manually rotated and distributed to users
  • Connection timeouts still apply: Even though passwords don't expire, connections are still subject to 24-hour idle timeout and 7-day maximum connection life

Security considerations​

  • Password storage: Store passwords securely using environment variables or secrets management systems
  • SSL required: All connections must use SSL (sslmode=require)
  • Password distribution: You receive the password only once when creating the role. Store it securely

Next steps​

Last updated on