Informazioni sull'autenticazione

Informazioni su come autenticare le connessioni di database a Lakebase Postgres. Per istruzioni dettagliate sulla connessione, vedere Avvio rapido.

Informazioni generali

Lakebase supporta due metodi di autenticazione, ognuno progettato per casi d'uso diversi:

Autenticazione del token OAuth: Usa le identità di Azure Databricks con token OAuth limitati a tempo. Ideale per:

• Sessioni interattive in cui è possibile aggiornare i token
• Flussi di lavoro integrati nell'area di lavoro
• Applicazioni che possono implementare la rotazione dei token
• Quando si vuole che l'autenticazione sia gestita da Azure Databricks

Autenticazione password postgres nativa: Usa i ruoli Postgres tradizionali con password. Ideale per:

• Applicazioni che non possono aggiornare le credenziali ogni ora
• Processi a esecuzione prolungata
• Strumenti che non supportano la rotazione dei token

Timeout di connessione

Tutte le connessioni di database sono soggette ai limiti seguenti indipendentemente dal metodo di autenticazione:

• Timeout di inattività di 24 ore: Le connessioni senza attività per 24 ore vengono chiuse automaticamente.
• Durata massima della connessione di 3 giorni: Le connessioni attive per più di 3 giorni possono essere chiuse indipendentemente dall'attività.

Progettare le applicazioni per gestire i timeout di connessione normalmente implementando la logica di ripetizione dei tentativi di connessione con le impostazioni di timeout appropriate.

Autenticazione del token OAuth

L'autenticazione tramite token OAuth consente di connettersi usando l'identità di Azure Databricks. Si genera un token OAuth limitato a tempo dall'interfaccia utente di Lakebase e lo si usa come password durante la connessione a Postgres.

Il ruolo OAuth del proprietario del progetto viene creato automaticamente. Per abilitare l'autenticazione OAuth per altre identità di Azure Databricks, è necessario creare i ruoli Postgres usando l'estensione databricks_auth e SQL. Vedere Creare un ruolo OAuth per un'identità del database usando SQL.

Funzionamento dei token OAuth

• Durata del token: I token OAuth scadono dopo un'ora.
• Applicazione della scadenza: La scadenza del token viene applicata solo al momento del login. Le connessioni aperte rimangono attive anche dopo la scadenza del token.
• Ripetere l'autenticazione: Qualsiasi query o comando Postgres ha esito negativo se il token è scaduto.
• Aggiornamento del token: Per le sessioni interattive, generare un nuovo token dall'interfaccia utente quando necessario. Per le applicazioni con connessioni a esecuzione prolungata, implementare la rotazione dei token per aggiornare automaticamente le credenziali.

Requisiti e limitazioni

• Ruolo Postgres corrispondente richiesto: l'identità di Azure Databricks deve avere un ruolo Postgres corrispondente. Il ruolo del proprietario del progetto viene creato automaticamente. Per altre identità di Azure Databricks, creare ruoli usando l'estensione databricks_auth .
• Definizione dell'ambito dell'area di lavoro: i token OAuth sono con ambito dell'area di lavoro e devono appartenere alla stessa area di lavoro che possiede il progetto. L'autenticazione token tra aree di lavoro non è supportata.
• SSL obbligatorio: l'autenticazione basata su token richiede connessioni SSL. Tutti i client devono essere configurati per utilizzare SSL (in genere sslmode=require).

Ottenere un token OAuth in un flusso utente-macchina

Se si è un proprietario del database, un amministratore o l'identità di Azure Databricks ha un ruolo Postgres corrispondente per il database, è possibile ottenere un token OAuth dall'interfaccia utente, dall'API databricks, dall'interfaccia della riga di comando o da uno degli SDK di Databricks.

Per altri utenti di identità di Azure Databricks, vedere Autorizzare l'accesso utente ad Azure Databricks con OAuth per le istruzioni di autorizzazione a livello di area di lavoro per ottenere i token OAuth.

INTERFACCIA UTENTE

Quando si usano client SQL come psql o DBeaver, usare l'interfaccia utente di Lakebase per generare token:

1. Naviga al tuo progetto nell'app Lakebase.
2. Selezionare il ramo e il calcolo a cui connettersi.
3. Fare clic su Connetti e seguire le istruzioni per generare un token OAuth.

Per istruzioni complete, vedere Connettersi con un ruolo OAuth .

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

Risposta:

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

Usare il token valore come password per la connessione al database.

Python SDK

È possibile generare un token OAuth usando Databricks SDK per 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

È possibile generare un token OAuth usando Databricks SDK per 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());

Ottenere un token OAuth in un flusso da macchina a macchina

Per abilitare l'accesso sicuro e automatizzato (da computer a computer) al database, è necessario ottenere un token OAuth usando un principale del servizio di Azure Databricks. Questo processo comporta la configurazione dell'entità servizio, la generazione di credenziali e la creazione di token OAuth per l'autenticazione.

1. Configurare un principale del servizio con credenziali a tempo indeterminato. Per istruzioni, vedere Autorizzare l'accesso dell'entità servizio ad Azure Databricks con OAuth.

2. Generare nuovi token OAuth come principale del servizio.

   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
   

   Risposta:

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

   Usare il token valore come password per la connessione al database.

   Python SDK

   È possibile generare un token OAuth usando Databricks SDK per 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

   È possibile generare un token OAuth usando Databricks SDK per 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());
   

Esempi di rotazione dei token

Poiché i token OAuth scadono dopo un'ora, le applicazioni che mantengono connessioni di database a esecuzione prolungata devono implementare la rotazione dei token per aggiornare periodicamente le credenziali. Gli esempi seguenti illustrano come ruotare automaticamente i token nel codice dell'applicazione.

Python: psycopg3

Questo esempio usa il pool di connessioni psycopg3 con una classe di connessione personalizzata che genera un nuovo token OAuth ogni volta che viene creata una nuova connessione. Questo approccio garantisce che ogni connessione dal pool abbia sempre un token valido e corrente.

%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

Questo esempio usa il pool di connessioni di SQLAlchemy con un listener di eventi che aggiorna automaticamente il token OAuth ogni 15 minuti. Il listener di eventi controlla l'età del token prima che ogni nuova connessione venga creata dal pool, assicurando che l'applicazione disponga sempre di un token valido senza intervento manuale.

%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}")

Autenticazione tramite password di Postgres

L'autenticazione password di Postgres nativa usa i ruoli Postgres tradizionali con password. A differenza dei token OAuth, queste password non scadono dopo un'ora, rendendole adatte alle applicazioni che non possono gestire la rotazione frequente delle credenziali.

Quando usare le password postgres

Usare l'autenticazione password postgres quando:

• L'applicazione o lo strumento non può aggiornare le credenziali ogni ora
• Sono presenti processi a esecuzione prolungata che necessitano di credenziali stabili
• La libreria client non supporta la rotazione dei token OAuth
• È necessaria l'autenticazione tradizionale del database per la compatibilità

Funzionamento delle password di Postgres

• Durata password: le password non scadono automaticamente
• Nessuna integrazione dell'area di lavoro: l'autenticazione viene gestita da Postgres, non dall'autenticazione dell'area di lavoro di Azure Databricks
• Gestione manuale: le password devono essere ruotate e distribuite manualmente agli utenti
• I timeout di connessione si applicano ancora: anche se le password non scadono, le connessioni sono ancora soggette a timeout di inattività di 24 ore e durata massima della connessione di 7 giorni

Considerazioni sulla sicurezza

• Archiviazione password: archiviare le password in modo sicuro usando variabili di ambiente o sistemi di gestione dei segreti
• SSL obbligatorio: tutte le connessioni devono usare SSL (sslmode=require)

Passaggi successivi

• Guida rapida: Connettersi al tuo database
• Gestire i ruoli di Postgres
• Gestire autorizzazioni
• Eseguire query sui dati