Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth

Esta página explica como autorizar o acesso aos recursos do Azure Databricks a partir de processos autônomos, como comandos automatizados da CLI ou chamadas de API REST feitas a partir 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 de cliente unificada automatiza a geração e a atualização de tokens. Quando uma entidade de serviço entra e recebe consentimento, o OAuth emite um token de acesso para a CLI, 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, 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 se refere à validação de credenciais por meio de tokens de acesso.

Para obter mais detalhes de alto nível, consulte Autorizar 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 a autenticação unificada com ferramentas e SDKs suportados, como o SDK do Azure Databricks Terraform. Essa abordagem lida com a geração e 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 desafie e, em seguida, troque-os por um token OAuth. Use esse método se sua ferramenta ou API não oferecer 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:

Crie uma entidade de serviço do Azure Databricks. Consulte Adicionar entidades de serviço à sua conta.
Vá para a guia Configuração da entidade de serviço e selecione os direitos que ela deve ter para esse espaço de trabalho.
Vá para 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. Consulte Quem pode gerenciar e usar entidades de serviço?.

Etapa 1: Criar um segredo OAuth

Para autorizar o acesso aos seus recursos do Azure Databricks com OAuth, você deve criar um segredo OAuth. O segredo é usado para gerar tokens de acesso OAuth para autenticação. Um diretor 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 de espaço de trabalho podem criar uma chave OAuth para uma entidade de serviço.

Na página de detalhes da entidade de serviço, abra a guia Segredos .
Em Segredos OAuth, clique em Gerar segredo.
Defina a vida útil do segredo em dias (máximo 730 dias).
Copie o segredo exibido e a ID do cliente e clique em Concluído. O segredo é mostrado apenas uma vez. O ID do cliente é o mesmo que o ID do aplicativo da entidade de serviço.

Os administradores de conta também podem criar um segredo OAuth a partir do console da conta. Na guia Gerenciamento de usuários , selecione a entidade de serviço e vá para a guia Credenciais & segredos .

Nota

Para permitir que a entidade de serviço use clusters ou almacéns de SQL, deve-se conceder à entidade de serviço acesso a eles. Consulte Permissões de computação ou Gerenciar um armazém SQL.

Etapa 2: Usar a autorização OAuth

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

O host do Azure Databricks é especificado como https://accounts.azuredatabricks.net para operações de conta ou como a URL de destino por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net para operações de espaço de trabalho.
O ID da conta do Azure Databricks, para operações da conta Azure Databricks.
O identificador do cliente principal de serviço.
O segredo principal do serviço.

Para executar a autenticação da entidade de serviço OAuth, integre o seguinte em seu código, com base na ferramenta participante ou 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 a documentação da ferramenta ou do SDK. Consulte também Variáveis e campos de ambiente para autenticação unificada e a prioridade do método de autenticação.

Para operações ao 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 operações ao nível de espaço de trabalho , defina as seguintes variáveis de ambiente:

DATABRICKS_HOST, definido como o valor da URL do Azure Databricks por espaço de trabalho, 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 .databrickscfg arquivo. Se criares o perfil, substitui os marcadores pelos valores apropriados. Para usar o perfil com uma ferramenta ou SDK, consulte Autorizar o acesso aos recursos do Azure Databricks ou a documentação da ferramenta ou do SDK. Consulte também Variáveis e campos de ambiente para autenticação unificada e a prioridade do método de autenticação.

Para operações no nível da conta, defina os seguintes valores em seu .databrickscfg arquivo. 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 ao nível do espaço de trabalho , configure os seguintes valores no seu ficheiro .databrickscfg. Nesse caso, o host é a URL do Azure Databricks associada a cada espaço de trabalho, por exemplo :

[<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 em seu arquivo .databrickscfg.

Consulte também a autenticação máquina para máquina (M2M) OAuth.

Conectar

Nota

A autenticação do principal de serviço OAuth é suportada nas seguintes versões do Databricks Connect:

Para Python, Databricks Connect para Databricks Runtime 14.0 ou posterior.
Para Scala, Databricks Connect para Databricks Runtime 13.3 LTS e versões posteriores. O SDK do Databricks para Java incluído no Databricks Connect for Databricks Runtime 13.3 LTS e superior deve ser atualizado para o SDK do Databricks para Java 0.17.0 ou superior.

Para o Databricks Connect, você pode:

Use um perfil de configuração: Defina valores no nível do 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 . Defina também a URL da instância do DATABRICKS_CLUSTER_ID espaço de trabalho.

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

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

Código VS

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

Defina os valores em seu .databrickscfg arquivo para operações no nível do espaço de trabalho do Azure Databricks, conforme especificado na guia Perfil .
No painel Configuração da extensão Databricks para Visual Studio Code, clique em Configurar Databricks.
Na Paleta de comandos, para Databricks Host, insira sua URL por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net, e pressione Enter.
Na Paleta de comandos, selecione o nome do seu perfil de destino na lista associada ao seu URL.

Para obter mais detalhes, consulte Configurar autorização para a extensão Databricks para Visual Studio Code.

Terraformação

Operações ao 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 Provedor do Vault. 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 a 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 Provedor do Vault. Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.

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

Python

Operações ao nível da conta

Para a 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 espaço de trabalho

Para a 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 de outro repositório de configuração, como o Azure KeyVault. Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.

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

Nota

A extensão Databricks para Visual Studio Code usa Python, mas ainda não implementou a autenticação principal de serviço OAuth.

Java

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

Para a 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 de outro repositório de configuração, como o Azure KeyVault. Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.

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

Configure o cliente Databricks Connect para Scala (o cliente Databricks Connect para Scala usa o SDK Databricks incluído para Java para autenticação)
Autenticar o SDK do Databricks para Java com sua conta ou espaço de trabalho do Azure Databricks

Go

Operações ao 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(),
}))
// ...

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

Para a 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 de outro repositório de configuração, como o Azure KeyVault. Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net.

Para obter mais informações sobre a autenticação com ferramentas e SDKs do Databricks que usam o Go e que implementam a autenticação unificada do cliente Databricks, consulte Autenticar o SDK do Databricks para Go com sua conta ou espaço de trabalho do Azure Databricks.

Gerar manualmente tokens de acesso OAuth M2M

Esta seção é para ferramentas ou serviços que não suportam a autenticação unificada 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 o ID do cliente da entidade de serviço e o segredo OAuth. Cada token de acesso é válido por uma hora. Depois que expirar, solicite um novo token. Você pode gerar tokens no nível da conta ou do espaço de trabalho:

Nível da conta: Use para chamar APIs REST no nível da conta e no nível do espaço de trabalho em contas e espaços de trabalho que a entidade de serviço pode acessar. Consulte Gerar um token de acesso no nível da conta.
Nível do espaço de trabalho: Use para chamar APIs REST em um único espaço de trabalho. Consulte Gerar um token de acesso no nível do espaço de trabalho.

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 espaços de trabalho que a entidade de serviço possa acessar.

Localize o ID da sua conta.
Construa a URL do ponto de extremidade do token substituindo <account-id> a URL a seguir pelo ID da sua conta.
```
https://accounts.azuredatabricks.net/oidc/accounts/<my-account-id>/v1/token
```
Use curl para solicitar um token de acesso OAuth. Substituir:
- <token-endpoint-URL> com o URL acima.
- <client-id> com o ID do cliente da entidade de serviço (ID do aplicativo).
- <client-secret> com o segredo OAuth do diretor 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.
Copie o access_token valor da resposta.

Gerar um token de acesso no nível do espaço de trabalho

Use um token no nível do espaço de trabalho somente com APIs REST nesse espaço de trabalho.

Construa a URL do ponto de extremidade do token substituindo <databricks-instance> pelo <databricks-instance> nome da instância do espaço de trabalho do Azure Databricks, por exemplo adb-1234567890123456.7.azuredatabricks.net:
```
https://<databricks-instance>/oidc/v1/token
```

Use curl para solicitar um token de acesso OAuth. Substituir:

<token-endpoint-URL> com o URL acima.
<client-id> com o ID do cliente da entidade de serviço (ID do aplicativo).
<client-secret> com o segredo OAuth do diretor 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
}

Copie o access_token valor da resposta.

Nota

Para gerar um token para um ponto de extremidade de serviço, inclua o ID do ponto de extremidade e a ação em sua solicitação. Consulte Obter um token OAuth manualmente.

Chamar uma API REST do Azure Databricks

Use o token de acesso OAuth para chamar APIs REST no nível da conta ou no nível do espaço de trabalho . 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 de API REST no nível da conta

Este exemplo lista todos os espaços de trabalho de uma conta. Substituir:

<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 de API REST no nível do espaço de trabalho

Este exemplo lista todos os clusters disponíveis em um espaço de trabalho. Substituir:

<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 OAuth M2M

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

Verificações rápidas

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

Credenciais:DATABRICKS_CLIENT_ID está definido como o ID de aplicação do principal do serviço (ID do cliente), e DATABRICKS_CLIENT_SECRET está definido como o valor secreto OAuth, ambos sem espaços extra.
Anfitrião:DATABRICKS_HOST aponta para https://accounts.azuredatabricks.net para operações de conta ou para a URL de destino por espaço de trabalho, como por exemplo https://adb-1234567890123456.7.azuredatabricks.net para operações relacionadas ao espaço de trabalho. Não inclua /api.
Atribuição: O principal de serviço é atribuído ao espaço de trabalho de destino.
Permissões: O principal de 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 resolva conflitos.
Ferramentas: Use autenticação unificada e as versões atuais da CLI ou SDK.

401 Não autorizado

Causas prováveis e correções:

ID de cliente incorreto ou segredo: Recopiar DATABRICKS_CLIENT_ID e DATABRICKS_CLIENT_SECRET. Regenere o segredo se não tiver certeza.
Segredo expirado: Crie um novo segredo se o atual tiver expirado.
Emissor de token errado: Para M2M, utilize o endpoint do token OAuth do Databricks, e não o endpoint do token do seu IdP ou da nuvem.
Incompatibilidade de host: Se se autenticar para APIs de espaço de trabalho, DATABRICKS_HOST deverá ser a URL do espaço de trabalho que está a chamar.

403 Proibido

Causas prováveis e correções:

Permissões de recursos ausentes: Conceda ao principal de serviço CAN USE ou CAN MANAGE em clusters ou armazéns de SQL e as permissões necessárias no nível do objeto para notebooks, trabalhos ou objetos de dados.
Nenhuma atribuição de espaço de trabalho: Atribua o principal de serviço ao espaço de trabalho no console da conta.
Acesso à API de administração: Para APIs somente para administradores, atribua a entidade de serviço ao grupo de administradores do espaço de trabalho ou conceda permissões de administrador de conta.

Problemas de configuração

Os sintomas incluem tempo esgotado, "host não encontrado", "conta não encontrada" ou "espaço de trabalho não encontrado".

Fixes:

Regras do anfitrião: Use a URL do console da conta para APIs de conta. Use o URL do espaço de trabalho para APIs do espaço de trabalho. Não inclua o sufixo /api .
ID da conta: Fornecer DATABRICKS_ACCOUNT_ID apenas para operações no nível da conta. Use o UUID no console da conta.
Seleção do 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 o 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 nos pontos de extremidade do Databricks

Recursos adicionais

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

Feedback

Esta página foi útil?

Last updated on 2025-10-16

Partilhar via

Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth

Maneiras de autorizar uma entidade de serviço

Pré-requisitos

Etapa 1: Criar um segredo OAuth

Etapa 2: Usar a autorização OAuth

Ambiente

Perfil

CLI

Conectar

Código VS

Terraformação

Operações ao nível da conta

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

Python

Operações ao nível da conta

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

Java

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

Go

Operações ao nível da conta

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

Gerar manualmente tokens de acesso OAuth M2M

Gerar um token de acesso no nível da conta

Gerar um token de acesso no nível do espaço de trabalho

Chamar uma API REST do Azure Databricks

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

Exemplo de solicitação de API REST no nível do espaço de trabalho

Solucionar problemas de autenticação OAuth M2M

Verificações rápidas

401 Não autorizado

403 Proibido

Problemas de configuração

Connectivity

Recursos adicionais

Feedback

Recursos adicionais