Autorize o acesso da entidade de serviço ao Azure Databricks usando OAuth

Esta página explica como autorizar o acesso aos recursos do Azure Databricks de processos autônomos, como comandos automatizados da CLI ou chamadas à API REST feitas de scripts ou aplicativos.

O Azure Databricks utiliza OAuth 2.0 como o protocolo preferencial para autenticação e autorização de entidades de serviço fora da interface do usuário. A autenticação unificada do cliente automatiza a geração e a atualização de token. Quando uma entidade de serviço entra e recebe consentimento, o OAuth emite um token de acesso para a CLI, o SDK ou outra ferramenta para ser usada em seu nome. Cada token de acesso é válido por uma hora, após a qual um novo token é solicitado automaticamente.

Nesta página, a autorização refere-se ao uso do OAuth para conceder a uma entidade de serviço acesso aos recursos do Azure Databricks, enquanto a autenticação refere-se à validação de credenciais por meio de tokens de acesso.

Para obter mais detalhes de alto nível, consulte Autorizar o acesso aos recursos do Azure Databricks.

Formas de autorizar um service principal

O Azure Databricks dá suporte a duas maneiras de autorizar um principal de serviço:

• Automático (recomendado): Use autenticação unificada com ferramentas e SDKs compatíveis, como o Azure Databricks Terraform SDK. Essa abordagem lida com a geração e a atualização de tokens automaticamente e é ideal para automação ou outras cargas de trabalho autônomas.

• Manual: Gere um verificador de código e um desafio e, em seguida, troque-os por um token OAuth. Use esse método se sua ferramenta ou API não der suporte à autenticação unificada. Talvez seja necessário criar seu próprio mecanismo de atualização de token para seu aplicativo. Para obter detalhes, consulte Gerar manualmente tokens de acesso OAuth M2M.

Pré-requisitos

Antes de configurar o OAuth, execute as seguintes etapas:

1. Crie um service principal do Azure Databricks. Consulte Adicione entidades de serviço à sua conta.
2. Vá para a aba Configuração do service principal e selecione as permissões que ele deve ter para este workspace.
3. Acesse a guia Permissões e conceda acesso a qualquer usuário, principal de serviço e grupo do Azure Databricks que você deseja que gerencie e use este principal de serviço. Consulte Quem pode gerenciar e usar entidades de serviço?.

Etapa 1: Criar um segredo OAuth

Para autorizar o acesso aos recursos do Azure Databricks com o OAuth, você deve criar um segredo OAuth. O segredo é usado para gerar tokens de acesso OAuth para autenticação. Um principal de serviço pode ter até cinco segredos OAuth e cada segredo pode ser válido por até dois anos.

Os administradores de conta e administradores de workspace podem criar um segredo do OAuth para uma entidade de serviço.

1. Clique no nome de usuário na barra superior e selecione Configurações.
2. Clique na guia Identidade e acesso .
3. Ao lado de Entidades de serviço, clique em Gerenciar.
4. Selecione a entidade de serviço.
5. Clique na guia Segredos.
6. Clique em Gerar segredo.
7. Defina o tempo de vida do segredo em dias (no máximo 730 dias).
8. Clique em Gerar.
9. Copie o segredo exibido e a ID do cliente e clique em Concluído. O segredo é mostrado apenas uma vez. A ID do cliente é a mesma que a ID do aplicativo da entidade de serviço.

Os administradores de conta também podem criar um segredo OAuth no console da conta. Na guia Gerenciamento de Usuários, selecione o principal do serviço e, em seguida, vá para a guia Credenciais e segredos.

Etapa 2: Usar a autorização do OAuth

Para usar a autorização OAuth com a ferramenta de autenticação unificada, você deve definir as seguintes variáveis ​​de ambiente associadas, campos .databrickscfg, campos Terraform ou campos Config:

• O host do Azure Databricks, especificado como https://accounts.azuredatabricks.net para operações de conta ou a URL por workspace de destino, por exemplo https://adb-1234567890123456.7.azuredatabricks.net para as operações do workspace.
• A ID da conta do Azure Databricks para as operações de conta do Azure Databricks.
• A ID do cliente da entidade de serviço.
• O segredo da entidade de serviço.

Para executar a autenticação da entidade de serviço do OAuth, integre o seguinte em seu código, com base na ferramenta participante ou no SDK:

Ambiente

Para usar variáveis de ambiente para um tipo de autenticação específico do Azure Databricks com uma ferramenta ou SDK, consulte Autorizar o acesso aos recursos do Azure Databricks ou à documentação da ferramenta ou do SDK. Consulte também variáveis de ambiente e campos para autenticação unificada e a prioridade do método de autenticação.

Para operações no nível da conta, defina as seguintes variáveis de ambiente:

• DATABRICKS_HOST, definido pelo valor da URL do console da sua conta no Azure Databricks. https://accounts.azuredatabricks.net
• DATABRICKS_ACCOUNT_ID
• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET

Para as operações no nível do workspace, defina as seguintes variáveis de ambiente:

• DATABRICKS_HOST, definido com o valor da sua URL do Azure Databricks por workspace, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.
• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET

Perfil

Crie ou identifique um perfil de configuração do Azure Databricks com os seguintes campos em seu arquivo do .databrickscfg. Se você criar o perfil, substitua os espaços reservados pelos valores apropriados. Para usar o perfil com uma ferramenta ou SDK, consulte Autorizar o acesso aos recursos do Azure Databricks ou à documentação da ferramenta ou do SDK. Consulte também variáveis de ambiente e campos para autenticação unificada e a prioridade do método de autenticação.

Para as operações no nível da conta, defina os seguintes valores em seu arquivo .databrickscfg. Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net:

[<some-unique-configuration-profile-name>]
host          = <account-console-url>
account_id    = <account-id>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

Para operações no nível do espaço de trabalho, defina os seguintes valores no seu arquivo .databrickscfg. Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net:

[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

CLI

Para a CLI do Databricks, siga um destes procedimentos:

• Defina as variáveis de ambiente conforme especificado na guia Ambiente .
• Defina os valores em seu .databrickscfg arquivo, conforme especificado na guia Perfil .

As variáveis de ambiente sempre têm precedência sobre os valores do arquivo .databrickscfg.

Veja também Autenticação de máquina a máquina (M2M) do OAuth.

Conectar

Você pode fazer o seguinte com o Databricks Connect:

• Use um perfil de configuração: Defina valores no nível do workspace no arquivo .databrickscfg, conforme descrito na guia Perfil. Defina também a URL da instância do workspace cluster_id.
• Use variáveis de ambiente: Defina os mesmos valores mostrados na guia Ambiente. Também defina a URL da instância do workspace DATABRICKS_CLUSTER_ID.

Os valores em .databrickscfg têm precedência sobre as variáveis de ambiente.

Para inicializar o Databricks Connect com essas configurações, consulte a configuração de computação do Databricks Connect.

VS Code

Para a extensão do IDE Databricks, faça o seguinte:

1. Defina os valores no seu arquivo .databrickscfgpara as operações em nível de workspaces para Azure Databricks conforme especificado na aba Perfil.
2. No painel de Configuração da extensão do IDE Databricks, clique em Configurar Databricks.
3. Na Paleta de Comandos, em Host do Databricks, insira a URL por workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net, e pressione Enter.
4. Na Paleta de Comandos, selecione o nome do perfil de destino na lista de URL.

Para mais detalhes, veja Configurar autorização para a extensão do IDE Databricks.

Terraformação

Operações no nível da conta

Para autenticação padrão:

provider "databricks" {
  alias = "accounts"
}

Para configuração direta:

provider "databricks" {
  alias         = "accounts"
  host          = <retrieve-account-console-url>
  account_id    = <retrieve-account-id>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

Substitua os espaços reservados retrieve pela sua própria implementação para recuperar os valores do console ou de outro repositório de configurações, como HashiCorp Vault. Consulte também Vault Provider. Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net.

Operações no nível do espaço de trabalho

Para configuração padrão:

provider "databricks" {
  alias = "workspace"
}

Para configuração direta:

provider "databricks" {
  alias         = "workspace"
  host          = <retrieve-workspace-url>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

Substitua os espaços reservados retrieve pela sua própria implementação para recuperar os valores do console ou de outro repositório de configurações, como HashiCorp Vault. Consulte também Vault Provider. Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

Para obter mais informações sobre como autenticar com o provedor Terraform do Databricks, veja Autenticação.

Python

Operações no nível da conta

Para configuração padrão:

from databricks.sdk import AccountClient

a = AccountClient()
# ...

Para configuração direta:

from databricks.sdk import AccountClient

a = AccountClient(
  host          = retrieve_account_console_url(),
  account_id    = retrieve_account_id(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

Substitua os espaços reservados retrieve pela sua própria implementação para recuperar os valores do console ou de outro repositório de configuração, como o Azure KeyVault. Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net.

Operações no nível do espaço de trabalho

Para configuração padrão:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para configuração direta:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host          = retrieve_workspace_url(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

Substitua os marcadores retrieve por sua própria implementação para obter os valores do console ou de outro repositório de configuração, como o Azure KeyVault. Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

Para obter mais informações sobre como autenticar com ferramentas do Databricks e SDKs que usam Python e implementam a autenticação unificada, consulte:

• Configurar o cliente do Databricks Connect para o Python
• Autenticar o SDK do Databricks para o Python com sua conta ou workspace do Azure Databricks

Java

Operações no nível do espaço de trabalho

Para configuração padrão:

import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

Para configuração direta:

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveWorkspaceUrl())
  .setClientId(retrieveClientId())
  .setClientSecret(retrieveClientSecret());
WorkspaceClient w = new WorkspaceClient(cfg);
// ...

Substitua os marcadores retrieve por sua própria implementação para obter os valores do console ou de outro repositório de configuração, como o Azure KeyVault. Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

Para obter mais informações sobre como autenticar com ferramentas e SDKs do Databricks que usam Java e implementam a autenticação unificada, consulte:

• Configurar o cliente do Databricks Connect para o Scala (o cliente do Databricks Connect para o Scala usa o SDK do Databricks incluído para o Java para autenticação)
• Autenticar o SDK do Databricks para o Java com sua conta ou workspace do Azure Databricks

Go

Operações no nível da conta

Configuração padrão:

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
a := databricks.Must(databricks.NewAccountClient())

Para configuração direta:

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient(&databricks.Config{
  Host:         retrieveWorkspaceUrl(),
  ClientId:     retrieveClientId(),
  ClientSecret: retrieveClientSecret(),
}))
// ...

Substitua os marcadores retrieve por sua própria implementação para obter os valores do console ou de outro repositório de configuração, como o Azure KeyVault. Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net.

Operações no nível do espaço de trabalho

Para configuração padrão:

import "github.com/databricks/databricks-sdk-go"

// Uses environment configuration automatically
w := databricks.Must(databricks.NewWorkspaceClient())

Para configuração direta:

import "github.com/databricks/databricks-sdk-go"
// ...
w := databricks.Must(databricks.NewWorkspaceClient(&databricks.Config{
    Host:         retrieveAccountConsoleUrl(),
    ClientId:     retrieveClientId(),
    ClientSecret: retrieveClientSecret(),
}))
// ...

Substitua os marcadores retrieve por sua própria implementação para obter os valores do console ou de outro repositório de configuração, como o Azure KeyVault. Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

Para obter mais informações sobre como autenticar com as ferramentas e SDKs do Databricks que usam o Go e que implementam a autenticação unificada do cliente do Databricks, veja Autenticar o SDK do Databricks para o Go com sua conta ou workspace do Azure Databricks.

Gerar manualmente tokens de acesso OAuth M2M

Esta seção destina-se a ferramentas ou serviços que não dão suporte à autenticação unificada do Databricks. Se você precisar gerar, atualizar ou usar manualmente tokens OAuth do Azure Databricks para autenticação M2M, siga estas etapas.

Para gerar um token de acesso OAuth M2M, utilize o ID do cliente e o segredo OAuth da entidade de serviço. Cada token de acesso é válido por uma hora. Depois de expirar, solicite um novo token. Você pode gerar tokens no nível da conta ou do workspace:

• Nível da conta: utilize para chamar APIs REST tanto em nível de conta quanto em nível de workspace, em contas e workspaces aos quais a entidade de serviço tenha acesso. Consulte Gerar um token de acesso no nível da conta.
• Nível do workspace: Use para chamar APIs REST em um único workspace. Consulte Gerar um token de acesso no nível de área de trabalho.

Gerar um token de acesso no nível da conta

Use um token de nível de conta para chamar APIs REST para a conta e para quaisquer workspaces que a entidade de serviço possa acessar.

1. Localize a ID da conta.

2. Construa a URL do endpoint de token substituindo <account-id> na URL a seguir pelo ID da sua conta.

   https://accounts.azuredatabricks.net/oidc/accounts/<my-account-id>/v1/token
   

3. Use curl para solicitar um token de acesso OAuth. Replace:

   • <token-endpoint-URL> com a URL acima.
   • <client-id> com o ID do cliente (ID do aplicativo) do service principal.
   • <client-secret> com o segredo OAuth do service principal.

   export CLIENT_ID=<client-id>
   export CLIENT_SECRET=<client-secret>
   
     curl --request POST \
     --url <token-endpoint-URL> \
     --user "$CLIENT_ID:$CLIENT_SECRET" \
     --data 'grant_type=client_credentials&scope=all-apis'
   

   Isso gera uma resposta semelhante a:

   {
     "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
     "token_type": "Bearer",
     "expires_in": 3600
   }
   

   O all-apis escopo solicita um token de acesso OAuth que permite que o serviço principal chame qualquer API REST do Databricks que ele tenha permissão para acessar.

4. Copie o access_token valor da resposta.

Gerar um token de acesso no nível do workspace

Use um token de nível de workspace apenas com APIs REST nesse workspace.

1. Construa a URL do endpoint de token substituindo <databricks-instance> pelo seu <databricks-instance> com o nome da instância do workspace do Azure Databricks, por exemplo, adb-1234567890123456.7.azuredatabricks.net:

   https://<databricks-instance>/oidc/v1/token
   

2. Use curl para solicitar um token de acesso OAuth. Replace:

   • <token-endpoint-URL> com a URL acima.
   • <client-id> com o ID do cliente (ID do aplicativo) do service principal.
   • <client-secret> com o segredo OAuth do service principal.

   export CLIENT_ID=<client-id>
   export CLIENT_SECRET=<client-secret>
   
   curl --request POST \
   --url <token-endpoint-URL> \
   --user "$CLIENT_ID:$CLIENT_SECRET" \
   --data 'grant_type=client_credentials&scope=all-apis'
   

   Isso gera uma resposta semelhante a:

   {
     "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
     "token_type": "Bearer",
     "expires_in": 3600
   }
   

3. Copie o access_token valor da resposta.

Assumir uma função

Um service principal pode assumir uma função ao solicitar um token de acesso em nível de workspace. Quando um service principal assume uma função, as permissões da função substituem as do próprio service principal. No Azure Databricks, uma função é implementada como um grupo, e o service principal deve ter a permissão Assume nesse grupo. Para obter mais informações, consulte RBAC (controle de acesso baseado em função).

Para assumir uma função, adicione o assume_group parâmetro à solicitação de token:

export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis&assume_group=<group-id>'

Substitua <group-id> pelo ID numérico do grupo de suporte da função.

Supondo que uma função tenha os seguintes requisitos e limitações:

• Compatível apenas com tokens em nível de workspace. Se você incluir assume_group em uma solicitação de token no nível da conta, a solicitação falhará.
• O service deve ter a permissão Assume no grupo. Se isso não acontecer, a solicitação falhará. Para conceder a Assume, consulte Gerenciar permissões em um grupo.

Para obter mais informações sobre como alternar funções, consulte Alternar funções.

Chamar uma API REST do Azure Databricks

Use o token de acesso OAuth para chamar APIs REST no nível da conta ou do workspace . Para chamar APIs no nível da conta, o principal de serviço deve ser um administrador de conta.

Inclua o token no cabeçalho de autorização com a autenticação Bearer.

Exemplo de solicitação da API REST no nível da conta

Este exemplo lista todos os workspaces de uma conta. Replace:

• <oauth-access-token> com o token de acesso OAuth da entidade de serviço.
• <account-id> com o ID da sua conta.

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.azuredatabricks.net/api/2.0/accounts/<account-id>/workspaces'

Exemplo de solicitação da API REST no nível do workspace

Este exemplo lista todos os clusters disponíveis em um workspace. Replace:

• <oauth-access-token> com o token de acesso OAuth da entidade de serviço.
• <databricks-instance> com o nome da instância do espaço de trabalho do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net.

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

Solucionar problemas de autenticação do OAuth M2M

Use estas etapas para corrigir os problemas mais comuns com a autenticação OAuth M2M do Databricks para entidades de serviço.

Verificações rápidas

Comece verificando esses problemas comuns de configuração que causam falhas de autenticação OAuth M2M:

• Credenciais:DATABRICKS_CLIENT_ID é definido como o ID do aplicativo (ID do cliente) do service principal, e DATABRICKS_CLIENT_SECRET é definido como o valor do segredo OAuth, ambos sem espaços extras.
• Host:DATABRICKS_HOST aponta para https://accounts.azuredatabricks.net para operações de conta ou para o destino URL por workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net para operações de workspace. Não inclua /api.
• Designação: O principal de serviço é atribuído ao espaço de trabalho de destino.
• Permissões: O principal do serviço tem as permissões necessárias no recurso de destino.
• Conflitos: Nenhum conjunto de variáveis conflitantes, como DATABRICKS_TOKEN, DATABRICKS_USERNAME. Execute env | grep DATABRICKS e remova os conflitos.
• Ferramentas: use autenticação unificada e versões atuais da CLI ou do SDK.

401 Não autorizado

Causas e correções prováveis:

• ID de cliente inválida ou segredo: Copiar novamente DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET. Regenerar o segredo se não tiver certeza.
• Segredo expirado: Crie um novo segredo se o atual tiver expirado.
• Wrong token issuer: para M2M, utilize o endpoint de token OAuth do Databricks, e não o endpoint de token do seu IdP ou da nuvem.
• Incompatibilidade de host: se você se autenticar para APIs de workspace, DATABRICKS_HOST deve ser a URL do workspace que você chama.

403 Proibido

Causas e correções prováveis:

• Permissões de recurso ausentes: conceda ao service principal CAN USE or CAN MANAGE acesso a clusters ou SQL warehouses, bem como as permissões necessárias em nível de objeto para notebooks, jobs ou objetos de dados.
• Nenhuma atribuição de workspace: atribua o service principal ao workspace no console da conta.
• Acesso à API de administrador: Para APIs exclusivas para administradores, atribua a entidade de serviço ao grupo de administradores do workspace ou conceda permissões de administrador de conta.

Problemas de configuração

Os sintomas incluem timeouts, “host não encontrado”, “conta não encontrada” ou “workspace não encontrado”.

Fixes:

• Regras do host: use a URL do console da conta para as APIs de conta. Use a URL do ambiente de trabalho para as APIs do ambiente de trabalho. Não inclua o /api sufixo.
• ID da conta: Forneça DATABRICKS_ACCOUNT_ID somente para operações de nível de conta. Use o UUID do console da conta.
• Seleção de perfil: Se você usar vários perfis, passe --profile <name> ou defina DATABRICKS_CONFIG_PROFILE.

Connectivity

Se a autenticação OAuth M2M falhar devido a problemas de rede, use estes testes para verificar se seu ambiente pode alcançar os endpoints do Databricks:

• DNS:nslookup <your-host> (deve retornar endereços IP para o nome do host)
• TLS e acessibilidade:curl -I https://<your-host> (deve retornar o status HTTP 200, 401 ou 403)
• Rede corporativa: Confirme se as regras de proxy ou firewall permitem HTTPS para endpoints do Databricks

Recursos adicionais

• Entidades de serviço
• Visão geral do Modelo de identidade do Databricks
• Informações adicionais sobre a autenticação e controle de acesso