Acerca de la autenticación

Importante

El escalado automático de Lakebase está en Beta en las siguientes regiones: eastus2, westeurope, westus.

El escalado automático de Lakebase es la versión más reciente de Lakebase con proceso de escalado automático, escalado a cero, bifurcación y restauración instantánea. Para ver la comparación de características con Lakebase Provisioned, consulte Elección entre versiones.

Aprenda a autenticar conexiones de base de datos a Lakebase Postgres. Para obtener instrucciones de conexión paso a paso, consulte Inicio rápido.

Información general

Lakebase admite dos métodos de autenticación, cada uno diseñado para distintos casos de uso:

Autenticación de tokens de OAuth: Usa identidades de Azure Databricks con tokens de OAuth limitados por tiempo. Ideal para:

Sesiones interactivas en las que puede actualizar tokens
Flujos de trabajo integrados en el área de trabajo
Aplicaciones que pueden implementar la rotación de tokens
Cuando desee la autenticación administrada por Azure Databricks

Autenticación de contraseña de Postgres nativa: Usa roles de Postgres tradicionales con contraseñas. Ideal para:

Aplicaciones que no pueden actualizar las credenciales cada hora
Procesos de ejecución prolongada
Herramientas que no admiten la rotación de tokens

Nota:

Administración de la plataforma frente al acceso a bases de datos: esta página se centra en la autenticación de bases de datos (tokens de OAuth y contraseñas de Postgres para conectarse a la base de datos). Para la autenticación de administración de plataformas (creación de proyectos, ramas, procesos), consulte Permisos de proyecto.

Tiempos de espera de conexión

Todas las conexiones de base de datos están sujetas a los límites siguientes, independientemente del método de autenticación:

Tiempo de espera de inactividad de 24 horas: Las conexiones sin actividad durante 24 horas se cierran automáticamente.
Duración máxima de la conexión de 3 días: Las conexiones que han estado activas durante más de 3 días se pueden cerrar independientemente de la actividad.

Diseñe las aplicaciones para controlar los tiempos de espera de conexión correctamente mediante la implementación de la lógica de reintento de conexión con la configuración de tiempo de espera adecuada.

Autenticación de tokens de OAuth

La autenticación de tokens de OAuth permite conectarse mediante la identidad de Azure Databricks. Se genera un token de OAuth limitado por tiempo desde la interfaz de usuario de Lakebase y se usa como contraseña al conectarse a Postgres.

El rol OAuth del propietario del proyecto se crea automáticamente. Para habilitar la autenticación de OAuth para otras identidades de Azure Databricks, debe crear sus roles de Postgres mediante la databricks_auth extensión y SQL. Consulte Creación de un rol de OAuth para una identidad de base de datos mediante SQL.

Funcionamiento de los tokens de OAuth

Duración del token: Los tokens de OAuth expiran después de una hora.
Cumplimiento de la expiración: La expiración del token solo se aplica al inicio de sesión. Las conexiones abiertas permanecen activas incluso después de que expire el token.
Volver a autenticar: Se produce un error en cualquier consulta o comando de Postgres si el token ha expirado.
Actualización del token: En el caso de las sesiones interactivas, genere un nuevo token a partir de la interfaz de usuario cuando sea necesario. En el caso de las aplicaciones con conexiones de ejecución prolongada, implemente la rotación de tokens para actualizar automáticamente las credenciales.

Requisitos y limitaciones

Rol correspondiente de Postgres requerido: Su identidad de Azure Databricks debe tener un rol correspondiente de Postgres. El rol del propietario del proyecto se crea automáticamente. Para otras identidades de Azure Databricks, cree sus roles mediante la databricks_auth extensión .
Ámbito del área de trabajo: los tokens de OAuth tienen ámbito de área de trabajo y deben pertenecer al mismo área de trabajo que posee el proyecto. No se admite la autenticación de tokens entre áreas de trabajo.
SSL requerido: la autenticación basada en tokens requiere conexiones SSL. Todos los clientes deben configurarse para usar SSL (normalmente sslmode=require).

Obtención de un token de OAuth en un flujo de usuario a máquina

Si es propietario, administrador, o si una identidad de Azure Databricks que usted representa tiene un rol de Postgres correspondiente para la base de datos, puede obtener un token de OAuth desde la interfaz de usuario, la API de Databricks, la CLI o uno de los SDK de Databricks.

Para otros usuarios de identidad de Azure Databricks, consulte Autorización del acceso de usuario a Azure Databricks con OAuth para obtener tokens de OAuth en el nivel de área de trabajo.

Interfaz de usuario

Al usar clientes SQL como psql o DBeaver, use la interfaz de usuario de Lakebase para generar tokens:

Dirígete a tu proyecto en la aplicación Lakebase.
Seleccione la rama y la instancia de computación a la que desea conectarse.
Haga clic en Conectar y siga las instrucciones para generar un token de OAuth.

Consulte Conexión con un rol de OAuth para obtener instrucciones completas.

Interfaz de línea de comandos (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

Respuesta:

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

Use el token valor como contraseña al conectarse a la base de datos.

SDK de Python

Puede generar un token de OAuth mediante el SDK de Databricks para 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"
)

SDK de Java

Puede generar un token de OAuth mediante el SDK de Databricks para 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());

Obtención de un token de OAuth en un flujo de máquina a máquina

Para habilitar el acceso seguro y automatizado (máquina a máquina) a la base de datos, debe obtener un token de OAuth mediante una entidad de servicio de Azure Databricks. Este proceso implica la configuración de la entidad de servicio, la generación de credenciales y la creación de tokens de OAuth para la autenticación.

Configure una entidad de servicio con credenciales de duración indefinida. Para obtener instrucciones, consulte Autorización del acceso de la entidad de servicio a Azure Databricks con OAuth.

Emita nuevos tokens de OAuth como entidad de servicio.

Interfaz de línea de comandos (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

Respuesta:

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

Use el token valor como contraseña al conectarse a la base de datos.

SDK de Python

Puede generar un token de OAuth mediante el SDK de Databricks para 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}")

SDK de Java

Puede generar un token de OAuth mediante el SDK de Databricks para 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());

Nota:

Rote tokens de OAuth antes de que expiren cada hora:

Compruebe la hora de expiración del token de OAuth en cada uso y actualización cuando sea necesario.
Como alternativa, configure un subproceso en segundo plano para actualizar el token de OAuth actual periódicamente.

Ejemplos de rotación de tokens

Dado que los tokens de OAuth expiran después de una hora, las aplicaciones que mantienen conexiones de base de datos de ejecución prolongada deben implementar la rotación de tokens para actualizar las credenciales periódicamente. En los ejemplos siguientes se muestra cómo rotar automáticamente los tokens en el código de la aplicación.

Nota:

Requisitos para estos ejemplos:

Debes estar autenticado en el área de trabajo propietaria del proyecto. WorkspaceClient() usa las credenciales de OAuth del área de trabajo para generar tokens de base de datos.
Su identidad de Azure Databricks debe ser miembro del área de trabajo donde se creó el proyecto.
Obtenga los parámetros de conexión (host, base de datos, punto de conexión) del cuadro de diálogo Conectar en la aplicación Lakebase. Consulte Inicio rápido para obtener más información.
El endpoint parámetro usa el formato : projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}

Para la configuración de la autenticación del área de trabajo, consulte Autorización del acceso de usuario a Azure Databricks con OAuth o Autorización del acceso de un principal de servicio a Azure Databricks con OAuth.

Python: psycopg3

En este ejemplo se usa el grupo de conexiones de psycopg3 con una clase de conexión personalizada que genera un token de OAuth nuevo cada vez que se crea una nueva conexión. Este enfoque garantiza que cada conexión del grupo siempre tenga un token válido y actualizado.

%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

En este ejemplo se usa el grupo de conexiones de SQLAlchemy con un agente de escucha de eventos que actualiza automáticamente el token de OAuth cada 15 minutos. El oyente de eventos comprueba la antigüedad del token antes de crear cada nueva conexión desde el pool, lo que garantiza que la aplicación siempre tenga un token válido sin intervención manual.

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

Autenticación con contraseña de Postgres

La autenticación con contraseña de Postgres nativa usa roles tradicionales de Postgres con contraseñas. A diferencia de los tokens de OAuth, estas contraseñas no expiran después de una hora, por lo que son adecuadas para las aplicaciones que no pueden controlar la rotación frecuente de credenciales.

Cuándo usar contraseñas de Postgres

Use la autenticación con contraseña de Postgres cuando:

La aplicación o la herramienta no pueden actualizar las credenciales cada hora
Tienes procesos de ejecución prolongada que necesitan credenciales estables.
La biblioteca cliente no admite la rotación de tokens de OAuth.
Necesita la autenticación de base de datos tradicional para la compatibilidad

Funcionamiento de las contraseñas de Postgres

Duración de la contraseña: las contraseñas no expiran automáticamente
Sin integración en el espacio de trabajo: La autenticación es gestionada por Postgres, no por la autenticación del espacio de trabajo de Azure Databricks.
Administración manual: las contraseñas deben rotarse y distribuirse manualmente a los usuarios
Todavía se aplican tiempos de espera de conexión: aunque las contraseñas no expiran, las conexiones siguen estando sujetas a un tiempo de espera de inactividad de 24 horas y una duración máxima de conexión de 7 días.

Consideraciones de seguridad

Almacenamiento de contraseñas: almacenar contraseñas de forma segura mediante variables de entorno o sistemas de administración de secretos
SSL requerido: todas las conexiones deben usar SSL (sslmode=require)

Pasos siguientes

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-02-07

Compartir vía

Acerca de la autenticación

Información general

Tiempos de espera de conexión

Autenticación de tokens de OAuth

Funcionamiento de los tokens de OAuth

Requisitos y limitaciones

Obtención de un token de OAuth en un flujo de usuario a máquina

Interfaz de usuario

Interfaz de línea de comandos (CLI)

SDK de Python

SDK de Java

Obtención de un token de OAuth en un flujo de máquina a máquina

Interfaz de línea de comandos (CLI)

SDK de Python

SDK de Java

Ejemplos de rotación de tokens

Python: psycopg3

Python: SQLAlchemy

Autenticación con contraseña de Postgres

Cuándo usar contraseñas de Postgres

Funcionamiento de las contraseñas de Postgres

Consideraciones de seguridad

Pasos siguientes

Comentarios

Recursos adicionales