Autenticar em uma instância de banco de dados

Importante

Esse recurso está em Visualização Pública nas seguintes regiões: westus, , westus2, eastus, eastus2, centralus, southcentralus, , northeurope, westeurope, , australiaeast, , brazilsouth, , canadacentral, , centralindia, , southeastasiauksouth.

Esta página descreve como autenticar em uma instância de banco de dados do Lakebase. Há duas maneiras de autenticar:

Obtenha um token OAuth e autentique-se usando identidades do Azure Databricks.
Use funções postgres nativas com senhas.

Autenticar com identidades do Azure Databricks

Quando você se autentica como uma identidade do Azure Databricks, precisa gerar um token OAuth e usá-lo como senha ao se conectar ao Postgres.

Considerações antes de começar

Os tokens OAuth expiram após uma hora, mas a expiração é imposta somente no logon. As conexões abertas permanecem ativas mesmo se o token expirar. No entanto, qualquer comando PostgreSQL que exija autenticação falhará se o token tiver expirado.
Os tokens OAuth usados para autenticação do Postgres têm escopo de workspace e devem pertencer ao mesmo workspace que possui a instância do banco de dados. Não há suporte para autenticação de token entre workspaces. Para saber mais sobre autenticação, consulte Autenticação para a CLI do Databricks.
A autenticação baseada em token requer uma senha de texto não criptografado, portanto, somente conexões SSL são permitidas. Verifique se a biblioteca de clientes usada para acessar o Postgres com autenticação baseada em token está configurada para estabelecer uma conexão SSL.

Obter um token OAuth em um fluxo de usuário para computador

Se você for um proprietário de banco de dados, administrador ou sua identidade do Azure Databricks tiver uma função postgres correspondente para a instância do banco de dados, você poderá obter um token OAuth da interface do usuário, da CLI do Databricks ou de um dos SDKs do Databricks. Você pode restringir o escopo do token adequadamente usando a CLI do Databricks.

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

interface do usuário

Quando o status da instância do banco de dados estiver disponível, use a interface do usuário do Azure Databricks para obter um token OAuth:

Clique em Compute na barra lateral do workspace e clique na guia Lakebase Provisionado.
Localize e clique no nome da instância do banco de dados para a qual você deseja obter um token OAuth.
Clique na guia Detalhes da conexão.
Clique em Obter Token OAuth. Um sinalizador indica quando o token foi criado.
Clique em Copiar OAuthToken para copiar o token para sua área de transferência.

CLI

Quando o Status da instância do banco de dados estiver Disponível, use a CLI do Databricks v0.256.0 ou posterior para obter um token OAuth:

Use o comando a seguir para buscar um token.

 databricks database generate-database-credential \
   --request-id $(uuidgen) \
   --json '{
     "instance_names": ["db-instance-name"]
   }'

Isso gera uma resposta no formato a seguir. Copie o token da resposta.

{
  "expiration_time": "2025-08-24T14:15:22Z",
  "token": "<string>"
}

Para obter mais informações sobre como usar a CLI do Databricks para obter um token OAuth, consulte a autenticação U2M (usuário para máquina) do OAuth.

SDK do Python

Você pode gerar um token OAuth usando o SDK do Databricks para Python. As associações do SDK do Azure Databricks estão disponíveis no SDK do Databricks para Python versão v0.56.0.

Se você estiver executando com uma versão mais antiga do SDK, execute esses comandos primeiro.

%pip install --upgrade databricks-sdk
%restart_python

O SDK do Databricks para Python gera um token credOAuth seguro para sua instância de banco de dados. Insira suas credenciais quando necessário.

from databricks.sdk import WorkspaceClient
import uuid

w = WorkspaceClient()

instance_name = "<YOUR INSTANCE>"

cred = w.database.generate_database_credential(request_id=str(uuid.uuid4()), instance_names=[instance_name])

Java SDK

Você pode gerar um token OAuth usando o SDK do Databricks para Java. As associações do SDK do banco de dados estão disponíveis no SDK do Databricks para a versão java v0.53.0 ou superior. Se você estiver executando com uma versão mais antiga do SDK, talvez seja necessário atualizar o SDK importado. Para obter mais informações, consulte aqui.

%scala

import com.databricks.sdk.WorkspaceClient
import com.databricks.sdk.service.database.GetDatabaseInstanceRequest
import com.databricks.sdk.service.database.GenerateDatabaseCredentialRequest
import com.databricks.sdk.service.database.DatabaseInstance
import com.databricks.sdk.service.database.DatabaseCredential
import java.util.Collections
import java.util.UUID

val w = new WorkspaceClient()

val instanceName = "<YOUR INSTANCE>"

// Generate database credential
val cred = w.database().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setRequestId(UUID.randomUUID().toString())
        .setInstanceNames(Collections.singletonList(instanceName))
)

// Print out credential details
System.out.println("Credential: " + cred.getToken())

Obter um token OAuth em um fluxo de máquina para máquina

Para habilitar o acesso seguro e automatizado (máquina a máquina) à instância do banco de dados, você deve obter um token OAuth usando um principal de serviço do Azure Databricks. Esse processo envolve a configuração do principal de serviço, a geração de credenciais e a emissão de tokens OAuth para autenticação.

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 Azure Databricks com o OAuth.

Novos tokens OAuth do Mint como a entidade de serviço.

CLI

Quando o Status da instância do banco de dados estiver Disponível, use a CLI do Databricks v0.256.0 ou posterior para obter um token OAuth:

Use o comando a seguir para buscar um token.

  databricks database generate-database-credential \
    --request-id $(uuidgen) \
    --json '{
      "instance_names": ["db-instance-name"]
    }'

Isso gera uma resposta no formato a seguir. Copie o token da resposta.

{
  "expiration_time": "2025-08-24T14:15:22Z",
  "token": "<string>"
}

SDK do Python

Você pode gerar um token OAuth usando o SDK do Databricks para Python. As associações do SDK do Azure Databricks estão disponíveis no SDK do Databricks para Python versão v0.56.0.

Se você estiver executando com uma versão mais antiga do SDK, execute esses comandos primeiro.

%pip install --upgrade databricks-sdk
%restart_python

O SDK do Databricks para Python gera um token credOAuth seguro para sua instância de banco de dados. Insira o nome da instância do banco de dados quando necessário.

from databricks.sdk import WorkspaceClient
import uuid

w = WorkspaceClient(
  host          = "https://<YOUR WORKSPACE URL>/",
  client_id     = "<YOUR SERVICE PRINCIPAL ID>",
  client_secret = "REDACTED"
)

instance_name = "<YOUR INSTANCE>"

cred = w.database.generate_database_credential(request_id=str(uuid.uuid4()), instance_names=[instance_name])

Java SDK

Você pode gerar um token OAuth usando o SDK do Databricks para Java. As associações do SDK do banco de dados estão disponíveis no SDK do Databricks para a versão java v0.53.0 ou superior. Se você estiver executando com uma versão mais antiga do SDK, talvez seja necessário atualizar para um SDK mais recente. Para obter mais informações, consulte aqui.

%scala

import com.databricks.sdk.WorkspaceClient
import com.databricks.sdk.core.DatabricksConfig
import com.databricks.sdk.service.database.GetDatabaseInstanceRequest
import com.databricks.sdk.service.database.GenerateDatabaseCredentialRequest
import com.databricks.sdk.service.database.DatabaseInstance
import com.databricks.sdk.service.database.DatabaseCredential
import java.util.Collections
import java.util.UUID

val config = new DatabricksConfig() // See https://github.com/databricks/databricks-sdk-java#authentication
val w = new WorkspaceClient(config)

val instanceName = "<YOUR INSTANCE>"

// Generate database credential
val cred = w.database().generateDatabaseCredential(
    new GenerateDatabaseCredentialRequest()
        .setRequestId(UUID.randomUUID().toString())
        .setInstanceNames(Collections.singletonList(instanceName))
)

// Print out credential details
System.out.println("Credential: " + cred.getToken())

Observação

Gire tokens OAuth antes da expiração horária:

Verifique a hora de expiração do token OAuth em cada uso e atualização quando necessário.
Como alternativa, configure um thread em segundo plano para atualizar periodicamente o token OAuth atual.

Solucionar problemas de identidade de token

Se a identidade do token não corresponder ao rótulo de segurança, você poderá receber uma mensagem de erro como a seguinte.

A valid oauth token was supplied but the token's identity "<USER>" did not match the security label configured for role "<SERVICE PRINCIPAL>". Please ensure that the token is generated for the correct databricks identity.

Execute o seguinte comando para verificar qual identidade do Azure Databricks é retornada:

CLI

databricks current-user me

SDK do Python

w.current_user.me().user_name

Java SDK

w.currentUser.me().getUserName()

Se a identidade esperada não for retornada, verifique se as credenciais corretas foram usadas ao inicializar o cliente do workspace.

Autenticar com a ID do Microsoft Entra

Para o Azure Databricks, as identidades e tokens do Microsoft Entra ID também podem ser usados para autenticar nas APIs do Azure Databricks. Use essas APIs para obter um token para autenticar no Postgres.

Consulte Gerenciar usuários, entidades de serviço e grupos para saber como gerenciar identidades gerenciadas da ID do Microsoft Entra no Azure Databricks. Usuários, grupos e principais de serviço do Microsoft Entra ID podem ser criados no Azure Databricks. Depois que essas identidades forem adicionadas ao Azure Databricks, você poderá adicioná-las à instância do banco de dados, conforme descrito nas funções Gerenciar Postgres.

Para recuperar tokens de ID do Microsoft Entra, confira o seguinte:

Autenticar como grupo do Azure Databricks

Grupos e associações de grupo não são sincronizados do Azure Databricks com o Postgres e nem as permissões do Catálogo do Unity. No entanto, depois que um grupo do Azure Databricks é adicionado ao Postgres, qualquer usuário do Azure Databricks no grupo pode fazer logon como o grupo usando a senha do usuário. Isso permite que você gerencie permissões no nível do grupo no Postgres. Qualquer membro direto ou indireto (usuário ou entidade de serviço) da identidade do grupo do Azure Databricks pode se autenticar no Postgres e fazer logon como a função postgres do grupo do Azure Databricks.

Ao autenticar como uma identidade de grupo usando um token de usuário ou serviço principal, a associação ao grupo é validada somente no momento da autenticação. Qualquer conexão aberta com um token de membro de grupo permanecerá aberta se o membro for removido do grupo após a autenticação. Qualquer nova solicitação de conexão de um membro do grupo removido é rejeitada durante a autenticação.

export PGPASSWORD='<OAuth token of a group member>'
export GROUPROLENAME=<pg-case-sensitive-group-role-name>

psql -h $HOSTNAME -p 5432 -d databricks_postgres -U $GROUPROLENAME

Somente grupos atribuídos ao workspace do Azure Databricks da instância do banco de dados têm suporte para logon do Postgres baseado em grupo. Para saber como atribuir um grupo a um workspace, consulte Atribuir um grupo a um workspace.

Autenticar com funções e senhas do Postgres

Se você tiver clientes que não dão suporte à rotação de credenciais após uma hora, você poderá criar funções postgres nativas com senhas:

Clique em Computação na barra lateral do workspace.
Clique na guia Instâncias do Banco de Dados .
Selecione a instância do banco de dados que você deseja atualizar.
Clique em Editar no canto superior direito.
Ative Habilitar Logon de Função Nativa do Postgres.
Clique em Salvar.
Faça logon no Postgres ou use o Editor de SQL para criar uma função com uma senha.
```
CREATE ROLE new_role LOGIN PASSWORD 'your strong password';
```
Conceda permissões adicionais do Postgres à nova função. Confira conceder privilégios para roles do Postgres usando PostgreSQL.

Próximas etapas

Depois de obter uma credencial (token OAuth ou senha), você pode se conectar à instância do banco de dados:

Comentários

Esta página foi útil?

Last updated on 2025-12-18

Compartilhar via

Autenticar em uma instância de banco de dados

Autenticar com identidades do Azure Databricks

Considerações antes de começar

Obter um token OAuth em um fluxo de usuário para computador

interface do usuário

CLI

SDK do Python

Java SDK

Obter um token OAuth em um fluxo de máquina para máquina

CLI

SDK do Python

Java SDK

Solucionar problemas de identidade de token

CLI

SDK do Python

Java SDK

Autenticar com a ID do Microsoft Entra

Autenticar como grupo do Azure Databricks

Autenticar com funções e senhas do Postgres

Próximas etapas

Comentários

Recursos adicionais