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

Autorizar o acesso do Databricks service principal ao Databricks com OAuth

Autorize o acesso de um service principal do Databricks aos recursos do Databricks com OAuth. Use autenticação máquina para máquina (M2M) para processos não atendidos, como comandos da CLI automatizados ou chamadas de API REST de scripts ou aplicativos. Esses processos podem usar autenticação unificada ou solicitar access tokens manualmente. Use OAuth on-behalf-of (OBO) para agir como um service principal do Databricks interativamente, sem um segredo OAuth.

O Databricks usa OAuth 2.0 como o protocolo preferencial para autorização e autenticação de service principal do Databricks fora da interface do usuário. A autenticação unificada de cliente automatiza a geração e o refresh de tokens. Quando um service principal do Databricks entra e recebe consentimento, o OAuth emite um access token para a CLI, SDK ou outra ferramenta usar em seu nome. Cada access token é válido por uma hora, após a qual um novo token é solicitado automaticamente.

Nesta página, autorização refere-se ao uso de OAuth para conceder a um service principal do Databricks acesso a recursos do Databricks, enquanto autenticação refere-se à 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​

O Databricks é compatível com as seguintes maneiras de autorizar uma Service Principal:

  • Autenticação OAuth máquina a máquina (M2M) com um segredo do cliente: use isto para cargas de trabalho não supervisionadas. Consulte Autorizar com OAuth M2M usando um ID de cliente e um segredo. Você pode autorizar de uma das seguintes maneiras:

    • 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: Troque o ID do cliente e o segredo do Service Principal por um access token usando a concessão de credenciais do cliente do OAuth. Use este método se sua ferramenta ou API não for compatível com a autenticação unificada. Talvez seja necessário criar seu próprio mecanismo de refresh de tokens para seu aplicativo. Para obter detalhes, consulte Gere manualmente access tokens OAuth M2M.

  • OAuth em nome de (OBO): Aja como um Service Principal que você gerencia por meio do fluxo OAuth padrão de usuário para máquina (U2M), sem um segredo OAuth. Use isto para acesso interativo quando uma pessoa conduzir a sessão. Consulte Autenticar-se como um Service Principal usando OAuth OBO.

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?

Autentique-se como um Service Principal usando OAuth OBO​

info

Beta

Este recurso está em Beta. Para usá-lo, um administrador do workspace deve ativar U2M para Service Principal na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

O OAuth on-behalf-of (OBO) permite que um cliente OAuth, como a CLI do Databricks, atue com uma identidade delegada. Com o OBO, quando você autoriza um cliente por meio do fluxo OAuth padrão de usuário para máquina (U2M), pode delegar uma Service Principal que você gerencia em vez da sua própria identidade de usuário.

Requisitos​

  • Você tem a função de gerente de Service Principal no Service Principal como o qual deseja se autenticar. Se você criou o Service Principal, terá essa função automaticamente. Consulte Funções para gerenciar Service Principal.
  • Um administrador do workspace ativou U2M para Service Principal na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

Autentique-se como a Service Principal​

  1. Inicie o fluxo U2M padrão. O exemplo a seguir usa a CLI do Databricks:

    databricks auth login --host <workspace-url>

  2. Uma janela do navegador é aberta para autorização. No dropdown, selecione o Service Principal a ser usado para autenticação e, em seguida, autorize o aplicativo.

  3. O token OAuth é emitido com a identidade da Service Principal. A claim sub no token corresponde à Service Principal selecionada. Para view o token, execução:

    databricks auth token --host <workspace-url>

Este fluxo funciona com qualquer aplicativo compatível com a autenticação U2M padrão. Para consultar os passos completos, consulte Autorização automática com autenticação unificada ou Gerar manualmente access tokens OAuth U2M.

Autorize com OAuth M2M usando uma ID do cliente e um segredo do cliente​

Para cargas de trabalho não assistidas, como automação, scripts e CI/CD, crie um segredo OAuth para o Service Principal e troque-o por access tokens de curta duração usando o fluxo de credenciais do cliente (M2M).

Etapa 1: Criar um segredo OAuth​

Para autorizar o acesso aos seus recursos do Databricks com OAuth, você deve criar um segredo OAuth. O segredo é usado para gerar access tokens OAuth para autenticação. Uma Service Principal pode ter até cinco segredos do OAuth, e cada segredo pode ser válido por até dois anos. O Databricks exclui automaticamente um segredo OAuth após 90 dias sem uso.

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. Em Scopes , selecione os escopos de API que o segredo pode usar. Para restringir o segredo, pesquise e selecione um ou mais escopos, como sql ou jobs. Para permitir que o segredo acesse todas as APIs para as quais o Service Principal está autorizado, selecione all APIs (não recomendado). Consulte Segredos OAuth com escopo.
  9. Clique em Gerar .
  10. 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.

Segredos OAuth com escopo​

Por default, um segredo OAuth pode acessar todas as APIs para as quais o service principal está autorizado (all-apis). Um segredo com escopo restringe o acesso a um conjunto específico de escopos de API, como sql, jobs ou unity-catalog. Um access token OAuth gerado a partir de um segredo com escopo não pode exceder os escopos do segredo, o que limita o impacto caso o segredo seja vazado ou utilizado indevidamente. A Databricks recomenda vincular cada segredo apenas aos escopos de que sua integração necessita.

Um segredo criado sem escopos, incluindo todos os segredos existentes, mantém o acesso all-apis e se comporta como antes.

Os escopos são definidos quando você gera o segredo e não podem ser alterados posteriormente. Para usar escopos diferentes, gere um novo segredo. Na tabela Secrets , clique em Clone em um segredo existente para criar um novo com os mesmos escopos e tempo de vida.

atenção

Um segredo com o escopo authentication pode criar novos tokens com qualquer escopo. Vincule este escopo apenas a segredos que gerenciam outras credenciais.

Para obter a lista completa de escopos e as operações de API que cada um cobre, consulte escopos de API.

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.gcp.databricks.com para account operações ou o workspace URL de destino, por exemplo,https://1234567890123456.7.gcp.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.gcp.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://1234567890123456.7.gcp.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.gcp.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 1234567890123456.7.gcp.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​

Um Service Principal do Databricks pode assumir uma função quando solicita um access token de nível de workspace. Quando um Service Principal do Databricks assume uma função, as permissões da função substituem as permissões do próprio Service Principal do Databricks. No Databricks, uma função é implementada como um grupo, e o Service Principal do Databricks deve ter a permissão Assume 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á.
  • Tanto o service principal do Databricks quanto a função devem ser atribuídos ao workspace de destino. A assunção de função não substitui a atribuição do workspace do service principal do Databricks. Consulte Atribuir um service principal a um workspace e Atribuir um grupo a um workspace.
  • O service principal do Databricks deve ter a permissão Assume no grupo. Se não tiver, a solicitação falha. Para conceder a permissão Assume, consulte Gerenciar permissões em um grupo.

Após o token ser criado, use-o para chamar APIs do workspace sem precisar especificar assume_group novamente.

Para obter um exemplo completo com queries SQL permitidas e negadas e verificação de auditoria, consulte tutorial: limitar o acesso de um agente de AI com RBAC. Para outros métodos de autenticação, consulte Alternar funções de RBAC.

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.gcp.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 1234567890123456.7.gcp.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 está definido como o ID do aplicativo (ID do cliente) do Service Principal do Databricks e DATABRICKS_CLIENT_SECRET está definido com o valor secreto OAuth, ambos sem espaços extras.
  • Host: DATABRICKS_HOST aponta https://accounts.gcp.databricks.com para para account operações ou para o workspace URL de destino, por exemplo,https://1234567890123456.7.gcp.databricks.com para workspace operações. Não inclua /api.
  • Atribuição: Para tokens de workspace, o Service Principal do Databricks é atribuído ao workspace de destino. Ao assumir uma função, a função também deve ser atribuída a esse workspace. Verifique se o Service Principal do Databricks tem a permissão Assume e inclua assume_group na solicitação de token. Consulte Assumir uma função.
  • Permissões: A identidade usada pelo token, seja o service principal do Databricks ou a função assumida, 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 à identidade usada pelo token as permissões necessárias, como CAN USE ou CAN MANAGE em clusters ou SQL Warehouse, e permissões de nível de objeto em notebooks, jobs ou objetos de dados. Para um token com escopo de função, conceda essas permissões à função.
  • Sem atribuição de workspace: Atribua o Databricks service principal ao workspace. Para um tokens com escopo de função, também atribua a função ao workspace, conceda ao Databricks Service Principal a permissão Assume e inclua assume_group ao criar o tokens. Consulte Assumir uma função.
  • Acesso à API de administração: Para APIs de administração de workspace, a identidade usada pelo token deve ser um administrador de workspace. Para APIs de administrador account, o Databricks service principal deve ser um administrador account. A assunção de função é suportada apenas para tokens de nível de workspace.

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