Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M)

Artigo
11/09/2024

Este artigo explica como criar uma entidade de serviço do Azure Databricks e usá-la para autenticar em uma entidade de destino com OAuth.

Etapa 1: criar uma entidade de serviço

Os administradores de conta e os administradores de workspace podem criar entidades de serviço. Esta etapa descreve a criação de uma entidade de serviço em um workspace. Para usar o console da conta, consulte 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.

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

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

Etapa 2: Atribuir permissões à entidade de serviço

Clique no nome da entidade de serviço para abrir a página de detalhes.
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.
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 3: Criar um segredo OAuth para uma entidade de serviço

Antes de poder usar o OAuth para autenticar no Azure Databricks, primeiro você deve criar um segredo OAuth, que pode ser usado para gerar tokens de acesso OAuth. 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.

Na página de detalhes da entidade de serviço, clique na guia Segredos .
Em Segredos OAuth, clique em Gerar segredo.
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.

Como administrador de conta, faça logon no console da conta.
Clique em Gerenciamento de Usuários.
Na guia Entidades de serviço, selecione sua entidade de serviço.
Em Segredos OAuth, clique em Gerar segredo.
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 4: Usar a autenticação OAuth M2M

Para usar a autenticação OAuth M2M, você deve definir as seguintes variáveis de ambiente associadas, .databrickscfg campos, campos do Terraform ou Config campos:

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 do M2M do OAuth, integre o seguinte em seu código, com base na ferramenta ou SDK participante:

Ambiente

Para usar variáveis de ambiente para um tipo de autenticação do Azure Databricks específico com uma ferramenta ou SDK, consulte Autenticar o acesso a recursos do Azure Databricks ou a documentação da ferramenta ou 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 Autenticar o acesso a recursos do Azure Databricks ou a documentação da ferramenta ou 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 do OAuth M2M tem suporte para 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 esses valores no arquivo .databrickscfg, confira um dos seguintes artigos:

No caso do Python, confira Configurar as propriedades de conexão do Python.
No caso do Scala, confira Configurar as propriedades de conexão do Scala.

Código VS

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

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.
No painel Configuração da extensão do Databricks para Visual Studio Code, clique em Configurar o Databricks.
Na Paleta de Comandos, em Host do Databricks, insira a URL por workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net, e pressione Enter.
Na Paleta de Comandos, selecione o nome do perfil de destino na lista da URL.

Para obter mais detalhes, confira Configuração de autenticação da extensão do Databricks para 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 M2M do OAuth.

Java

Para operações no nível do workspace, para 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:

Configurar o cliente do Databricks Connect para o Scala (o cliente do Databricks Connect para o Scala usa o SDK do Databricks incluído para o Java para autenticação)
Autenticar o SDK do Databricks para o Java com sua conta ou espaço de trabalho do Azure Databricks

Go

Para operações no nível da conta, para 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 no nível do workspace, para autenticação padrão:

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

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 OAuth M2M

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

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:

Para chamar APIs REST no nível da conta e no nível do workspace em contas e workspaces aos quais a entidade de serviço tem acesso, gere manualmente um token de acesso no nível da conta.
Para chamar APIs REST em apenas um dos workspaces aos quais a entidade de serviço tem acesso, gere manualmente um token de acesso no nível do workspace apenas para esse workspace.

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.

Como administrador de conta, faça logon no console da conta.
Clique na seta para baixo ao lado do seu nome de usuário no canto superior direito.
Copie sua ID da conta.
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
```
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.

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
```
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

Agora você pode usar o token de acesso OAuth para se autenticar nas APIs REST no nível da conta do Azure Databricks e nas APIs REST no nível do workspace. A entidade de serviço deve ser um administrador de conta para chamar APIs REST no nível da conta.

Você pode incluir o token no cabeçalho usando a autenticação do Bearer. 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

Entidades de serviço
Visão geral do Modelo de identidade do Databricks
Informações adicionais sobre a autenticação e controle de acesso

Compartilhar via

Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M)

Etapa 1: criar uma entidade de serviço

Etapa 2: Atribuir permissões à entidade de serviço

Etapa 3: Criar um segredo OAuth para uma entidade de serviço

Etapa 4: Usar a autenticação OAuth M2M

Ambiente

Perfil

CLI

Conectar

Código VS

Terraform

Python

Java

Go

Gerar e usar manualmente tokens de acesso para autenticação OAuth M2M

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

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

Chamar uma API REST do Databricks

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

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

Recursos adicionais

Comentários

Recursos adicionais