Autorizar o acesso não supervisionado aos recursos do Azure Databricks com um principal de serviço usando OAuth

Este tópico fornece etapas e detalhes para autorizar o acesso aos recursos do Azure Databricks ao automatizar comandos da CLI do Azure Databricks ou chamar APIs REST do Azure Databricks de código que serão executados a partir de um processo não supervisionado.

O Azure Databricks usa o OAuth como o protocolo preferencial para autorização e autenticação do usuário ao interagir com recursos do Azure Databricks fora da interface do usuário. O Azure Databricks também fornece a ferramenta de autenticação de cliente unificada para automatizar a atualização dos tokens de acesso gerados como parte do método de autenticação do OAuth. Isso se aplica a entidades de serviço, bem como contas de usuário, mas você deve configurar uma entidade de serviço com as permissões e privilégios apropriados para os recursos do Azure Databricks que ele deve acessar como parte de suas operações.

Para obter mais detalhes de alto nível, consulte Autorizando o acesso aos recursos do Azure Databricks.

Quais são as minhas opções de autorização e autenticação ao usar um principal de serviço do Azure Databricks?

Neste tópico, a autorização refere-se ao protocolo (OAuth) usado para negociar o acesso a recursos específicos do Azure Databricks por meio da delegação. Autenticação refere-se ao mecanismo pelo qual as credenciais são representadas, transmitidas e verificadas—que, nesse caso, são tokens de acesso.

O Azure Databricks usa autorização baseada em OAuth 2.0 para habilitar o acesso aos recursos de conta e espaço de trabalho do Azure Databricks a partir da linha de comando ou código em nome de uma entidade de serviço com permissões para acessar esses recursos. Depois que uma entidade de serviço do Azure Databricks é configurada e suas credenciais são verificadas quando executa um comando da CLI ou chama uma API REST, um token OAuth é fornecido à ferramenta participante ou ao SDK para executar a autenticação baseada em token em nome da entidade de serviço a partir desse momento. O token de acesso OAuth tem um tempo de vida útil de uma hora, seguindo o qual a ferramenta ou o SDK envolvido fará uma tentativa automática em segundo plano de obter um novo token que também é válido por uma hora.

O Azure Databricks oferece suporte a duas maneiras de autorizar o acesso de uma entidade de serviço com OAuth:

  • Principalmente automaticamente, usando o suporte à autenticação de cliente unificada do Databricks. Use essa abordagem simplificada se você estiver usando SDKs específicos do Azure Databricks (como o SDK do Databricks Terraform) e ferramentas. As ferramentas e SDKs suportados estão listados em Autenticação unificada de cliente Databricks. Essa abordagem é adequada para automação ou outros cenários de processo autônomos.
  • Manualmente, gerando diretamente um par de verificador/desafio de código OAuth e um código de autorização e usando-os para criar o token OAuth inicial que você fornecerá em sua configuração. Use essa abordagem quando você não estiver usando uma API compatível com a autenticação de cliente unificada do Databricks. Nesse caso, talvez seja necessário desenvolver seu próprio mecanismo para lidar com a atualização de tokens de acesso específicos para a ferramenta de terceiros ou a API que você está usando. Para obter mais detalhes, veja: Gerar e usar manualmente tokens de acesso para autenticação principal do serviço OAuth.

Antes de começar, você deve configurar um principal de serviço do Azure Databricks e atribuir as permissões apropriadas para que a entidade acesse os recursos que devem ser usados quando solicitados pelo seu código de automação ou comandos.

Pré-requisito: criar um principal de serviço

Administradores de contas e administradores de espaços de trabalho podem criar entidades de serviço. Essa etapa descreve a criação de uma entidade de serviço em um espaço de trabalho do Azure Databricks. Para obter detalhes sobre o próprio console da conta do Azure Databricks, veja Gerenciar entidades de serviço em sua conta.

Você também pode criar uma entidade de serviço gerenciada da ID do Microsoft Entra e adicioná-la ao Azure Databricks. Para obter mais informações, consulte Databricks e entidades de serviço do Microsoft Entra ID.

  1. Como administrador do workspace, faça logon no workspace do Azure Databricks.
  2. Clique no seu nome de usuário na barra superior do workspace do Azure Databricks e selecione Configurações.
  3. Clique na guia Identidade e acesso.
  4. Ao lado de Entidades de serviço, clique em Gerenciar.
  5. Clique em Adicionar entidade de serviço.
  6. Clique na seta suspensa na caixa de pesquisa e clique em Adicionar novo.
  7. Em Gerenciamento, escolha Databricks gerenciado.
  8. Insira um nome para a entidade de serviço.
  9. Clique em Adicionar.

A entidade de serviço é adicionada ao workspace e à conta do Azure Databricks.

Etapa 1: atribuir permissões ao seu principal de serviço

  1. Clique no nome da entidade de serviço para abrir a página de detalhes.
  2. Na guia Configurações, marque a caixa ao lado de cada direito que você deseja que sua entidade de serviço tenha para este workspace e clique em Atualizar.
  3. Na guia Permissões, permita acesso a qualquer usuário do Azure Databricks, entidades de serviço e grupos que você deseja gerenciar e use essa entidade de serviço. Confira Gerenciar funções em uma entidade de serviço.

Etapa 2: Criar um segredo OAuth para um principal de serviço

Antes de poder usar o OAuth para autorizar o acesso aos recursos do Azure Databricks, primeiro você deve criar um segredo OAuth, que pode ser usado para gerar tokens de acesso OAuth para autenticação. Uma entidade de serviço pode ter até cinco segredos OAuth. Os administradores de conta e os administradores do workspace podem criar um segredo OAuth para uma entidade de serviço.

  1. Na página de detalhes da entidade de serviço, clique na guia Segredos .

  2. Em Segredos OAuth, clique em Gerar segredo.

    Gerar segredo OAuth do workspace

  3. Copie o Segredo e o ID do Cliente exibidos e clique em Concluído.

O segredo só será revelado uma vez durante a criação. O ID do cliente é igual ao ID do aplicativo da entidade de serviço.

Os administradores de conta também podem gerar um segredo OAuth na página de detalhes da entidade de serviço no console da conta.

  1. Como administrador de conta, faça logon no console da conta.

  2. Clique em ícone Gerenciamento de usuários do console da contaGerenciamento de Usuários.

  3. Na guia Entidades de serviço, selecione sua entidade de serviço.

  4. Em Segredos OAuth, clique em Gerar segredo.

    Gerar segredo OAuth do workspace

  5. Copie o Segredo e o ID do Cliente exibidos e clique em Concluído.

Observação

Para permitir que a entidade de serviço use clusters ou SQL warehouses, você deve conceder acesso a eles à entidade de serviço. Consulte Permissões de computação ou Gerenciar um SQL warehouse.

Etapa 3: Usar a autorização do OAuth

Para usar a autorização OAuth com a ferramenta de autenticação de cliente unificada, você deve definir as seguintes variáveis de ambiente associadas, campos .databrickscfg, campos terraform ou campos 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 exemplohttps://adb-1234567890123456.7.azuredatabricks.net para operações de workspace.
  • A ID da conta do Azure Databricks para 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 principal do serviço OAuth, integre o seguinte ao 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 Autorizando o acesso aos recursos do Azure Databricks ou a documentação da ferramenta ou do SDK. Consulte também Variáveis de ambiente e campos para autenticação unificada do cliente e Métodos padrão para autenticação unificada do cliente.

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

  • DATABRICKS_HOST, definido como a URL do console da conta do Azure Databricks, https://accounts.azuredatabricks.net.
  • DATABRICKS_ACCOUNT_ID
  • DATABRICKS_CLIENT_ID
  • DATABRICKS_CLIENT_SECRET

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

  • DATABRICKS_HOST, defina a 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 para autorizar o acesso aos recursos do Azure Databricks ou a documentação da ferramenta ou do SDK. Consulte também Variáveis de ambiente e campos para autenticação unificada do cliente e Métodos padrão para autenticação unificada do cliente.

Para 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 workspace, defina os seguintes valores em 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>

CLI

Na CLI do Databricks, siga um destes procedimentos:

  • Defina as variáveis de ambiente, conforme especificado na seção “Ambiente” deste artigo.
  • Defina os valores no arquivo .databrickscfg, conforme especificado na seção “Perfil” deste artigo.

As variáveis de ambiente sempre têm precedência sobre os valores do arquivo .databrickscfg.

Consulte também Autenticação máquina a máquina (M2M) do OAuth.

Conectar

Observação

A autenticação principal do serviço OAuth é compatível com as seguintes versões do Databricks Connect:

  • Para Python, Databricks Connect para o Databricks Runtime 14.0 e superior.
  • No caso do Scala, o Databricks Connect para Databricks Runtime 13.3 LTS e superior. O SDK do Databricks para Java incluído no Databricks Connect para Databricks Runtime 13.3 LTS e posterior deve ser atualizado para o Databricks SDK para Java 0.17.0 ou superior.

No Databricks Connect, siga um destes procedimentos:

  • Defina os valores em seu arquivo .databrickscfg para operações no nível do workspace do Azure Databricks, conforme especificado na seção "Perfil" deste artigo. Defina também a variável de ambiente cluster_id no seu perfil como a URL por workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.
  • Defina as variáveis de ambiente para operações no nível do workspace do Azure Databricks, conforme especificado na seção "Ambiente" deste artigo. Defina também a variável de ambiente DATABRICKS_CLUSTER_ID como a URL por workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

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

Para inicializar o cliente do Databricks Connect com essas variáveis de ambiente ou valores em seu .databrickscfg arquivo, consulte Configuração de computação para o Databricks Connect.

Código VS

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

  1. Defina os valores em seu arquivo .databrickscfg para operações no nível do workspace do Azure Databricks, conforme especificado na seção "Perfil" deste artigo.
  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 da URL.

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

Terraform

Para operações no nível da conta, para autenticação padrão:

provider "databricks" {
  alias = "accounts"
}

Para configuração direta (substitua os espaços reservados retrieve por sua própria implantação para recuperar os valores do console ou de algum outro repositório de configurações, como HashiCorp Vault. Confira também Provedor de Cofres). Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net:

provider "databricks" {
  alias         = "accounts"
  host          = <retrieve-account-console-url>
  account_id    = <retrieve-account-id>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

Para operações no nível do workspace, para autenticação padrão:

provider "databricks" {
  alias = "workspace"
}

Para configuração direta (substitua os espaços reservados retrieve por sua própria implantação para recuperar os valores do console ou de algum outro repositório de configurações, como HashiCorp Vault. Confira também Provedor de Cofres). Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net:

provider "databricks" {
  alias         = "workspace"
  host          = <retrieve-workspace-url>
  client_id     = <retrieve-client-id>
  client_secret = <retrieve-client-secret>
}

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

Python

Para operações no nível da conta, use o seguinte para autenticação padrão:

from databricks.sdk import AccountClient

a = AccountClient()
# ...

Para configuração direta, use o seguinte, substituindo os espaços reservados retrieve pela sua própria implementação para recuperar os valores do console ou de outro armazenamento de configuração, como o Azure KeyVault. Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net:

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()
)
# ...

Para operações no nível de espaço de trabalho, especificamente autenticação padrão:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para a configuração direta, substitua os espaços reservados retrieve por sua própria implantação para recuperar os valores do console ou de outro repositório de configurações, como o Azure KeyVault. Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host          = retrieve_workspace_url(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

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

Observação

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

Java

Para operações em nível de espaço de trabalho usando autenticação padrão:

import com.databricks.sdk.WorkspaceClient;
// ...
WorkspaceClient w = new WorkspaceClient();
// ...

Para a configuração direta (substitua os espaços reservados retrieve por sua própria implantação para recuperar os valores do console ou de outro repositório de configurações, como o Azure KeyVault). Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net:

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);
// ...

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

Go

Para operações em nível de conta usando autenticação padrão:

import (
"github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient())
// ...

Para a configuração direta (substitua os espaços reservados retrieve por sua própria implantação para recuperar os valores do console ou de outro repositório de configurações, como o Azure KeyVault). Nesse caso, a URL do console da conta do Azure Databricks é https://accounts.azuredatabricks.net:

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
w := databricks.Must(databricks.NewWorkspaceClient(&databricks.Config{
    Host:         retrieveAccountConsoleUrl(),
    AccountId:    retrieveAccountId(),
    ClientId:     retrieveClientId(),
    ClientSecret: retrieveClientSecret(),
}))
// ...

Para operações em nível de espaço de trabalho usando autenticação padrão:

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient())
// ...

Para a configuração direta (substitua os espaços reservados retrieve por sua própria implantação para recuperar os valores do console ou de outro repositório de configurações, como o Azure KeyVault). Nesse caso, o host é a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net:

import (
  "github.com/databricks/databricks-sdk-go"
)
// ...
a := databricks.Must(databricks.NewAccountClient(&databricks.Config{
  Host:         retrieveWorkspaceUrl(),
  ClientId:     retrieveClientId(),
  ClientSecret: retrieveClientSecret(),
}))
// ...

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, consulte Autenticar o SDK do Databricks para o Go com sua conta ou espaço de trabalho do Azure Databricks.

Gerar e usar manualmente tokens de acesso para autenticação principal do serviço OAuth

As ferramentas e SDKs do Azure Databricks que implementam o padrão de autenticação unificada do cliente Databricks gerarão, atualizarão e usarão automaticamente os tokens de acesso OAuth do Azure Databricks em seu nome, conforme necessário, para a autenticação da entidade de serviço OAuth.

O Databricks recomenda usar a autenticação unificada do cliente, no entanto, se você precisar gerar, atualizar ou usar manualmente os tokens de acesso OAuth do Azure Databricks, siga as instruções nesta seção.

Use a ID do cliente da entidade de serviço e o segredo do OAuth para solicitar um token de acesso OAuth para autenticar as APIs REST no nível da conta e as APIs REST no nível do workspace. O token de acesso expirará em uma hora. Você deve solicitar um novo token de acesso OAuth após a expiração. O escopo do token de acesso OAuth depende do nível a partir do qual você cria o token. Você pode criar um token no nível da conta ou no nível do workspace, da seguinte maneira:

Gerar manualmente um token de acesso no nível da conta

Um token de acesso OAuth criado no nível da conta pode ser usado em APIs REST do Databricks na conta e em qualquer workspace ao qual a entidade de serviço tenha acesso.

  1. Como administrador de conta, faça logon no console da conta.

  2. Clique na seta para baixo ao lado do seu nome de usuário no canto superior direito.

  3. Copie sua ID da conta.

  4. Construa a URL do ponto de extremidade do token substituindo <my-account-id> na URL a seguir pela ID da conta que você copiou.

    https://accounts.azuredatabricks.net/oidc/accounts/<my-account-id>/v1/token
    
  5. Use um cliente para curl solicitar um token de acesso OAuth com a URL do ponto de extremidade do token, a ID do cliente da entidade de serviço (também conhecida como ID do aplicativo) e o segredo OAuth da entidade de serviço que você criou. O all-apis escopo solicita um token de acesso OAuth que pode ser usado para acessar todas as APIs REST do Databricks às quais a entidade de serviço recebeu acesso.

    • Substitua <token-endpoint-URL> pela URL do ponto de extremidade do token anterior.
    • Substitua <client-id> pela ID de cliente da entidade de serviço, também é conhecida como ID de aplicativo.
    • Substitua <client-secret> pelo segredo OAuth da entidade de serviço que você criou.
    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 da resposta.

Gerar manualmente um token de acesso no nível do workspace

Um token de acesso OAuth criado no nível do workspace só pode acessar APIs REST nesse workspace, mesmo que a entidade de serviço seja um administrador de conta ou seja membro de outros workspaces.

  1. Construa a URL do ponto de extremidade do token substituindo https://<databricks-instance> pela URL do espaço de trabalho da sua implantação do Azure Databricks:

    https://<databricks-instance>/oidc/v1/token
    
  2. Use um cliente para curl solicitar um token de acesso OAuth com a URL do ponto de extremidade do token, a ID do cliente da entidade de serviço (também conhecida como ID do aplicativo) e o segredo OAuth da entidade de serviço que você criou. O all-apis escopo solicita um token de acesso OAuth que pode ser usado para acessar todas as APIs REST do Databricks às quais a entidade de serviço recebeu acesso no workspace do qual você está solicitando o token.

    • Substitua <token-endpoint-URL> pela URL do ponto de extremidade do token anterior.
    • Substitua <client-id> pela ID de cliente da entidade de serviço, também é conhecida como ID de aplicativo.
    • Substitua <client-secret> pelo segredo OAuth da entidade de serviço que você criou.
    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 da resposta.

Chamar uma API REST do Databricks

Você pode usar o token de acesso OAuth para autenticar-se nas APIs REST de nível de conta e de nível de espaço de trabalho no Azure Databricks. O principal do serviço deve ter privilégios de administrador de conta para chamar APIs REST em nível de conta.

Inclua o token de acesso no cabeçalho de autorização usando Bearer autenticação. Você pode usar essa abordagem com curl ou qualquer cliente que você criar.

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

Esse exemplo usa a autenticação Bearer para obter uma lista de todos os espaços de trabalho associados a uma conta.

  • Substitua <oauth-access-token> pelo token de acesso OAuth da entidade de serviço que você copiou na etapa anterior.
  • Substitua <account-id> pela 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 da API REST no nível do workspace

Este exemplo usa Bearer a autenticação para listar todos os clusters disponíveis no workspace especificado.

  • Substitua <oauth-access-token> pelo token de acesso OAuth da entidade de serviço que você copiou na etapa anterior.
  • Substitua <workspace-URL> pela URL do seu espaço de trabalho básico, que tem a forma semelhante a dbc-a1b2345c-d6e7.cloud.databricks.com.
export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

Recursos adicionais