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

Artigo
01/21/2025

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 espaço de trabalho podem criar entidades de serviço. Esta etapa descreve a criação de uma entidade de serviço em um espaço de trabalho. Para utilizar a consola da conta, consulte Gerir entidades de serviço na sua conta.

Você também pode criar uma entidade de serviço gerenciada do Microsoft Entra ID 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 espaço de trabalho, faça logon no espaço de trabalho do Azure Databricks.
Clique no seu nome de utilizador na barra superior da área de trabalho do Azure Databricks e selectDefiniçõ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, em seguida, clique em Adicionar novo.
Em Gerenciamento, escolha Databricks gerenciados.
Insira um nome para a entidade de serviço.
Clique em Adicionar.

A entidade de serviço é adicionada ao seu espaço de trabalho 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 do , marque a caixa ao lado de cada direito que você deseja que sua entidade de serviço tenha para este espaço de trabalho e clique em .
Na guia Permissões, grant acesso a todos os usuários, entidades de serviço e grupos do Azure Databricks que você deseja gerenciar e usar essa entidade de serviço. Consulte 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, você deve primeiro criar um segredo OAuth, que pode ser usado para generate tokens de acesso OAuth. Uma entidade de serviço pode ter até cinco segredos OAuth. Os administradores de conta e de espaço de trabalho 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 .
Sob a secção de segredos OAuth, clique em Generate segredo.
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 generate um segredo OAuth na página de detalhes da entidade de serviço no console da conta.

Como administrador da conta, inicie sessão na consola da conta.
Clique em Gerenciamento de usuários.
Na guia Entidades de serviço, select a sua entidade de serviço.
Em segredos OAuth, clique em Generate segredo.
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 SQL warehouses, você deve conceder à entidade de serviço acesso a eles. Consulte Permissões de computação ou Gerenciar um armazém SQL.

Etapa 4: Usar a autenticação OAuth M2M

Para usar a autenticação OAuth M2M, você deve set 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 de destino por espaço de trabalho, por exemplohttps://adb-1234567890123456.7.azuredatabricks.net, para operações de espaço de trabalho.
A ID da conta do Azure Databricks, para operações de conta do Azure Databricks.
O ID do cliente da entidade de serviço.
O segredo principal do serviço.

Para executar a autenticação OAuth M2M, integre o seguinte em seu código, com base na ferramenta participante ou SDK:

Environment

Para usar variáveis de ambiente para um tipo de autenticação específico do Azure Databricks com uma ferramenta ou SDK, consulte Autenticar 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 os métodos padrão para autenticação unificada do cliente.

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

DATABRICKS_HOST, set para 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 espaço de trabalho , as seguintes variáveis de ambiente, set:

, aode URL por espaço de trabalho do Azure Databricks , por exemplo, .
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. Ao criar o perfil, substitua os marcadores de posição pelo valuesapropriado. Para usar o perfil com uma ferramenta ou SDK, consulte Autenticar o acesso aos recursos do Azure Databricks ou à documentação da ferramenta ou do SDK. Consulte também Variáveis de ambiente e campos para autenticação unificada do cliente e os métodos padrão para autenticação unificada do cliente.

Para operações no nível da conta, set as seguintes values no 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 espaço de trabalho, set as seguintes values no arquivo .databrickscfg. Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplohttps://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

Para a CLI do Databricks, siga um destes procedimentos:

Set as variáveis de ambiente conforme especificado na seção "Ambiente" deste artigo.
Set o values no arquivo .databrickscfg, conforme especificado na seção "Perfil" deste artigo.

As variáveis de ambiente sempre têm precedência sobre values em seu arquivo .databrickscfg.

Consulte também a autenticação OAuth máquina-a-máquina (M2M).

Ligar

Nota

A autenticação OAuth M2M é suportada nas seguintes versões do Databricks Connect:

Para Python, Databricks Connect for Databricks Runtime 14.0 e superior.
Para Scala, Databricks Connect for Databricks Runtime 13.3 LTS e superior. 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:

Set o values no seu arquivo .databrickscfg para operações ao nível do espaço de trabalho do Azure Databricks , conforme especificado na secção "Perfil" deste artigo. Além disso, set a variável de ambiente cluster_id no seu perfil para o URL por espaço de trabalho, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.
Set as variáveis de ambiente para o Azure Databricks de operações no nível do espaço de trabalho, conforme especificado na seção "Ambiente" deste artigo. Além disso, set a variável de ambiente DATABRICKS_CLUSTER_ID para o URL por espaço de trabalho, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

Values no seu arquivo .databrickscfg têm sempre precedência sobre as variáveis de ambiente.

Para inicializar o cliente Databricks Connect com estas variáveis de ambiente ou com values no seu ficheiro de .databrickscfg, consulte a configuração de computação para o Databricks Connect.

Código VS

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

Set o values no seu arquivo .databrickscfg para operações no nível do espaço de trabalho do Azure Databricks , conforme indicado na seção "Perfil" deste artigo.
No painel Configuração da extensão Databricks para Visual Studio Code, clique em Configurar Databricks.
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.
Na Paleta de Comandos, select o nome do perfil de destino no list para o seu URL.

Para obter mais detalhes, consulte Configuração de autenticação para a extensão 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 marcadores retrieve por sua própria implementação para obter o values do console ou de um outro repositório de configuração, como HashiCorp Vault. Consulte também Provedor do Vault). 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 espaço de trabalho, para autenticação padrão:

provider "databricks" {
  alias = "workspace"
}

Para configuração direta (substitua os marcadores de posição retrieve pela sua própria implementação para recuperar o values do console ou de algum outro armazenamento de configuração, como o HashiCorp Vault. Veja também o Provedor do Vault). Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplohttps://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 Databricks Terraform, 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, utilize o seguinte, substituindo os placeholders retrieve pela sua própria implementação, para recuperar o values 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 do espaço de trabalho, especificamente a autenticação padrão:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para configuração direta, substitua os placeholders retrieve pela sua própria implementação para recuperar o values do console ou de outro repositório de configuração, como, por exemplo, o Azure KeyVault. Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplohttps://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 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 OAuth M2M.

Java

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

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

Para configuração direta (substitua os marcadores de posição retrieve pela sua própria implementação para recuperar o values do console ou de outro repositório de configuração, como o Azure KeyVault). Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplohttps://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 a autenticação com ferramentas Databricks e SDKs que usam Java e implementam a autenticação unificada do cliente Databricks, consulte:

Set configurar o cliente Databricks Connect para Scala (o cliente Databricks Connect para Scala usa o Databricks SDK para Java incluído para autenticação)
Autenticar o SDK do Databricks para 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 configuração direta (substitua os marcadores de posição retrieve pela sua própria implementação para recuperar o values 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:

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, para autenticação padrão:

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

Para configuração direta (substitua os espaços reservados retrieve por sua própria implementação para recuperar o values do console ou de outro repositório de configuração, como Azure KeyVault). Nesse caso, o host é a URL do Azure Databricks por espaço de trabalho, por exemplohttps://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 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.

Usar tokens de acesso manualmente generate para autenticação OAuth M2M

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

O Databricks recomenda o uso da autenticação unificada do cliente, no entanto, se você precisar generatemanualmente , refreshou usar 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:

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

Crie manualmente generate um token de acesso ao nível da conta

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

Como administrador da conta, inicie sessão na consola da conta.
Clique na seta para baixo ao lado do seu nome de usuário no canto superior direito.
Copie o ID da sua conta.
Construa a URL do ponto de extremidade do token substituindo <my-account-id> a URL a seguir pela ID da conta que você copiou.
```
https://accounts.azuredatabricks.net/oidc/accounts/<my-account-id>/v1/token
```
Use um cliente como 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 de 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 do cliente da entidade de serviço, que também é conhecida como ID do 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.

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

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 como 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 de 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 dentro do espaço de trabalho 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 do cliente da entidade de serviço, que também é conhecida como ID do 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 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 ser um administrador de conta para chamar APIs REST no nível da conta.

Você pode incluir o token no cabeçalho usando Bearer autenticação. 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 get uma list 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> 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 list todos os clusters que estejam disponíveis no espaço de trabalho indicado.

Substitua <oauth-access-token> pelo token de acesso OAuth da entidade de serviço que você 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

Principais de serviço
Visão geral do modelo de identidade Databricks
Informações adicionais sobre autenticação e controle de acesso

Partilhar 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

Environment

Perfil

CLI

Ligar

Código VS

Terraform

Python

Java

Go

Usar tokens de acesso manualmente generate para autenticação OAuth M2M

Crie manualmente generate um token de acesso ao nível da conta

generate manualmente um token de acesso no nível do espaço de trabalho

Chamar uma API REST do Databricks

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

Exemplo de solicitação de API REST no nível do espaço de trabalho

Recursos adicionais

Comentários

Recursos adicionais