Pular para o conteúdo principal
Última atualização em

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

Esta página explica como autorizar o acesso ao recurso Databricks a partir de processos autônomos, como comandos CLI automatizados ou chamadas API REST feitas a partir de scripts ou aplicativos.

A 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 de clientes automatiza a geração de tokens e o refresh. Quando uma entidade de serviço se inscreve e recebe consentimento, o site OAuth emite tokens de acesso para o site CLI, SDK, ou outra ferramenta para usar em seu nome. Cada token de acesso é válido por uma hora, após o qual um novo token é solicitado automaticamente.

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

Para obter mais detalhes de alto nível, consulte Autorizar acesso ao recurso Databricks.

Formas de autorizar uma entidade de serviço​

A Databricks oferece suporte a duas maneiras de autorizar uma entidade de serviço:

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

  • Manual: Gere um verificador de código e um desafio e, em seguida, troque-os por tokens OAuth. Use esse método se sua ferramenta ou API não for compatível com a autenticação unificada. Talvez o senhor precise criar seu próprio mecanismo de tokens refresh para seu aplicativo. Para obter detalhes, consulte Gerar manualmente OAuth M2M access tokens.

Pré-requisitos​

Antes de configurar o OAuth, execute as seguintes etapas:

  1. Crie uma entidade de serviço Databricks. Consulte Adicionar entidade de serviço ao seu account.
  2. Acesse o site de configuração tab para a entidade de serviço e selecione os direitos que ela deve ter para este workspace.
  3. Acesse o site Permissions (Permissões ) tab e conceda acesso a todos os usuários, entidades de serviço e grupos do Databricks que o senhor deseja gerenciar e usar essa entidade de serviço. Veja Quem pode gerenciar e usar a entidade de serviço?

Etapa 1: Criar um segredo OAuth​

Para autorizar o acesso ao seu recurso Databricks com OAuth, o senhor 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 contas e os administradores de workspaces podem criar um segredo do OAuth para uma entidade de serviço.

  1. Clique no seu 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 a vida útil do segredo em dias (máximo de 730 dias).
  8. Clique em Gerar .
  9. Copie o segredo e o ID do cliente exibidos 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 no console account. Em User management (Gerenciamento de usuários ) tab, selecione a entidade de serviço e, em seguida, vá para Credentials (Credenciais) & secrets (Segredos ) tab.

nota

Para permitir que a entidade de serviço use o armazenamento em cluster ou SQL, o senhor deve conceder à entidade de serviço acesso a eles. Consulte computar permissões ou gerenciar SQL warehouse a.

Etapa 2: Use a autorização OAuth​

Para usar a autorização OAuth com a ferramenta de autenticação unificada, o senhor deve definir os seguintes campos associados variável de ambiente, .databrickscfg, Terraform ou Config:

  • O Databricks host, especificado como https://accounts.cloud.databricks.com para account operações ou o workspace URL de destino, por exemplo,https://dbc-a1b2345c-d6e7.cloud.databricks.com para workspace operações.
  • O ID da conta do Databricks, para operações da conta do Databricks.
  • O ID do cliente da entidade de serviço.
  • O segredo da entidade de serviço.

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

Para usar a variável de ambiente para um tipo específico de autenticação Databricks com uma ferramenta ou SDK, consulte Autorizar acesso ao recurso Databricks ou a documentação da ferramenta ou do SDK. Veja também variável de ambiente e campos para autenticação unificada e a prioridade do método de autenticação.

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

  • DATABRICKS_HOST, defina para o valor da URL do console da sua conta Databricks, https://accounts.cloud.databricks.com.
  • DATABRICKS_ACCOUNT_ID
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

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

  • DATABRICKS_HOST, definido como o valor do Databricks workspace URL, por https://dbc-a1b2345c-d6e7.cloud.databricks.com exemplo,.
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

Gerar manualmente tokens de acesso OAuth M2M​

Esta seção é para ferramentas ou serviços que não são compatíveis com a autenticação unificadaDatabricks. Se o senhor precisar gerar manualmente, refresh, ou usar Databricks OAuth tokens para autenticação M2M, siga estes passos.

Para gerar tokens 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. Após a expiração, solicite novos tokens. O senhor pode gerar tokens no nível account ou workspace:

Gerar um account-level access tokens​

Use um token de nível accountpara chamar REST APIs para o account e qualquer espaço de trabalho que a entidade de serviço possa acessar.

  1. Localize o seu ID do account.

  2. Construa o URL de tokens endpoint substituindo <account-id> no URL a seguir pelo seu ID account.

    https://accounts.cloud.databricks.com/oidc/accounts/<my-account-id>/v1/token

  3. Use curl para solicitar tokens de acesso OAuth. Substitua:

    • <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 da entidade de serviço.
    Bash
    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:

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

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

  4. Copie o valor access_token da resposta.

Gerar um workspace-level access tokens​

Use tokens de nível workspacesomente com REST APIs em que workspace.

  1. Construa o endpoint URL dos tokens substituindo <databricks-instance> pelo seu <databricks-instance> pelo Databricks workspace nome da instância, por dbc-a1b2345c-d6e7.cloud.databricks.com exemplo,:

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

  2. Use curl para solicitar tokens de acesso OAuth. Substitua:

    • <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 da entidade de serviço.
    Bash
    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:

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

  3. Copie o valor access_token da resposta.

nota

Para gerar tokens para um serviço endpoint, inclua a ID endpoint e a ação em sua solicitação. Consulte Obter um OAuth tokens manualmente.

Assumir uma função​

info

Visualização

Este recurso está em Pré-visualização Pública.

Um Service Principal pode assumir uma função quando solicita um access token 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 Databricks, uma função é implementada como um grupo, e o Service Principal deve ter permissão de Assumir nesse grupo. Para obter mais informações, consulte role-based access control (RBAC).

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

Bash
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 apoio da função.

Assumir uma função tem os seguintes requisitos e limitações:

  • Suportado apenas para tokens em nível de workspace. Se o senhor incluir assume_group em uma solicitação de token em nível de conta, a solicitação falhará.
  • O Service Principal deve ter permissão de **Assumir** no grupo. Caso contrário, a solicitação falha. Para conceder Assumir, consulte Gerenciar permissões em um grupo.

Para obter mais informações sobre a alternância de funções, consulte Alternar funções.

Chamar uma API REST da Databricks​

Use os tokens de acesso OAuth para chamar account-level ou workspace-level REST APIs. Para chamar o account-level APIs, a entidade de serviço deve ser um administrador do account.

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

Exemplo account-level REST API request​

Este exemplo lista todos os espaços de trabalho de um account. Substitua:

  • <oauth-access-token> com os tokens de acesso OAuth da entidade de serviço.
  • <account-id> com sua ID account.
Bash
export OAUTH_TOKEN=<oauth-access-token>

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

Exemplo workspace-level REST API request​

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

  • <oauth-access-token> com os tokens de acesso OAuth da entidade de serviço.
  • <databricks-instance> com o Databricks workspace nome da instância, por dbc-a1b2345c-d6e7.cloud.databricks.com exemplo,.
Bash
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 estes passos 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 comuns de configuração que causam falhas na autenticação do OAuth M2M:

  • Credenciais: DATABRICKS_CLIENT_ID é definido como o ID do aplicativo da entidade de serviço (ID do cliente) e DATABRICKS_CLIENT_SECRET é definido como o valor secreto do OAuth, ambos sem espaços extras.
  • Host: DATABRICKS_HOST aponta https://accounts.cloud.databricks.com para para account operações ou para o workspace URL de destino, por exemplo,https://dbc-a1b2345c-d6e7.cloud.databricks.com para workspace operações. Não inclua /api.
  • Atribuição: A entidade de serviço é atribuída ao alvo workspace.
  • Permissões: A entidade de serviço tem as permissões necessárias no recurso de destino.
  • Conflitos: Nenhuma variável conflitante definida, como DATABRICKS_TOKEN, DATABRICKS_USERNAME. execução env | grep DATABRICKS e conflitos não definidos.
  • Ferramentas: Use a autenticação unificada e as versões atuais da CLI ou do SDK.

401 Não autorizado​

Causas e soluções prováveis:

  • ID de cliente ou segredo incorretos: copie novamente 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 tokens errado: Para M2M, use os tokens Databricks OAuth endpoint, não seu IdP ou cloud tokens endpoint.
  • Incompatibilidade de host: Se o senhor se autenticar em workspace APIs, DATABRICKS_HOST deve ser o URL workspace que o senhor chama.

403 Proibido​

Causas e soluções prováveis:

  • Permissões de recurso ausentes: Conceda à entidade de serviço CAN USE ou CAN MANAGE no depósito clusters ou SQL e as permissões necessárias em nível de objeto para Notebook, Job ou objetos de dados.
  • Não há atribuição de workspace: Atribua a entidade de serviço ao workspace no console account.
  • Acesso de administrador API: Para acesso somente de administrador APIs, atribua a entidade de serviço ao grupo de administradores workspace ou conceda permissões de administrador account.

Problemas de configuração​

Os sintomas incluem timeouts, "host not found" (host não encontrado), "account not found" ( não encontrado) ou "workspace not found" ( não encontrado).

Correções:

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

Conectividade​

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

  • DNS: nslookup <your-host> (deve retornar endereços IP para o hostname)
  • 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 o endpoint Databricks

Recurso adicional​

Nesta página