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

Autorize o acesso do usuário ao Databricks com OAuth

Esta página explica como autorizar o acesso do usuário ao recurso Databricks ao usar o Databricks CLI ou APIs REST Databricks .

A Databricks utiliza OAuth 2.0 como protocolo preferencial para autorização e autenticação de usuários fora da interface do usuário. A autenticação unificada de clientes automatiza a geração de tokens e o refresh. Após o usuário fazer login e conceder consentimento, OAuth emite um token de acesso para CLI, SDK ou outra ferramenta a ser utilizada em nome do usuário. 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 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 o acesso a um recurso d Databricks​

Databricks Suporta duas formas de autorizar contas de usuário com OAuth:

  • Automática (recomendada): Use a autenticação unificada se estiver trabalhando com ferramentas e SDKs compatíveis, como o Databricks Terraform SDK. Essa abordagem lida com a geração de tokens e com o site refresh automaticamente.

  • 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 não oferecer suporte à autenticação unificada. Para obter detalhes, consulte Gerar manualmente OAuth U2M access tokens.

Autorização automática com autenticação unificada​

nota

Antes de configurar a autorização, verifique as permissões do ACL para o tipo de operações workspace que você planeja realizar e confirme se o seu account possui o nível de acesso necessário. Para obter detalhes, consulte Listas de controle de acesso.

Para executar a autorização OAuth com SDKs da Databricks e ferramentas que suportam autenticação unificada, integre o seguinte em seu código:

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

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,.

Gerar manualmente tokens de acesso OAuth U2M​

Esta seção é para usuários que trabalham com ferramentas ou serviços de terceiros que não são compatíveis com o padrão de autenticação unificadaDatabricks. Se precisar gerar manualmente, refresh, ou usar Databricks OAuth tokens para autenticação OAuth U2M, siga os passos desta seção.

Etapa 1: gerar um verificador de código e desafiar​

Para gerar manualmente um acesso U2M OAuth tokens , inicie criando um verificador de código e um desafio de código correspondente. Utilizará o desafio na Etapa 2 para obter um código de autorização e o verificador na Etapa 3 para trocar esse código por um token de acesso.

nota

Siga o padrão OAuth PKCE:

  • O verificador de código é uma sequência de caracteres aleatórios criptograficamente (43–128 caracteres) utilizando os caracteres A–Z, a–z, 0–9, -._~.
  • O desafio do código é um hash SHA256 codificado em URL Base64 do verificador.

Para obter mais informações, consulte Solicitação de autorização.

O script Python a seguir gera um verificador e um desafio. Embora seja possível utilizá-los várias vezes, a Databricks recomenda gerar um novo par sempre que você gerar tokens de acesso manualmente.

Python
import hashlib, base64, secrets, string

# Allowed characters for the code verifier, per PKCE spec
allowed_chars = string.ascii_letters + string.digits + "-._~"

# Generate a secure code verifier (43–128 characters)
code_verifier = ''.join(secrets.choice(allowed_chars) for _ in range(64))

# Create the SHA256 hash of the code verifier
sha256_hash = hashlib.sha256(code_verifier.encode()).digest()

# Base64-url-encode the hash and strip any trailing '=' padding
code_challenge = base64.urlsafe_b64encode(sha256_hash).decode().rstrip("=")

# Output values
print(f"code_verifier:  {code_verifier}")
print(f"code_challenge: {code_challenge}")

Etapa 2: gerar um código de autorização​

Para obter um token de acesso Databricks OAuth , é necessário primeiro gerar um código de autorização OAuth. Esse código expira imediatamente após o uso. É possível gerar o código no nível account ou workspace:

  • nível da conta: utilize para acessar tanto o nível accountquanto o nível workspace REST APIs em todos os espaços de trabalho aos quais o usuário tem acesso.
  • nível do espaço de trabalho: Utilize para chamar REST APIs dentro de um único workspace.
nota

Esses exemplos usam databricks-cli como ID do cliente. Caso não esteja utilizando uma ferramenta integrada do Databricks, como a CLI ou SDKs, é necessário habilitar um aplicativo OAuth personalizado e utilizar seu client_id em suas solicitações. Consulte Ativar ou desativar aplicativos OAuth de parceiros.

Gerar um código de autorização de nível account​

  1. Localize o seu ID do account.

  2. Em seu navegador, navegue até o URL com as seguintes substituições:

    • <account-id>: O seu ID do Databricks account
    • <redirect-url>: Um URI de redirecionamento local (por exemplo, http://localhost:8020)
    • <state>: Quaisquer sequências de texto simples para validar a resposta
    • <code-challenge>: O desafio do código da Etapa 1
    https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/authorize
    ?client_id=databricks-cli
    &redirect_uri=<redirect-url>
    &response_type=code
    &state=<state>
    &code_challenge=<code-challenge>
    &code_challenge_method=S256
    &scope=all-apis+offline_access

  3. Faça login quando solicitado para acessar o seu Databricks account.

  4. Após efetuar o login, o navegador o redirecionará para o seu URL. Se nada estiver escutando nesse host e porta (por exemplo, http://localhost:8020), a página mostra um erro de conexão, o que é esperado. Copie o código de autorização da barra de endereços. É a substring após code= e antes do próximo & nas strings de consulta.

    http://localhost:8020/?code=dcod...7fe6&state=<state>

    Verifique se o valor state corresponde ao que você forneceu originalmente. Se isso não acontecer, descarte o código.

  5. Continue a gerar tokens de acesso de nível account.

Gerar um código de autorização de nível workspace​

  1. Em seu navegador, navegue até o URL com as seguintes substituições:

    • <databricks-instance>: Seu <databricks-instance> com o Databricks workspace nome de instância, por exemplo dbc-a1b2345c-d6e7.cloud.databricks.com
    • <redirect-url>: Um redirecionamento local (por exemplo, http://localhost:8020)
    • <state>: Qualquer valor de texto sem formatação para validação de resposta
    • <code-challenge>: As sequências de desafio da Etapa 1
    https://<databricks-instance>/oidc/v1/authorize
    ?client_id=databricks-cli
    &redirect_uri=<redirect-url>
    &response_type=code
    &state=<state>
    &code_challenge=<code-challenge>
    &code_challenge_method=S256
    &scope=all-apis+offline_access

  2. Faça login quando solicitado para acessar o seu Databricks account.

  3. Após efetuar o login, o navegador o redirecionará para o seu URL. Se nada estiver escutando nesse host e porta (por exemplo, http://localhost:8020), a página mostra um erro de conexão, o que é esperado. Copie o código de autorização da barra de endereços. É a substring após code= e antes do próximo & nas strings de consulta.

    http://localhost:8020/?code=dcod...7fe6&state=<state>

    Verifique se o valor state corresponde ao que você forneceu originalmente. Se isso não acontecer, descarte o código.

  4. Continue a gerar tokens de acesso de nível “ workspace”.

Passo 3: Troque o código de autorização por um token de acesso​

Para trocar o código de autorização por um token de acesso Databricks OAuth , selecione o nível apropriado:

  • nível da conta: utilize para acessar tanto o nível accountquanto o nível workspace REST APIs em todos os espaços de trabalho aos quais o usuário tem acesso.
  • nível do espaço de trabalho: Utilize para chamar REST APIs dentro de um único workspace.

Gerar um account-level access tokens​

  1. Utilize curl para trocar o código de autorização de nível accountpor um token de acesso OAuth.

    Substitua o seguinte na solicitação:

    • <account-id>: O seu ID do Databricks account
    • <redirect-url>: O URL de redirecionamento da etapa anterior
    • <code-verifier>: O verificador que você gerou anteriormente
    • <authorization-code>: O código de autorização da etapa anterior
    Bash
    curl --request POST \
    https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token \
    --data "client_id=databricks-cli" \
    --data "grant_type=authorization_code" \
    --data "scope=all-apis offline_access" \
    --data "redirect_uri=<redirect-url>" \
    --data "code_verifier=<code-verifier>" \
    --data "code=<authorization-code>"

  2. Copie o valor access_token da resposta. Por exemplo:

    JSON
    {
      "access_token": "eyJr...Dkag",
      "refresh_token": "doau...f26e",
      "scope": "all-apis offline_access",
      "token_type": "Bearer",
      "expires_in": 3600
    }

    Os tokens são válidos por uma hora.

  3. Continue para a Etapa 4: Chamar uma API REST do Databricks.

Gerar um workspace-level access tokens​

  1. Utilize curl para trocar o código de autorização de nível workspacepor um token de acesso OAuth.

    Substitua o seguinte na solicitação:

    • <databricks-instance>: Seu <databricks-instance> com o Databricks workspace nome de instância, por exemplo dbc-a1b2345c-d6e7.cloud.databricks.com
    • <redirect-url>: O URL de redirecionamento da etapa anterior
    • <code-verifier>: O verificador que você gerou anteriormente
    • <authorization-code>: O código de autorização de nível " workspace" (Apenas para uso interno)
    Bash
    curl --request POST \
    https://<databricks-instance>/oidc/v1/token \
    --data "client_id=databricks-cli" \
    --data "grant_type=authorization_code" \
    --data "scope=all-apis offline_access" \
    --data "redirect_uri=<redirect-url>" \
    --data "code_verifier=<code-verifier>" \
    --data "code=<authorization-code>"

  2. Copie o valor access_token da resposta. Por exemplo:

    JSON
    {
      "access_token": "eyJr...Dkag",
      "refresh_token": "doau...f26e",
      "scope": "all-apis offline_access",
      "token_type": "Bearer",
      "expires_in": 3600
    }

    Os tokens são válidos por uma hora.

Etapa 4: chamar uma API REST da Databricks​

Utilize os tokens de acesso para chamar account-level ou workspace-level REST APIs, dependendo do seu escopo. Para acessar o account-level APIs, o usuário Databricks deve ser um administrador do account.

Exemplo account-level REST API request​

Este exemplo usa a autenticação curl junto com Bearer para obter uma lista de todos os espaços de trabalho associados a um account.

  • Substitua <oauth-access-token> pelos tokens de acesso account-level OAuth.
  • Substitua <account-id> pela ID de sua conta.
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 usa curl junto com a autenticação Bearer para listar todos os clusters disponíveis no site especificado workspace.

  • Substitua <oauth-access-token> pelos tokens de acesso account-level ou workspace-level OAuth.
  • Substitua <databricks-instance> pelo 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://<databricks-instance>/api/2.0/clusters/list"

Autentique-se como uma entidade de serviço usando OAuth U2M.​

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Utilize o fluxo OAuth U2M padrão para obter tokens em nome de uma entidade de serviço Databricks e acesse APIs Databricks usando a identidade da entidade de serviço em vez de sua própria account de usuário.

Você deve ter a função de Gerente de entidade de serviço na entidade de serviço na qual deseja se autenticar. Se você criou a entidade de serviço, você tem essa função automaticamente. Consulte Funções para gerenciar entidade de serviço.

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

    databricks auth login --host <workspace-url>

  2. Uma janela do navegador será aberta para autorização. Na dropdown, selecione a entidade de serviço para autenticação e, em seguida, autorize o aplicativo.

  3. Os tokens OAuth são emitidos com a identidade da entidade de serviço. A reivindicação sub nos tokens corresponde à entidade de serviço selecionada. Para view os tokens, execute:

    databricks auth token --host <workspace-url>

Este fluxo funciona com qualquer aplicação que suporte autenticação U2M padrão. Para obter os passos completos, consulte Autorização automática com autenticação unificada ou Gerar access tokens OAuth U2M manualmente.

Gerencie seu consentimento OAuth​

Durante o fluxo de autorização OAuth U2M, seu navegador pode exibir uma tela de consentimento solicitando que você aprove os escopos solicitados por um aplicativo. Você pode view ou revogar o consentimento já concedido.

Para view ou revogar o consentimento, você precisa do ID de integração do aplicativo. Se o aplicativo for um aplicativo Databricks, obtenha o ID do campo oauth2_app_client_id chamando a API REST Obter um aplicativo . Para configurar escopos para Databricks Apps, consulte Adicionar escopos a um aplicativo. Para outras aplicações, entre em contato com o administrador da sua account .

Para view os escopos aprovados para uma solicitação:

Bash
curl --request GET \
  --header "Authorization: Bearer $OAUTH_TOKEN" \
  "https://<databricks-instance>/api/2.0/oauth-app-integrations/<app-integration-id>/user-consent/me"

Para revogar o consentimento concedido a um aplicativo:

Bash
curl --request DELETE \
  --header "Authorization: Bearer $OAUTH_TOKEN" \
  "https://<databricks-instance>/api/2.0/oauth-app-integrations/<app-integration-id>/user-consent/me"
nota

Revogar o consentimento não invalida os tokens existentes. O aplicativo ainda pode usar tokens refresh existentes para obter novos access tokens até que esses tokens expirem. Após o vencimento, o aplicativo não pode iniciar um novo fluxo de autorização para obter novos tokens.

Substitua o seguinte:

  • <databricks-instance>: Seu <databricks-instance> com o Databricks workspace nome de instância, por exemplo dbc-a1b2345c-d6e7.cloud.databricks.com
  • <app-integration-id>ID de integração do aplicativo
Nesta página