Partilhar via


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 a partir de um código que será executado a partir de um processo autônomo.

O Azure Databricks usa OAuth como o protocolo preferencial para autorização e autenticação de 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 ela 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 de autorização (OAuth) usado para negociar o acesso a recursos específicos do Azure Databricks por meio de delegação. A autenticação refere-se ao mecanismo pelo qual as credenciais são representadas, transmitidas e verificadas — que, neste caso, são tokens de acesso.

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

O Azure Databricks suporta duas formas de autorizar o acesso a um principal de serviço com OAuth.

  • Principalmente automaticamente, usando o suporte à autenticação de cliente unificada Databricks. Use essa abordagem simplificada se estiver usando SDKs específicos do Azure Databricks (como o SDK do Databricks Terraform) e ferramentas. As ferramentas e SDKs suportados estão listados na autenticação de cliente unificada do 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 não estiver usando uma API suportada pela autenticação de cliente unificada Databricks. Neste caso, poderás precisar desenvolver o teu próprio mecanismo para lidar com a atualização de tokens de acesso específicos da ferramenta ou API de terceiros que estás a utilizar. Para obter mais detalhes, consulte: Gerar e usar manualmente tokens de acesso para autenticação do principal de serviço OAuth.

Antes de começar, deverá configurar uma entidade de serviço do Azure Databricks e atribuir-lhe as permissões apropriadas para aceder aos recursos que deverá usar quando o seu código de automação ou comandos os solicitarem.

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

Os administradores de conta e os administradores de espaço de trabalho podem criar entidades de serviço. Esta etapa descreve a criação de um principal de serviço num espaço de trabalho do Azure Databricks. Para obter detalhes sobre o próprio console da conta do Azure Databricks, consulte Adicionar entidades de serviço à sua conta.

Você também pode criar um principal de serviço gerido pela Microsoft Entra ID e adicioná-lo ao Azure Databricks. Para obter mais informações, consulte Databricks e entidades de serviço do Microsoft Entra ID.

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

O princípio de serviço é adicionado tanto ao seu espaço de trabalho quanto à conta do Azure Databricks.

Etapa 1: conceder permissões ao 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 permissão que deseja que a entidade de serviço tenha para este espaço de trabalho e clique em Atualizar.
  3. No separador Permissões, conceda acesso a quaisquer utilizadores, entidades de serviço e grupos do Azure Databricks que deseje gerir e usar esta entidade de serviço. Consulte 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, você deve primeiro criar um segredo OAuth, que pode ser usado para gerar tokens de acesso OAuth para autenticação. Um principal de serviço pode ter até cinco segredos OAuth.

Os segredos OAuth têm uma vida útil máxima de dois anos. Os administradores de conta e de espaço de trabalho podem criar uma chave OAuth para uma entidade de serviço.

  1. Na página de detalhes do principal de serviço, clique no separador Segredos.

  2. Em Segredos OAuth, clique em Gerar segredo.

    Gerar segredo OAuth a partir do espaço de trabalho

  3. Defina a vida útil do segredo em dias. Os segredos OAuth têm uma vida útil máxima de 730 dias (dois anos).

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

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

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

  1. Como administrador da conta, inicie sessão na consola da conta.

  2. Na barra lateral, clique em Gerenciamento 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 da conta

  5. Defina a vida útil do segredo em dias. Os segredos OAuth têm uma vida útil máxima de 730 dias (dois anos).

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

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 3: Usar a autorização 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 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 Autorizando 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 de cliente unificada e os métodos padrão para autenticação unificada de cliente.

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

  • DATABRICKS_HOST, definido para o 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 URL por espaço de trabalho 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 .databrickscfg arquivo. Se criares o perfil, substitui os marcadores pelos valores apropriados. Para usar o perfil 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 e campos de ambiente para autenticação de cliente unificada e os métodos padrão para autenticação unificada de cliente.

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>

Interface de Linha de Comandos (CLI)

Para a CLI do Databricks, siga um destes procedimentos:

  • Defina as variáveis de ambiente conforme especificado na seção "Ambiente" deste artigo.
  • Defina os valores em seu .databrickscfg arquivo conforme especificado na seção "Perfil" deste artigo.

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 seguir um destes procedimentos:

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

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

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

Código VS

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

  1. Defina os valores em seu .databrickscfg arquivo para operações no nível do espaço de trabalho do Azure Databricks, conforme especificado na seção "Perfil" deste artigo.
  2. No painel Configuração da extensão Databricks para Visual Studio Code, clique em Configurar Databricks.
  3. 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.
  4. 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

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

provider "databricks" {
  alias = "accounts"
}

Para configuração direta (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 Vault Provider). 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 ao nível do espaço de trabalho, para a autenticação padrão:

provider "databricks" {
  alias = "workspace"
}

Para configuração direta (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 Vault Provider). Nesse caso, o host é a URL do Azure Databricks associada a cada espaço de trabalho, por exemplo :

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 Databricks Terraform, consulte Autenticação.

Píton

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 retrieve marcadores de posição por sua própria implementação, para obter 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:

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 do espaço de trabalho, especificamente a autenticação padrão:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para configuração direta, substitua os retrieve marcadores pela sua própria implementação para recuperar os valores do console ou de outra fonte de configuração, como o Azure KeyVault. Nesse caso, o host é a URL do Azure Databricks associada a cada espaço de trabalho, por exemplo :

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 ferramentas Databricks e SDKs que usam Python e implementam a autenticação unificada do cliente Databricks, 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

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

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

Para configuração direta (substitua os retrieve marcadores de posição pela sua própria implementação para recuperar os valores da consola ou de outro repositório de configuração, como o Azure KeyVault). Nesse caso, o host é a URL do Azure Databricks associada a cada espaço de trabalho, por exemplo :

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 a autenticação com ferramentas Databricks e SDKs que usam Java e implementam a autenticação unificada do cliente Databricks, consulte:

Vai

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

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

Para configuração direta (substitua os retrieve marcadores de posição pela sua própria implementação para recuperar os valores da consola 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:

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 no nível do espaço de trabalho usando autenticação padrão:

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

Para configuração direta (substitua os retrieve marcadores de posição pela sua própria implementação para recuperar os valores da consola ou de outro repositório de configuração, como o Azure KeyVault). Nesse caso, o host é a URL do Azure Databricks associada a cada espaço de trabalho, por exemplo :

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 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 e usar manualmente tokens de acesso para autenticação do principal de 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 o uso da 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 OAuth para solicitar um token de acesso OAuth para autenticar em APIs REST no nível da conta e APIs REST no nível do espaço de trabalho. 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 espaço de trabalho, 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 espaço de trabalho ao qual o principal do serviço tenha acesso.

  1. Como administrador da conta, inicie sessão na consola da conta.

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

  3. Copie o ID da sua conta.

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

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

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

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

  1. Crie a URL do endpoint do token substituindo https://<databricks-instance> pela URL do espaço de trabalho da sua implementação do Azure Databricks.

    https://<databricks-instance>/oidc/v1/token
    
  2. Utilize um cliente tal como curl para solicitar um token de acesso OAuth com o URL do endpoint do token, a identificação do cliente da entidade de serviço (também conhecida como ID de aplicativo) e o segredo OAuth da entidade de serviço que criou. O all-apis âmbito solicita um token de acesso OAuth que pode ser utilizado para aceder a todas as APIs REST do Databricks às quais o principal do serviço tem acesso, dentro do espaço de trabalho do qual está a solicitar o token.

    • Substitua <token-endpoint-URL> pela URL do ponto de extremidade do token anterior.
    • Substitua <client-id> pela ID do cliente da entidade de serviço, que também é conhecida como ID da aplicação.
    • Substitua <client-secret> pelo segredo OAuth do principal do serviço que 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 APIs REST no nível da conta do Azure Databricks e APIs REST no nível do espaço de trabalho . A entidade de serviço deve ter privilégios de administrador de conta para invocar as APIs REST a nível da conta.

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

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

Este 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 do principal de serviço que copiou na etapa anterior.
  • Substitua <account-id> pelo 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 usa a autenticação Bearer para listar todos os clusters disponíveis no espaço de trabalho especificado.

  • Substitua <oauth-access-token> pelo token de acesso OAuth do principal de serviço que copiou na etapa anterior.
  • Substitua <workspace-URL> pelo URL do espaço de trabalho base, que tem o formato semelhante ao 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