Autorizar o acesso da entidade de serviço ao Azure Databricks com o 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 usa o OAuth 2.0 como o protocolo preferencial para autorização e autenticação da entidade 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 a 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.

Maneiras de autorizar uma entidade de serviço

O Azure Databricks dá suporte a duas maneiras de autorizar uma entidade de serviço:

• Automático (recomendado): Use autenticação unificada com ferramentas e SDKs com suporte, como o SDK do Terraform do Azure Databricks. 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 uma entidade de serviço do Azure Databricks. Consulte Adicionar entidades de serviço à sua conta.
2. Vá para a guia Configuração da entidade de serviço e selecione os direitos que ela deve ter para esse workspace.
3. Acesse a guia Permissões e conceda acesso a todos os usuários, entidades de serviço e grupos do Azure Databricks que você deseja gerenciar e usar essa entidade de serviço. Veja 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. Uma entidade 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. Na página de detalhes da entidade de serviço, abra a guia Segredos .
2. Em Segredos do OAuth, clique em Gerar segredo.
3. Defina o tempo de vida do segredo em dias (no máximo 730 dias).
4. 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ário , selecione a entidade de serviço e, em seguida, vá para a guia Credenciais > 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 associados, campos do Terraform .databrickscfg ou 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 como o valor da URL do console da conta do 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 como o valor da URL por workspace do Azure Databricks, 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>

Ao autorizar com entidades de serviço do Azure AD, as chaves de configuração diferem das entidades de serviço gerenciadas pelo Azure Databricks:

host = https://<workspace-url>
azure_client_id = <azure-service-principal-client-id>
azure_client_secret = <azure-service-principal-secret>
azure_tenant_id = <azure-tenant-id>

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 os valores de nível de espaço de trabalho em seu .databrickscfg arquivo, conforme descrito na guia Perfil. Defina também a URL da instância do cluster_id espaço de trabalho.
• Use variáveis de ambiente: Defina os mesmos valores mostrados na guia Ambiente. Além disso, defina o URL da instância da sua área de trabalho.

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

Na extensão do Databricks para Visual Studio Code, faça o seguinte:

1. Defina os valores em seu .databrickscfg arquivo para operações no nível do workspace do Azure Databricks, conforme especificado na guia Perfil .
2. No painel Configuração da extensão do Databricks para Visual Studio Code, clique em Configurar o 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 obter mais detalhes, consulte Configurar a autorização para a extensão do Databricks para o Visual Studio Code.

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 retrieve espaços reservados por sua própria implementação para recuperar os valores do console ou de algum outro repositório de configuração, como o HashiCorp Vault. Consulte também o Provedor do Cofre. Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net.

Operações no nível do workspace

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 retrieve espaços reservados por sua própria implementação para recuperar os valores do console ou de algum outro repositório de configuração, como o HashiCorp Vault. Consulte também o Provedor do Cofre. 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 retrieve espaços reservados por 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 workspace

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 retrieve espaços reservados por sua própria implementação para recuperar os valores do console ou 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 workspace

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 retrieve espaços reservados por sua própria implementação para recuperar os valores do console ou 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 retrieve espaços reservados por sua própria implementação para recuperar os valores do console ou 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 workspace

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 retrieve espaços reservados por sua própria implementação para recuperar os valores do console ou 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, use a ID do cliente da entidade de serviço e o segredo do OAuth. 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: Use para chamar as APIs REST no nível da conta e do workspace em contas e workspaces que a entidade de serviço pode acessar. 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 do workspace.

Gerar um token de acesso no nível da conta

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

1. Localize a ID da conta.

2. Construa a URL do ponto de extremidade de token substituindo <account-id> na URL a seguir pela ID da 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 a ID do cliente da entidade de serviço (ID do aplicativo).
   • <client-secret> com o segredo OAuth da entidade de serviço.

   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 a entidade de serviço chame qualquer API REST do Databricks que 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 no nível do workspace somente com APIs REST nesse workspace.

1. Construa a URL do ponto de extremidade de token substituindo-a <databricks-instance><databricks-instance> pelo 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 a ID do cliente da entidade de serviço (ID do aplicativo).
   • <client-secret> com o segredo OAuth da entidade de serviço.

   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.

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, a entidade de serviço deve ser um administrador de conta.

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

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 a ID da 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 workspace 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 está definido como a ID do aplicativo da entidade de serviço (ID do cliente) e DATABRICKS_CLIENT_SECRET é definido como o valor do segredo OAuth, ambos sem espaços adicionais.
• Anfitrião:DATABRICKS_HOST aponta para https://accounts.azuredatabricks.net para operações de conta ou a URL de destino para cada 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. Executar env | grep DATABRICKS e desfazer conflitos.
• Ferramentas: Use a autenticação unificada e as 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.
• Emissor de token incorreto: Para M2M, use o ponto de extremidade do token OAuth do Databricks, não o IdP ou o ponto de extremidade do token de nuvem.
• Incompatibilidade de host: Se você se autenticar para APIs de workspace, DATABRICKS_HOST deverá ser a URL do workspace que você chama.

403 Proibido

Causas e correções prováveis:

• Permissões de recurso ausentes: Conceda permissões ao principal de serviço CAN USE ou CAN MANAGE em clusters ou SQL Warehouses, e as permissões de nível de objeto necessárias para notebooks, trabalhos ou objetos de dados.
• Nenhuma atribuição de espaço de trabalho: Atribua um principal de serviço ao espaço de trabalho 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 tempos limite, "host não encontrado", "conta não encontrada" ou "espaço de trabalho não encontrado".

Fixes:

• Regras de host: Use a URL do console da conta para 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