Informationen zur Authentifizierung

Erfahren Sie, wie Sie Datenbankverbindungen mit Lakebase Postgres authentifizieren. Schrittweise Verbindungsanweisungen finden Sie in der Schnellstartanleitung.

Überblick

Lakebase unterstützt zwei Authentifizierungsmethoden, die jeweils für unterschiedliche Anwendungsfälle entwickelt wurden:

OAuth-Token-Authentifizierung: Verwendet Azure Databricks-Identitäten mit zeitlich begrenzten OAuth-Token. Am besten geeignet für:

  • Interaktive Sitzungen, in denen Sie Token aktualisieren können
  • Arbeitsbereich-integrierte Workflows
  • Anwendungen, die tokenrotation implementieren können
  • Wenn Die Authentifizierung von Azure Databricks verwaltet werden soll

Native Postgres-Passwortauthentifizierung: Verwendet traditionelle Postgres-Rollen mit Passwörtern. Am besten geeignet für:

  • Anwendungen, die Anmeldeinformationen nicht stündlich aktualisieren können
  • Lange laufende Prozesse
  • Tools, die die Tokenrotation nicht unterstützen

Hinweis

Plattformverwaltung vs. Datenbankzugriff: Diese Seite behandelt die Authentifizierung für die Datenbank (OAuth-Token und Postgres-Passwörter für die Verbindung mit Ihrer Datenbank). Informationen zur Authentifizierung für das Plattformmanagement (Erstellen von Projekten, Verzweigungen, Berechnungen) finden Sie unter Project permissions.

Verbindungs-Timeouts

Alle Datenbankverbindungen unterliegen den folgenden Grenzwerten, unabhängig von der Authentifizierungsmethode:

  • 24-Stunden-Leerlaufzeit: Verbindungen ohne 24-Stunden-Aktivität werden automatisch geschlossen.
  • Maximale Verbindungslebensdauer von 3 Tagen: Verbindungen, die seit mehr als 3 Tagen bestehen, können unabhängig davon, ob Aktivität vorliegt, geschlossen werden.

Entwerfen Sie Ihre Anwendungen so, dass Verbindungstimeouts ordnungsgemäß verarbeitet werden, indem Sie die Verbindungs-Wiederholungslogik mit den entsprechenden Timeouteinstellungen implementieren.

OAuth-Token-Authentifizierung

Mit der OAuth-Tokenauthentifizierung können Sie mithilfe Ihrer Azure Databricks Identität eine Verbindung herstellen. Sie generieren ein zeitlich begrenztes OAuth-Token und verwenden es als Kennwort, wenn Sie eine Verbindung mit Postgres herstellen.

Die OAuth-Rolle des Projektbesitzers wird automatisch erstellt. Um die OAuth-Authentifizierung für andere Azure Databricks Identitäten zu aktivieren, müssen Sie ihre Postgres-Rollen mithilfe der Erweiterung databricks_auth und SQL erstellen. Siehe Erstellen einer OAuth-Rolle für eine DB-Identität mit SQL.

Funktionsweise von OAuth-Token

  • Lebensdauer des Tokens: OAuth-Token verfallen nach einer Stunde.
  • Durchsetzung des Ablaufs: Der Ablauf des Tokens wird nur bei der Anmeldung durchgesetzt. Offene Verbindungen bleiben auch nach Ablauf des Tokens aktiv.
  • Token-Aktualisierung: Für interaktive Sitzungen erstellen Sie bei Bedarf einen neuen Token. Implementieren Sie für Anwendungen mit langen Verbindungen die Tokenrotation , um Anmeldeinformationen automatisch zu aktualisieren.

Anforderungen und Einschränkungen

  • Entsprechende Postgres-Rolle erforderlich: Ihre Azure Databricks-Identität muss über eine entsprechende Postgres-Rolle verfügen. Die Rolle des Projektbesitzers wird automatisch erstellt. Erstellen Sie die entsprechenden Rollen für andere Azure-Databricks-Identitäten mithilfe der Erweiterung databricks_auth.
  • Workspace-Scoping: OAuth-Token sind workspace-scoped und müssen demselben Workspace angehören, dem das Projekt gehört. Die arbeitsbereichübergreifende Tokenauthentifizierung wird nicht unterstützt.
  • SSL erforderlich: Token-basierte Authentifizierung erfordert SSL-Verbindungen. Alle Clients müssen für die Verwendung von SSL konfiguriert werden (in der Regel sslmode=require).
  • Verbindungspooling: Benutzer und Service-Principals können sich über den integrierten PgBouncer-Verbindungspooler mit einem OAuth-Token über die Lakebase-Benutzeroberfläche oder die Datenbank-Anmeldedaten-API verbinden. Gruppenrollen, Token von anderen OAuth-Clients und Token mit Tabellenberechtigungen benötigen eine direkte Verbindung. Siehe OAuth-Rollen.

Einen OAuth-Token in einem User-to-Machine-Flow abrufen

Wenn Sie Datenbankbesitzer, Administrator oder Ihre Azure-Databricks-Identität eine zugehörige Postgres-Rolle für die Datenbank hat, können Sie ein OAuth-Token über die Benutzeroberfläche, die Databricks-API, die CLI oder eines der Databricks-SDKs abrufen.

Für andere Benutzer mit Azure Databricks-Identitäten finden Sie unter Benutzerzugriff auf Azure Databricks mit OAuth autorisieren Anweisungen zur Autorisierung auf Arbeitsbereichsebene und zum Erhalt von OAuth-Token.

Benutzeroberfläche

Verwenden Sie bei Verwendung von SQL-Clients wie psql oder DBeaver die Lakebase-Benutzeroberfläche, um Token zu generieren:

  1. Navigieren Sie in der Lakebase-App zu Ihrem Projekt.
  2. Wählen Sie den Zweig und den Rechner aus, mit dem Sie eine Verbindung herstellen möchten.
  3. Klicken Sie auf "Verbinden" , und folgen Sie den Anweisungen, um ein OAuth-Token zu generieren.

Eine vollständige Anleitung finden Sie unter Herstellen einer Verbindung mit einer OAuth-Rolle .

Befehlszeilenschnittstelle (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

Antwort:

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

Verwenden Sie den token Wert als Kennwort, wenn Sie eine Verbindung mit Ihrer Datenbank herstellen.

Python SDK

Sie können ein OAuth-Token mithilfe des Databricks SDK für Python generieren.

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 psycopg

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

Java SDK

Sie können ein OAuth-Token mithilfe des Databricks SDK für Java generieren.

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

Einen OAuth-Token in einem Machine-to-Machine-Flow abrufen

Um den sicheren, automatisierten Zugriff (Maschine-zu-Maschine) auf die Datenbank zu ermöglichen, müssen Sie ein OAuth-Token mithilfe eines Azure-Databricks-Dienstprinzipals abrufen. Dieser Prozess umfasst das Konfigurieren des Dienstprinzipals, das Generieren von Anmeldeinformationen und das Abfassen von OAuth-Token für die Authentifizierung.

  1. Konfigurieren Sie einen Dienstprinzipal mit unbefristet gültigen Anmeldeinformationen. Anweisungen finden Sie unter Authorize-Dienstprinzipalzugriff auf Azure Databricks mit OAuth.
  2. Generieren Sie neue OAuth-Token als Dienstprinzipal.

Befehlszeilenschnittstelle (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

Antwort:

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

Verwenden Sie den token Wert als Kennwort, wenn Sie eine Verbindung mit Ihrer Datenbank herstellen.

Python SDK

Sie können ein OAuth-Token mithilfe des Databricks SDK für Python generieren.

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

Sie können ein OAuth-Token mithilfe des Databricks SDK für Java generieren.

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

Hinweis

Rotieren Sie OAuth-Token vor dem stündlichem Ablauf:

  • Überprüfen Sie bei Bedarf die Ablaufzeit des OAuth-Tokens für jede Verwendung und Aktualisierung.
  • Alternativ können Sie einen Hintergrundthread einrichten, um das aktuelle OAuth-Token regelmäßig zu aktualisieren.

Beispiele für Token-Rotationen

Da OAuth-Tokens nach einer Stunde ablaufen, müssen Anwendungen, die lang andauernde Datenbankverbindungen verwalten, die Token-Rotation implementieren, um Anmeldeinformationen regelmäßig aktualisieren. Die folgenden Beispiele veranschaulichen, wie Token in Ihrem Anwendungscode automatisch gedreht werden.

Hinweis

Anforderungen für diese Beispiele:

  • Sie müssen sich im Arbeitsbereich authentifizieren, der das Projekt besitzt. Der WorkspaceClient() verwendet Ihre OAuth-Anmeldeinformationen des Arbeitsbereichs, um Datenbanktoken zu generieren.
  • Ihre Azure Databricks-Identität muss Mitglied des Arbeitsbereichs sein, in dem das Projekt erstellt wurde.
  • Rufen Sie Ihre Verbindungsparameter (Host, Datenbank, Endpunkt) aus dem Dialogfeld "Verbinden " in der Lakebase-App ab. Details finden Sie in der Schnellstartanleitung .
  • Der endpoint Parameter verwendet das Format: projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}

Informationen zum Einrichten der Authentifizierung für Arbeitsbereiche finden Sie unter Benutzerzugriff auf Azure Databricks mit OAuth autorisieren oder Zugriff von Dienstprinzipalen auf Azure Databricks mit OAuth autorisieren.

Python: psycopg3

In diesem Beispiel wird der Verbindungspool von psycopg3 mit einer benutzerdefinierten Verbindungsklasse verwendet, die jedes Mal, wenn eine neue Verbindung erstellt wird, ein neues OAuth-Token generiert. Durch diesen Ansatz wird sichergestellt, dass jede Verbindung aus dem Pool immer über ein gültiges, aktuelles Token verfügt.

%pip install "psycopg[binary,pool]"
from databricks.sdk import WorkspaceClient

import psycopg
from psycopg_pool import ConnectionPool

w = WorkspaceClient()

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

In diesem Beispiel wird der Verbindungspool von SQLAlchemy mit einem Ereignislistener verwendet, der das OAuth-Token automatisch aktualisiert, bevor es abläuft. Der Ereignislistener wird ausgelöst, bevor jede neue physische Verbindung aus dem Pool erstellt wird. Er aktualisiert das Token, falls dessen Ablauf innerhalb von 2 Minuten bevorsteht, und stellt sicher, dass Ihre Anwendung immer über ein gültiges Token verfügt, ohne dass ein manuelles Eingreifen erforderlich ist.

%pip install sqlalchemy==2.0.36 "psycopg[binary]==3.2.3" databricks-sdk==0.79.0
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+psycopg://{username}:@{host}:{port}/{database}?sslmode=require")

# Global variables for token management
postgres_password = None
token_expiry = 0.0  # Unix timestamp when the current token expires

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

    # Refresh token if None or expiring within 2 minutes
    if postgres_password is None or time.time() >= token_expiry - 120:
        print("Refreshing PostgreSQL OAuth token")
        credential = w.postgres.generate_database_credential(endpoint=endpoint)
        postgres_password = credential.token
        token_expiry = credential.expire_time.seconds

    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-Passwortauthentifizierung

Hinweis

Passwortverbindungen sind standardmäßig für neue Lakebase-Projekte deaktiviert. Informationen zum Aktivieren finden Sie unter "Verwalten von Kennwortverbindungen".

Die native Postgres-Kennwortauthentifizierung verwendet traditionelle Postgres-Rollen mit Kennwörtern. Im Gegensatz zu OAuth-Token laufen diese Kennwörter nicht nach einer Stunde ab, sodass sie für Anwendungen geeignet sind, die einen häufigen Wechsel von Anmeldeinformationen nicht umgehen können.

Wann man Postgres-Kennwörter verwenden sollte

Verwenden Sie die Postgres-Kennwortauthentifizierung, wenn:

  • Ihre Anwendung oder Ihr Tool kann anmeldeinformationen nicht jede Stunde aktualisieren.
  • Sie haben langlaufende Prozesse, die stabile Anmeldeinformationen benötigen
  • Ihre Clientbibliothek unterstützt keine OAuth-Tokenrotation
  • Für die Kompatibilität benötigen Sie eine traditionelle Datenbankauthentifizierung.

Funktionsweise von Postgres-Kennwörtern

  • Passwort-Lebensdauer: Passwörter verfallen nicht automatisch
  • Keine Workspace-Integration: Die Authentifizierung wird von Postgres übernommen, nicht von der Azure Databricks-Workspace-Authentifizierung
  • Manuelle Verwaltung: Passwörter müssen manuell rotiert und an die Nutzer verteilt werden
  • Verbindungs-Timeouts gelten weiterhin: Auch wenn Passwörter nicht ablaufen, unterliegen Verbindungen weiterhin einem 24-stündigen Leerlauf-Timeout und einer maximalen Verbindungsdauer von 3 Tagen

Sicherheitsüberlegungen

  • Passwortspeicherung: Passwörter sicher mithilfe von Umgebungsvariablen oder Geheimnisverwaltungssystemen speichern
  • SSL erforderlich: Alle Verbindungen müssen SSL verwenden (sslmode=require)

Verbindungspooling

Native Postgres-Kennwortrollen unterstützen den integrierten PgBouncer-Verbindungspooler. Der Pooler reduziert den Verbindungsaufwand für Anwendungen mit hohem Durchsatz. Siehe Verwenden von Verbindungspooling.

Weitere Ressourcen