Pular para o conteúdo principal
Última atualização em

Sobre autenticação

info

O dimensionamento automático do Lakebase está disponível nas seguintes regiões: us-east-1, us-east-2, eu-central-1, eu-west-1, eu-west-2, ap-south-1, ap-southeast-1, ap-southeast-2.

O Lakebase autoscale é a versão mais recente do Lakebase com recursos como autoscale compute, escala-to-zero, branching e instant restore. Para comparação de recursos com o provisionamento do Lakebase, veja escolhendo entre versões.

Aprenda como autenticar conexões de banco de dados com o Lakebase Postgres. Para obter instruções de conexão passo a passo, consulte o Guia de Início Rápido.

Visão geral​

O Lakebase oferece suporte a dois métodos de autenticação, cada um projetado para diferentes casos de uso:

Autenticação por tokensOAuth : Utiliza identidades Databricks com tokens OAuth com tempo de validade limitado. Ideal para:

  • Sessões interativas onde você pode refresh tokens
  • fluxo de trabalho integrado ao espaço de trabalho
  • Aplicações que podem implementar rotação de tokens
  • Quando você deseja que a autenticação seja gerenciada pelo Databricks

Autenticação nativa de senha do Postgres: Utiliza funções tradicionais do Postgres com senhas. Ideal para:

  • Aplicativos que não conseguem refresh as credenciais a cada hora
  • Processos de longa duração
  • Ferramentas que não suportam rotação de tokens
nota

Gerenciamento de plataforma versus acesso ao banco de dados : Esta página aborda a autenticação do banco de dados (tokens OAuth e senhas do Postgres para conexão com o banco de dados). Para autenticação de gerenciamento de plataforma (criação de projetos, branches, computação), consulte Permissões do projeto.

Tempo limite de conexão​

Todas as conexões com o banco de dados estão sujeitas às seguintes limitações, independentemente do método de autenticação:

  • Tempo limite de 24 horas do Parado: Conexões sem atividade por 24 horas são fechadas automaticamente.
  • Tempo máximo de conexão: 3 dias. Conexões que estiverem ativas por mais de 3 dias poderão ser encerradas, independentemente da atividade.

Projete seus aplicativos para lidar com timeouts de conexão de forma adequada, implementando lógica de repetição de conexão com configurações de timeout apropriadas.

autenticação por tokensOAuth​

A autenticação por tokens OAuth permite que você se conecte usando sua identidade Databricks . Você gera tokens OAuth com tempo de vida limitado na interface do usuário do Lakebase e os utiliza como senha ao se conectar ao Postgres.

A função OAuth do proprietário do projeto é criada automaticamente. Para habilitar a autenticação OAuth para outras identidades do Databricks, você deve criar suas funções do Postgres usando a extensão databricks_auth e SQL. Consulte Criar uma função OAuth para uma identidade de banco de dados usando SQL.

Como funcionam os tokens OAuth​

  • Tempo de vida dos tokens: tokens OAuth expiram após uma hora.
  • Aplicação do prazo de validade: o prazo de validade dos tokens é aplicado somente no momento do login. As conexões abertas permanecem ativas mesmo após a expiração dos tokens.
  • Reautenticação: Qualquer consulta ou comando do Postgres falhará se os tokens expirarem.
  • refresh de tokens: Para sessões interativas, gere novos tokens na interface do usuário quando necessário. Para aplicações com conexões de longa duração, implemente a rotação de tokens para refresh as credenciais automaticamente.

Requisitos e limitações​

  • É necessário ter uma função correspondente no Postgres : Sua identidade no Databricks deve ter uma função correspondente no Postgres. A função de proprietário do projeto é criada automaticamente. Para outras identidades do Databricks, crie suas funções usando a extensão databricks_auth .
  • Escopo do espaço de trabalho : tokens OAuth têm escopo workspacee devem pertencer ao mesmo workspace que possui o projeto. A autenticação com tokens entreworkspace não é suportada.
  • SSL obrigatório : a autenticação baseada em tokens requer conexões SSL . Todos os clientes devem ser configurados para usar SSL (normalmente sslmode=require).

Obtenha tokens OAuth em um fluxo de usuário para máquina​

Se você for proprietário ou administrador do banco de dados, ou se sua identidade Databricks tiver uma função correspondente no Postgres para o banco de dados, você poderá obter tokens OAuth na interface do usuário, na API Databricks , CLI ou em um dos SDKs do Databricks .

Para outros usuários de identidade Databricks , consulte Autorizar o acesso do usuário ao Databricks com OAuth para obter instruções de autorização em nível workspacee como obter tokens OAuth .

Ao usar clientes SQL como psql ou DBeaver, utilize a interface do usuário do Lakebase para gerar tokens:

  1. Acesse seu projeto no aplicativo Lakebase.
  2. Selecione a filial e compute aos quais deseja se conectar.
  3. Clique em Conectar e siga as instruções para gerar um token OAuth .

Consulte Conectar com uma função OAuth para obter instruções completas.

Obtenha tokens OAuth em um fluxo de máquina para máquina.​

Para habilitar o acesso seguro e automatizado (máquina a máquina) ao banco de dados, você deve obter tokens OAuth usando uma entidade de serviço Databricks . Esse processo envolve configurar a entidade de serviço, gerar credenciais e criar tokens OAuth para autenticação.

  1. Configure uma entidade de serviço com credenciais de duração indefinida. Para obter instruções, consulte Autorizar o acesso da entidade de serviço ao Databricks com OAuth.
  2. Gere novos tokens OAuth como a entidade de serviço.
Bash
# Generate OAuth token for database connection (1-hour expiration)
databricks postgres generate-database-credential projects/my-project/branches/production/endpoints/my-compute --output json

Resposta:

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

Use o valor token como senha ao se conectar ao seu banco de dados.

nota

Rotacionar tokens OAuth antes do vencimento por hora:

  • Verifique o tempo de expiração dos tokens OAuth a cada uso e refresh quando necessário.
  • Alternativamente, configure uma thread em segundo plano para refresh periodicamente os tokens OAuth atuais.

Exemplos de rotação de tokens​

Como tokens OAuth expiram após uma hora, os aplicativos que mantêm conexões de banco de dados de longa duração devem implementar a rotação de tokens para refresh as credenciais periodicamente. Os exemplos a seguir demonstram como rotacionar tokens automaticamente no código do seu aplicativo.

nota

Requisitos para estes exemplos:

  • Você precisa estar autenticado no workspace que possui o projeto. O WorkspaceClient() usa suas credenciais OAuth workspace para gerar tokens de banco de dados.
  • Sua identidade Databricks deve ser membro do workspace onde o projeto foi criado.
  • Obtenha os parâmetros de conexão (host, banco de dados, endpoint) na caixa de diálogo Conectar do aplicativo Lakebase. Consulte o Guia de Início Rápido para obter mais detalhes.
  • O parâmetro endpoint usa o formato: projects/{project-id}/branches/{branch-id}/endpoints/{endpoint-id}

Para configurar a autenticação workspace , consulte Autorizar o acesso do usuário ao Databricks com OAuth ou Autorizar o acesso da entidade de serviço ao Databricks com OAuth.

Este exemplo utiliza pool de conexões do psycopg3 com uma classe de conexão personalizada que gera novos tokens OAuth sempre que uma nova conexão é criada. Essa abordagem garante que cada conexão do pool sempre tenha tokens válidos e atuais.

Python
%pip install "psycopg[binary,pool]"
Python
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)

Autenticação de senha do Postgres​

A autenticação nativa por senha do Postgres utiliza funções tradicionais do Postgres com senhas. Diferentemente dos tokens OAuth, essas senhas não expiram após uma hora, tornando-as adequadas para aplicativos que não suportam a rotação frequente de credenciais.

Quando usar senhas do Postgres​

Use a autenticação por senha do Postgres quando:

  • Seu aplicativo ou ferramenta não pode refresh as credenciais a cada hora.
  • Você tem processos de longa duração que precisam de credenciais estáveis.
  • Sua biblioteca cliente não suporta a rotação de tokens OAuth.
  • Você precisa de autenticação de banco de dados tradicional para compatibilidade.

Como funcionam as senhas do Postgres​

  • Tempo de vida da senha : As senhas não expiram automaticamente.
  • Sem integração workspace : a autenticação é gerenciada pelo Postgres, não pela autenticação workspace Databricks
  • Gestão manual : As senhas devem ser rotacionadas e distribuídas manualmente aos usuários.
  • Os tempos limite de conexão ainda se aplicam : mesmo que as senhas não expirem, as conexões ainda estão sujeitas ao tempo limite de 24 horas do Parado e à duração máxima de conexão de 7 dias.

Considerações de segurança​

  • Armazenamento de senhas : Armazene senhas com segurança usando variáveis de ambiente ou sistemas de gerenciamento de segredos.
  • SSL obrigatório : Todas as conexões devem usar SSL (sslmode=require)

Próximos passos​