About authentication

Important

Lakebase Autoscaling is in Beta in the following regions: eastus2, westeurope, westus.

Lakebase Autoscaling is the latest version of Lakebase with autoscaling compute, scale-to-zero, branching, and instant restore. For feature comparison with Lakebase Provisioned, see choosing between versions.

Learn how to authenticate database connections to Lakebase Postgres. For step-by-step connection instructions, see Quickstart.

Overview

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

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

Interactive sessions where you can refresh tokens
Workspace-integrated workflows
Applications that can implement token rotation
When you want authentication managed by Azure 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

Platform management vs database access: This page focuses on database authentication (OAuth tokens and Postgres passwords for connecting to your database). For platform management authentication (creating projects, branches, computes), see Project permissions.

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 Azure 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 Azure 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. For applications with long-running connections, implement token rotation to automatically refresh credentials.

Requirements and limitations

Corresponding Postgres role required: Your Azure Databricks identity must have a corresponding Postgres role. The project owner's role is created automatically. For other Azure 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 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).

Obtain an OAuth token in a user-to-machine flow

If you are a database owner, admin, or your Azure Databricks identity has a corresponding Postgres role for the database, you can obtain an OAuth token from the UI, the Databricks API, CLI, or one of the Databricks SDKs.

For other Azure Databricks identity users, see Authorize user access to Azure Databricks with OAuth for the workspace-level authorization instructions to obtain OAuth tokens.

UI

When using SQL clients like psql or DBeaver, use the Lakebase UI to generate tokens:

Navigate to your project in the Lakebase App.
Select the branch and compute you want to connect to.
Click Connect and follow the instructions to generate an OAuth token.

See Connect with an OAuth role for complete instructions.

CLI

# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

Response:

{
  "token": "eyJraWQiOiI1NDdkNjFjNzQ2YTk3M2Q3M2ViNjM2YWRiMWY2Nz...",
  "expire_time": "2026-01-22T17:07:00Z"
}

Use the token value as the password when connecting to your database.

Python SDK

You can generate an OAuth token using the Databricks SDK for Python.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

# Generate OAuth token for database connection (1-hour expiration)
credential = w.postgres.generate_database_credential(
    endpoint="projects/my-project/branches/production/endpoints/my-compute"
)

print(f"Token: {credential.token}")
print(f"Expires: {credential.expire_time}")

# Use the token to connect to Postgres
import psycopg2

conn = psycopg2.connect(
    host="ep-example.database.region.databricks.com",
    port=5432,
    database="postgres",
    user="your.email@company.com",
    password=credential.token,
    sslmode="require"
)

Java SDK

You can generate an OAuth token using the Databricks SDK for Java.

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;

WorkspaceClient w = new WorkspaceClient();

// Generate OAuth token for database connection (1-hour expiration)
DatabaseCredential credential = w.postgres().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setEndpoint("projects/my-project/branches/production/endpoints/my-compute")
);

System.out.println("Token: " + credential.getToken());
System.out.println("Expires: " + credential.getExpireTime());

Obtain an OAuth token in a machine-to-machine flow

To enable secure, automated (machine-to-machine) access to the database, you must obtain an OAuth token using a Azure 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 service principal access to Azure Databricks with OAuth.

Mint new OAuth tokens as the service principal.

CLI

# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

Response:

{
  "token": "eyJraWQiOiI1NDdkNjFjNzQ2YTk3M2Q3M2ViNjM2YWRiMWY2Nz...",
  "expire_time": "2026-01-22T17:07:00Z"
}

Use the token value as the password when connecting to your database.

Python SDK

You can generate an OAuth token using the Databricks SDK for Python.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
    host="https://<YOUR WORKSPACE URL>/",
    client_id="<YOUR SERVICE PRINCIPAL ID>",
    client_secret="REDACTED"
)

# Generate OAuth token for database connection (1-hour expiration)
credential = w.postgres.generate_database_credential(
    endpoint="projects/my-project/branches/production/endpoints/my-compute"
)

print(f"Token: {credential.token}")
print(f"Expires: {credential.expire_time}")

Java SDK

You can generate an OAuth token using the Databricks SDK for Java.

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
import com.databricks.sdk.service.postgres.*;

// Initialize with service principal credentials
DatabricksConfig config = new DatabricksConfig()
    .setHost("https://<YOUR WORKSPACE URL>/")
    .setClientId("<YOUR SERVICE PRINCIPAL ID>")
    .setClientSecret("REDACTED");

WorkspaceClient w = new WorkspaceClient(config);

// Generate OAuth token for database connection (1-hour expiration)
DatabaseCredential credential = w.postgres().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setEndpoint("projects/my-project/branches/production/endpoints/my-compute")
);

System.out.println("Token: " + credential.getToken());
System.out.println("Expires: " + credential.getExpireTime());

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.

Token rotation examples

Because OAuth tokens expire after one hour, applications that maintain long-running database connections must implement token rotation to refresh credentials periodically. The following examples demonstrate how to automatically rotate tokens in your application code.

Note

Requirements for these examples:

You must be authenticated to the workspace that owns the project. The WorkspaceClient() uses your workspace OAuth credentials to generate database tokens.
Your Azure Databricks identity must be a member of the workspace where the project was created.
Get your connection parameters (host, database, endpoint) from the Connect dialog in the Lakebase App. See Quickstart for details.
The endpoint parameter uses the format: projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}

For workspace authentication setup, see Authorize user access to Azure Databricks with OAuth or Authorize service principal access to Azure Databricks with OAuth.

Python: psycopg3

This example uses psycopg3's connection pool with a custom connection class that generates a fresh OAuth token every time a new connection is created. This approach ensures each connection from the pool always has a valid, current token.

%pip install "psycopg[binary,pool]"

from databricks.sdk import WorkspaceClient

import psycopg
from psycopg_pool import ConnectionPool

w = WorkspaceClient()

class CustomConnection(psycopg.Connection):
    global w
    def __init__(self, *args, **kwargs):
        # Call the parent class constructor
        super().__init__(*args, **kwargs)

    @classmethod
    def connect(cls, conninfo='', **kwargs):
        # Generate a fresh OAuth token for each connection
        endpoint = "projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        kwargs['password'] = credential.token

        # Call the superclass's connect method with updated kwargs
        return super().connect(conninfo, **kwargs)

# Configure connection parameters (get these from the Connect dialog in the LakeBase App)
username = "your.email@company.com"  # Your DB identity
host = "ep-example.database.region.databricks.com"  # Your compute endpoint hostname
port = 5432
database = "databricks_postgres"

# Create connection pool with custom connection class
pool = ConnectionPool(
    conninfo=f"dbname={database} user={username} host={host} sslmode=require",
    connection_class=CustomConnection,
    min_size=1,
    max_size=10,
    open=True
)

# Use the connection pool
with pool.connection() as conn:
    with conn.cursor() as cursor:
        cursor.execute("SELECT version()")
        for record in cursor:
            print(record)

Python: SQLAlchemy

This example uses SQLAlchemy's connection pool with an event listener that automatically refreshes the OAuth token every 15 minutes. The event listener checks the token age before each new connection is created from the pool, ensuring your application always has a valid token without manual intervention.

%pip install sqlalchemy==1.4 psycopg[binary]

from databricks.sdk import WorkspaceClient
import time

from sqlalchemy import create_engine, text, event

w = WorkspaceClient()

# Configure connection parameters (get these from the Connect dialog in the LakeBase App)
endpoint = "projects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>"
username = "your.email@company.com"  # Your DB identity
host = "ep-example.database.region.databricks.com"  # Your compute endpoint hostname
port = 5432
database = "databricks_postgres"

# Create SQLAlchemy engine
connection_pool = create_engine(f"postgresql+psycopg2://{username}:@{host}:{port}/{database}?sslmode=require")

# Global variables for token management
postgres_password = None
last_password_refresh = time.time()

@event.listens_for(connection_pool, "do_connect")
def provide_token(dialect, conn_rec, cargs, cparams):
    global postgres_password, last_password_refresh

    # Refresh token if it's None or older than 15 minutes (900 seconds)
    if postgres_password is None or time.time() - last_password_refresh > 900:
        print("Refreshing PostgreSQL OAuth token")
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        postgres_password = credential.token
        last_password_refresh = time.time()

    cparams["password"] = postgres_password

# Use the connection pool
with connection_pool.connect() as conn:
    result = conn.execute(text("SELECT version()"))
    for row in result:
        print(f"Connected to PostgreSQL database. Version: {row}")

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 Azure 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)

Next steps

Feedback

Was this page helpful?

Last updated on 2026-02-04

Share via

About authentication

Overview

Connection timeouts

OAuth token authentication

How OAuth tokens work

Requirements and limitations

Obtain an OAuth token in a user-to-machine flow

UI

CLI

Python SDK

Java SDK

Obtain an OAuth token in a machine-to-machine flow

CLI

Python SDK

Java SDK

Token rotation examples

Python: psycopg3

Python: SQLAlchemy

Postgres password authentication

When to use Postgres passwords

How Postgres passwords work

Security considerations

Next steps

Feedback

Additional resources