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

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

Etapa 1: Criar uma entidade de serviço

Os administradores de contas e os administradores do site workspace podem criar uma entidade de serviço. Este passo descreve a criação de uma entidade de serviço em um site workspace. Para usar o console account, consulte gerenciar entidade de serviço em seu account.

  1. Como administrador do workspace, faça login no workspace do Databricks.

  2. Clique no seu nome de usuário na barra superior do workspace do 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, em seguida, clique em Adicionar nova.

  7. Insira um nome para a entidade de serviço.

  8. Clique em Adicionar.

A entidade de serviço é adicionada ao seu espaço de trabalho e à conta do Databricks.

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

  1. Clique no nome da entidade de serviço para abrir a página de detalhes.

  2. Em Configurations (Configurações ) tab, marque a caixa ao lado de cada direito que o senhor deseja que sua entidade de serviço tenha para esse workspace e, em seguida, clique em Update (Atualizar).

  3. Em Permissions (Permissões ) tab, conceda acesso a qualquer Databricks usuário, entidade de serviço e grupo que o senhor deseja gerenciar e usar essa entidade de serviço. Veja como gerenciar funções em uma entidade de serviço.

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

Antes que possa usar o OAuth para se autenticar no Databricks, você deve primeiro criar um segredo do OAuth, que pode ser usado para gerar tokens de acesso do OAuth. Uma entidade de serviço pode ter até cinco segredos do OAuth. Os administradores de contas e os administradores de workspaces podem criar um segredo do OAuth para uma entidade de serviço.

  1. Na página de detalhes de sua entidade de serviço, clique em Secrets tab.

  2. Em Segredos do OAuth, clique em Gerar segredo.

    Gerar o segredo OAuth a partir de workspace

  3. 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. A ID do cliente é igual à 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 account.

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

  2. Clique em Icone de gerenciamento de usuários do console da conta Gerenciamento de usuários.

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

  4. Em Segredos do OAuth, clique em Gerar segredo.

    Gerar o segredo OAuth a partir de workspace

  5. Copie o Segredo e a 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.

Passo 4: Use a autenticação OAuth M2M

Para usar a autenticação OAuth M2M, o senhor deve definir os seguintes campos associados variável de ambiente, .databrickscfg, Terraform ou Config:

  • O host do Databricks, especificado como https://accounts.cloud.databricks.com para operações de contas ou a URL do espaço de trabalho de destino, como por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com para operações de workspaces.

  • O ID da conta do Databricks, para operações da conta do Databricks.

  • O ID do cliente da entidade de serviço.

  • O segredo da entidade de serviço.

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

Para usar a variável de ambiente para um tipo específico de autenticação Databricks com uma ferramenta ou SDK, consulte Autenticar o acesso a Databricks recurso ou a documentação da ferramenta ou SDK. Consulte também variável de ambiente e campos para autenticação unificada de cliente e os métodos padrão para autenticação unificada de cliente.

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

  • DATABRICKS_HOST, defina para a URL do console da conta do Databricks, https://accounts.cloud.databricks.com.

  • DATABRICKS_ACCOUNT_ID

  • DATABRICKS_CLIENT_ID

  • DATABRICKS_CLIENT_SECRET

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

  • DATABRICKS_HOST, defina como a URL do workspace do Databricks, como por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com.

  • DATABRICKS_CLIENT_ID

  • DATABRICKS_CLIENT_SECRET

Crie ou identifique um perfil de configuração do Databricks com os seguintes campos em seu arquivo .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 Databricks recurso ou a documentação da ferramenta ou SDK. Consulte também variável de ambiente e campos para autenticação unificada de cliente e os métodos padrão para autenticação unificada de cliente.

Para operações em nível de conta, defina os seguintes valores em seu arquivo .databrickscfg. Nesse caso, a URL do console da conta do Databricks é https://accounts.cloud.databricks.com:

[<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 em nível de workspace, defina os seguintes valores em seu arquivo .databrickscfg. Nesse caso, o host é a URL do workspace do Databricks, como por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com:

[<some-unique-configuration-profile-name>]
host          = <workspace-url>
client_id     = <service-principal-client-id>
client_secret = <service-principal-secret>

Para a CLI do Databricks, faça um das coisas a seguir:

  • Defina as variáveis de ambiente conforme especificado na seção "Ambiente" deste artigo.

  • Defina os valores em seu arquivo .databrickscfg 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 Autenticação OAuth máquina a máquina (M2M).

Observação

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

  • Para o Python, Databricks Connect para Databricks Runtime 13.1 e superior.

  • Para o Scala, Databricks Connect para Databricks Runtime 13.3 LTS e superior.

Para o Databricks Connect, você pode fazer um das coisas a seguir:

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 arquivo .databrickscfg, consulte a configuração de computação para Databricks Connect.

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

  1. Defina os valores em seu arquivo .databrickscfg para operações em nível de workspace do 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 Databricks.

  3. Na Paleta de comandos, em Host do Databricks, digite sua URL do workspace, como por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com, e pressione Enter.

  4. Na Paleta de comandos, selecione o nome de seu perfil de destino na lista para sua URL.

Para obter mais detalhes, consulte Configuração de autenticação para a extensão do Databricks para Visual Studio Code.

Para operações de nível account, para autenticação padrão:

provider "databricks" {
  alias = "accounts"
}

Para configuração direta (substitua os espaços reservados do retrieve por sua própria implementação para recuperar os valores do console ou algum outro armazenamento de configuração, como o HashiCorp Vault. Consulte também Provedor de cofre). Nesse caso, a URL do console da conta do Databricks é https://accounts.cloud.databricks.com:

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 em nível workspace, para autenticação padrão:

provider "databricks" {
  alias = "workspace"
}

Para configuração direta (substitua os espaços reservados do retrieve por sua própria implementação para recuperar os valores do console ou algum outro armazenamento de configuração, como o HashiCorp Vault. Consulte também Provedor de cofre). Nesse caso, o host é a URL do workspace do Databricks, como por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com:

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 se autenticar com o provedor do Terraform do Databricks, consulte Autenticação.

Para operações em nível account, 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 do retrieve por sua própria implementação, para recuperar os valores do console ou outro armazenamento de configuração, como o AWS Systems Manager Parameter Store. Nesse caso, a URL do console da conta do Databricks é https://accounts.cloud.databricks.com:

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 em nível de workspace, especificamente autenticação padrão:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para configuração direta, substitua os espaços reservados do retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como o AWS Systems Manager Parameter Store. Nesse caso, o host é a URL do workspace do Databricks, como por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com:

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

Para operações de nível account, para autenticação padrão:

import com.databricks.sdk.AccountClient;
// ...
AccountClient a = new AccountClient();
// ...

Para configuração direta (substitua os espaços reservados do retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como o AWS Systems Manager Parameter Store). Nesse caso, a URL do console da conta do Databricks é https://accounts.cloud.databricks.com:

import com.databricks.sdk.AccountClient;
import com.databricks.sdk.core.DatabricksConfig;
// ...
DatabricksConfig cfg = new DatabricksConfig()
  .setHost(retrieveAccountConsoleUrl())
  .setAccountId(retrieveAccountId())
  .setClientId(retrieveClientId())
  .setClientSecret(retrieveClientSecret());
AccountClient a = new AccountClient(cfg);
// ...

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

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

Para configuração direta (substitua os espaços reservados do retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como o AWS Systems Manager Parameter Store). Nesse caso, o host é a URL do workspace do Databricks, como por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com:

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

Para operações de nível account, para autenticação padrão:

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

Para configuração direta (substitua os espaços reservados do retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como o AWS Systems Manager Parameter Store). Nesse caso, a URL do console da conta do Databricks é https://accounts.cloud.databricks.com:

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 workspace, 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 do retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como o AWS Systems Manager Parameter Store). Nesse caso, o host é a URL do workspace do Databricks, como por exemplo, https://dbc-a1b2345c-d6e7.cloud.databricks.com:

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

Para mais informações sobre autenticação com ferramentas e SDKs do Databricks que usam Go e implementam autenticação unificada do cliente Databricks, veja Autentique o SDK do Databricks para Go com sua account ou workspace do Databricks.

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

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

Databricks recomenda o uso da autenticação unificada do cliente; no entanto, se for necessário gerar manualmente, refresh, ou usar Databricks OAuth access tokens, siga as instruções desta seção.

Use o ID do cliente da entidade de serviço e o segredo OAuth para solicitar um OAuth access token para autenticar tanto o account-level REST APIs quanto o workspace-level REST APIs. O access token expirará em uma hora. O senhor deve solicitar um novo OAuth access token após a expiração. O escopo do OAuth access token depende do nível a partir do qual o senhor cria os tokens. O senhor pode criar tokens no nível account ou no nível workspace, da seguinte forma:

Gere manualmente um token de acesso em nível de conta

Um token de acesso do OAuth criado em nível de conta pode ser usado em APIs REST do Databricks na conta e em quaisquer workspaces aos quais a entidade de serviço tenha acesso.

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

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

  3. Copie a ID de sua conta.

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

    https://accounts.cloud.databricks.com/oidc/accounts/<my-account-id>/v1/token

  5. Use um cliente como o curl para solicitar um token de acesso do OAuth com a URL do endpoint do token, a ID do cliente da entidade de serviço (também conhecida como ID do aplicativo) e o segredo do OAuth da entidade de serviço que você criou. O escopo all-apis solicita um token de acesso do 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 endpoint 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 do 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 access_token da resposta.

Gere manualmente um token de acesso em nível de workspace

Um token de acesso do OAuth criado em nível de 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 workspace da implantação do Databricks:

    https://<databricks-instance>/oidc/v1/token

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

    • Substitua <token-endpoint-URL> pela URL do endpoint 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 do 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 access_token da resposta.

Chamar uma API REST da Databricks

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

Você pode incluir o token no cabeçalho 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 em nível de conta

Este exemplo usa a autenticação Bearer para obter uma lista de todos os workspaces associados a uma conta.

  • Substitua <oauth-access-token> pelo token de acesso do OAuth da entidade de serviço que você copiou na etapa anterior.

  • Substitua <account-id> pela ID de sua conta.

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://accounts.cloud.databricks.com/api/2.0/accounts/<account-id>/workspaces'

Exemplo de solicitação de API REST em nível de workspace

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

  • Substitua <oauth-access-token> pelo token de acesso do OAuth da entidade de serviço que você copiou na etapa anterior.

  • Substitua <workspace-URL> pela URL de seu workspace básico, que tem um formato 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