Autenticar em uma instância de banco de dados

Importante

Esta funcionalidade está na Pré-visualização Pública nas seguintes regiões: westus, westus2, eastus, eastus2, centralussouthcentralusnortheuropewesteuropeaustraliaeastbrazilsouthcanadacentralcentralindiasoutheastasiauksouth.

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

1. Obtenha um token OAuth e autentique-se usando identidades do Azure Databricks.
2. Use funções nativas do Postgres 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 uma 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 apenas no login. 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 espaço de trabalho e devem pertencer ao mesmo espaço de trabalho que possui a instância do banco de dados. Não há suporte para autenticação de token entre espaços de trabalho. Para saber mais sobre autenticação, consulte Autenticação para a CLI do Databricks.

• A autenticação baseada em tokens requer uma senha de texto sem formatação, portanto, apenas conexões SSL são permitidas. Certifique-se de que a biblioteca de cliente que você usa para acessar o Postgres com autenticação baseada em token esteja configurada para estabelecer uma conexão SSL.

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

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 de banco de dados, 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 OAuth para obter as instruções de autorização no nível do espaço de trabalho para obter tokens OAuth.

IU

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

1. Clique em Calcular na barra lateral do espaço de trabalho e clique no separador Lakebase Provisioned .
2. Encontre e clique no nome da instância da base de dados para a qual quer obter um token OAuth.
3. Clique no separador Detalhes da conexão.
4. Clica em Obter Token OAuth. Um sinalizador indica quando o token foi criado.
5. Clique em Copiar OAuthToken para colocar o token na sua área de transferência.

CLI

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

1. Use o comando a seguir para buscar um token.

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

2. Isso gera uma resposta no seguinte formato. 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 Autenticação de usuário para máquina (U2M) OAuth.

Python SDK

Você pode gerar um token OAuth usando o Databricks SDK for 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 OAuth seguro, cred, para sua instância de banco de dados. Insira suas credenciais onde 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])

SDK de Java

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 Java versão 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 num fluxo máquina-a-máquina

Para habilitar o acesso seguro e automatizado (máquina a máquina) à instância do banco de dados, deve-se obter um token OAuth usando um principal de serviço do Azure Databricks. Este processo envolve configurar o principal de serviço, gerar credenciais e obter 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 Azure Databricks com OAuth.

2. Mint novos tokens OAuth como o principal de serviço.

   CLI

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

   1. Use o comando a seguir para buscar um token.

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

   2. Isso gera uma resposta no seguinte formato. Copie o token da resposta.

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

   Python SDK

   Você pode gerar um token OAuth usando o Databricks SDK for 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 OAuth seguro, cred, para sua instância de banco de dados. Insira o nome da instância do banco de dados onde 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])
   

   SDK de Java

   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 Java versão 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

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

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

Solucionar problemas de identidade de token

Se a identidade do seu 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

Python SDK

w.current_user.me().user_name

SDK de Java

w.currentUser.me().getUserName()

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

Autenticar com o Microsoft Entra ID

Para Azure Databricks, podem também ser utilizadas as identidades e tokens do Microsoft Entra ID 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 do Microsoft Entra ID no Azure Databricks. Usuários, grupos e entidades 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 em Gerenciar funções do Postgres.

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

• Obtenha tokens de ID do Microsoft Entra para Usuários.
• Obter tokens de identificação do Microsoft Entra para entidades de serviço

Autenticar como grupo do Azure Databricks

Os grupos e associações de grupo não são sincronizados do Azure Databricks para o Postgres e nem as permissões do Catálogo 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 Azure Databricks pode autenticar-se no Postgres e fazer logon como a função Postgres do grupo Azure Databricks.

Ao autenticar como uma identidade de grupo usando um token de entidade principal de usuário ou de serviço, a associação ao grupo é validada somente no momento da autenticação. Qualquer conexão aberta com um token de membro do grupo permanece 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 os grupos atribuídos ao espaço de trabalho do Azure Databricks da instância de banco de dados têm suporte para o logon do Postgres baseado em grupo. Para saber como atribuir um grupo a um espaço de trabalho, consulte Atribuir um grupo a um espaço de trabalho.

Autenticar com funções e senhas do Postgres

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

1. Clique em Computação na barra lateral do espaço de trabalho.

2. Clique na guia Instâncias de banco de dados .

3. Selecione a instância do banco de dados que você deseja atualizar.

4. Clique em Editar no canto superior direito.

5. Ative Ativar login de função nativa do Postgres.

6. Clique em Salvar.

7. Faça login no Postgres ou use o Editor SQL para criar uma função com uma senha.

   CREATE ROLE new_role LOGIN PASSWORD 'your strong password';
   

8. Conceda permissões Postgres adicionais para a nova função. Consulte conceder privilégios a funções do Postgres usando o PostgreSQL.

Próximos passos

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

• Acessar uma instância de banco de dados a partir de clientes SQL
• Usar um caderno para aceder a uma instância de base de dados