Over verificatie

Meer informatie over het verifiëren van databaseverbindingen met Lakebase Postgres. Zie quickstart voor stapsgewijze instructies voor de verbinding.

Overzicht

Lakebase ondersteunt twee verificatiemethoden, die elk zijn ontworpen voor verschillende gebruiksvoorbeelden:

OAuth-tokenverificatie: gebruikt Azure Databricks identiteiten met beperkte OAuth-tokens. Geschikt voor:

• Interactieve sessies waar u tokens kunt vernieuwen
• Met werkruimte geïntegreerde werkstromen
• Toepassingen die tokenrotatie kunnen implementeren
• Wanneer u verificatie wilt beheren door Azure Databricks

Systeemeigen Postgres-wachtwoordverificatie: Gebruikt traditionele Postgres-rollen met wachtwoorden. Geschikt voor:

• Toepassingen die inloggegevens niet ieder uur kunnen vernieuwen
• Langlopende processen
• Tools die geen ondersteuning bieden voor tokenrotatie

Verbindingstime-outs

Alle databaseverbindingen gelden voor de volgende limieten, ongeacht de verificatiemethode:

• Time-out voor inactiviteit van 24 uur: Verbindingen zonder activiteit gedurende 24 uur worden automatisch gesloten.
• Maximale verbindingsduur van 3 dagen: Verbindingen die langer dan 3 dagen actief zijn, kunnen worden gesloten, ongeacht de activiteit.

Ontwerp uw toepassingen om verbindingstime-outs correct te verwerken door verbindingslogica voor opnieuw proberen te implementeren met de juiste time-outinstellingen.

OAuth-tokenverificatie

Met OAuth-tokenverificatie kunt u verbinding maken met behulp van uw Azure Databricks identiteit. U genereert een OAuth-token met een tijdslimiet en gebruikt dit als een wachtwoord bij het maken van verbinding met Postgres.

De OAuth-rol van de projecteigenaar wordt automatisch gemaakt. Als u OAuth-verificatie wilt inschakelen voor andere Azure Databricks identiteiten, moet u hun Postgres-rollen maken met behulp van de extensie databricks_auth en SQL. Zie Een OAuth-rol maken voor een DB-identiteit met behulp van SQL.

Hoe OAuth-tokens werken

• Levensduur van token: OAuth-tokens verlopen na één uur.
• Vervaldatum afdwingen: Het verlopen van tokens wordt alleen afgedwongen bij aanmelding. Open verbindingen blijven actief, zelfs nadat het token is verlopen.
• Token vernieuwen: Genereer zo nodig een nieuw token voor interactieve sessies. Voor toepassingen met langdurige verbindingen implementeert u tokenrotatie om referenties automatisch te vernieuwen.

Vereisten en beperkingen

• Vereiste Postgres-rol: uw Azure Databricks-identiteit moet een bijbehorende Postgres-rol hebben. De rol van de projecteigenaar wordt automatisch gemaakt. Maak voor andere Azure Databricks identiteiten hun rollen met behulp van de extensie databricks_auth.
• Werkruimte-afbakening: OAuth-tokens zijn afgebakend binnen de werkruimte en moeten tot dezelfde werkruimte behoren die eigenaar is van het project. Tokenverificatie tussen werkruimten wordt niet ondersteund.
• SSL vereist: verificatie op basis van tokens vereist SSL-verbindingen. Alle clients moeten worden geconfigureerd voor het gebruik van SSL (meestal sslmode=require).
• Groepsgewijze verbindingen worden niet ondersteund: de ingebouwde PgBouncer-verbindingspooler biedt geen ondersteuning voor OAuth-verificatie. Gebruik systeemeigen Postgres-wachtwoordrollen voor gegroepeerde verbindingen. Zie Groepsgewijze verbindingen gebruiken.

Een OAuth-token verkrijgen in een gebruikers-naar-machine-stroom

Als u een database-eigenaar, beheerder of uw Azure Databricks identiteit een bijbehorende Postgres-rol voor de database heeft, kunt u een OAuth-token verkrijgen via de gebruikersinterface, de Databricks-API, CLI of een van de Databricks SDK's.

Zie Gebruikerstoegang tot Azure Databricks verifiëren met OAuth voor de autorisatie-instructies op werkruimteniveau voor het verkrijgen van OAuth-tokens voor andere Azure Databricks identiteitsgebruikers.

UI (Gebruikersinterface)

Wanneer u SQL-clients zoals psql of DBeaver gebruikt, gebruikt u de Lakebase-gebruikersinterface om tokens te genereren:

1. Navigeer naar uw project in de Lakebase-app.
2. Selecteer de vertakking en rekenkracht waarmee u verbinding wilt maken.
3. Klik op Verbinden en volg de instructies om een OAuth-token te genereren.

Zie Verbinding maken met een OAuth-rol voor volledige instructies.

CLI (Command Line Interface)

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

Antwoord:

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

Gebruik de token waarde als het wachtwoord wanneer u verbinding maakt met uw database.

Python SDK

U kunt een OAuth-token genereren met behulp van de Databricks SDK voor 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 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

U kunt een OAuth-token genereren met behulp van de Databricks SDK voor 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());

Een OAuth-token verkrijgen in een machine-naar-machine-proces

Als u beveiligde, geautomatiseerde (machine-naar-machine) toegang tot de database wilt inschakelen, moet u een OAuth-token verkrijgen met behulp van een Azure Databricks service-principal. Dit proces omvat het configureren van de service-principal, het genereren van referenties en het instellen van OAuth-tokens voor verificatie.

1. Configureer een serviceprincipal met referenties voor onbepaalde tijd. Zie Authorize service-principaltoegang tot Azure Databricks met OAuth voor instructies.
2. Aanmaken nieuwe OAuth-tokens als de service-principeel.

CLI (Command Line Interface)

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

Antwoord:

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

Gebruik de token waarde als het wachtwoord wanneer u verbinding maakt met uw database.

Python SDK

U kunt een OAuth-token genereren met behulp van de Databricks SDK voor 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

U kunt een OAuth-token genereren met behulp van de Databricks SDK voor 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());

Voorbeelden van tokenrotatie

Omdat OAuth-tokens na één uur verlopen, moeten toepassingen die langlopende databaseverbindingen onderhouden, tokenrotatie implementeren om referenties periodiek te vernieuwen. In de volgende voorbeelden ziet u hoe u tokens automatisch kunt roteren in uw toepassingscode.

Python: psycopg3

In dit voorbeeld wordt de verbindingsgroep van psycopg3 gebruikt met een aangepaste verbindingsklasse waarmee telkens wanneer een nieuwe verbinding wordt gemaakt een nieuw OAuth-token wordt gegenereerd. Deze methode zorgt ervoor dat elke verbinding van de pool altijd een geldig, actueel token heeft.

%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 dit voorbeeld wordt de verbindingsgroep van SQLAlchemy gebruikt met een gebeurtenislistener waarmee het OAuth-token automatisch wordt vernieuwd voordat het verloopt. De eventlistener wordt geactiveerd voordat elke nieuwe fysieke verbinding vanuit de pool wordt gemaakt en vernieuwt het token als het binnen 2 minuten voor het verlopen zit, zodat uw toepassing altijd een geldig token heeft zonder handmatige tussenkomst.

%pip install sqlalchemy "psycopg[binary]" databricks-sdk

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

Systeemeigen Postgres-wachtwoordverificatie maakt gebruik van traditionele Postgres-rollen met wachtwoorden. In tegenstelling tot OAuth-tokens verlopen deze wachtwoorden na één uur niet, waardoor ze geschikt zijn voor toepassingen die niet regelmatig referenties kunnen rouleren.

Wanneer gebruikt u Postgres-wachtwoorden?

Gebruik Postgres-wachtwoordverificatie wanneer:

• Uw toepassing of hulpprogramma kan referenties niet elk uur vernieuwen
• U hebt langlopende processen die stabiele referenties nodig hebben
• Uw clientbibliotheek biedt geen ondersteuning voor OAuth-tokenrotatie
• U hebt traditionele databaseverificatie nodig voor compatibiliteit

Hoe Postgres-wachtwoorden werken

• Levensduur van wachtwoord: wachtwoorden verlopen niet automatisch
• Geen integratie van werkruimten: Authenticatie wordt verwerkt door Postgres, niet door Azure Databricks werkruimteauthenticatie
• Handmatig beheer: wachtwoorden moeten handmatig worden gedraaid en gedistribueerd naar gebruikers
• Verbindingstime-outs zijn nog steeds van toepassing: Hoewel wachtwoorden niet verlopen, zijn verbindingen nog steeds onderhevig aan een time-out voor inactiviteit van 24 uur en een maximale verbindingsduur van 3 dagen

Beveiligingsoverwegingen

• Wachtwoordopslag: wachtwoorden veilig opslaan met behulp van omgevingsvariabelen of geheimenbeheersystemen
• SSL vereist: alle verbindingen moeten GEBRUIKMAKEN van SSL (sslmode=require)

Groepsgewijze verbindingen

Systeemeigen Postgres-wachtwoordrollen ondersteunen de ingebouwde PgBouncer-verbindingspooler. De pooler vermindert de verbindingsoverhead voor toepassingen met hoge doorvoer. Zie Groepsgewijze verbindingen gebruiken.

Volgende stappen

• Quickstart: Verbinding maken met uw database
• Postgres-rollen beheren
• Machtigingen beheren
• Query's uitvoeren op uw gegevens