Autorizar o acesso autônomo a Databricks recurso com uma entidade de serviço usando OAuth

Este tópico fornece as etapas e os detalhes para autorizar o acesso a Databricks recurso ao automatizar Databricks CLI comando ou chamar Databricks REST APIs a partir de um código que será executado a partir de um processo não supervisionado.

Databricks usa o OAuth como o protocolo preferencial para autorização e autenticação de usuários ao interagir com o Databricks recurso fora da interface do usuário. Databricks também fornece a ferramenta de autenticação de cliente unificada para automatizar o refresh do acesso tokens gerado como parte do método de autenticação do OAuth. Isso se aplica tanto à entidade de serviço quanto à conta de usuário, mas o senhor deve configurar uma entidade de serviço com as permissões e privilégios apropriados para o recurso Databricks que ela deve acessar como parte de suas operações.

Para obter mais detalhes de alto nível, consulte Autorização de acesso a Databricks recurso.

Quais são minhas opções de autorização e autenticação ao usar uma entidade de serviço da Databricks?

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

Databricks usa a autorização baseada emOAuth 2.0para permitir o acesso a Databricks account e workspace recurso 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 Databricks entidade de serviço é configurada e suas credenciais são verificadas quando ela executa um CLI comando ou chama um REST API, um OAuth tokens é fornecido à ferramenta participante ou SDK para executar a autenticação baseada em tokens em nome da entidade de serviço a partir desse momento. Os tokens de acesso OAuth têm uma vida útil de uma hora, após a qual a ferramenta ou o site SDK envolvido fará uma tentativa automática em segundo plano para obter um novo token que também é válido por uma hora.

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

Principalmente de forma automática, usando o suporte de autenticação de cliente unificado do Databricks. Use essa abordagem simplificada se estiver usando SDKs específicos da Databricks (como o SDK do Databricks Terraform) e ferramentas. As ferramentas e os SDKs compatíveis estão listados em Autenticação de cliente unificada da Databricks. Essa abordagem é adequada para automação ou outros cenários de processos autônomos.
Manualmente, gerando diretamente um par verificador/desafio de código OAuth e um código de autorização, e usando-os para criar os tokens OAuth iniciais que o senhor fornecerá na sua configuração. Use essa abordagem quando não estiver usando uma API compatível com a autenticação de cliente unificada da Databricks. Nesse caso, talvez seja necessário desenvolver seu próprio mecanismo para lidar com o refresh de acesso tokens específico da ferramenta de terceiros ou API que o senhor está usando. Para obter mais detalhes, consulte: Gerar e usar manualmente o acesso tokens para autenticação da entidade de serviço OAuth .

Antes de começar, o senhor deve configurar uma Databricks entidade de serviço e atribuir a ela as permissões apropriadas para acessar o recurso que deve ser usado quando o código de automação ou o comando os solicitar.

Pré-requisito: Criar uma entidade de serviço

Os administradores de contas e os administradores do site workspace podem criar entidades de serviço. Esta etapa descreve a criação de uma entidade de serviço em um site Databricks workspace. Para obter detalhes sobre o console Databricks account propriamente dito, consulte gerenciar entidade de serviço em seu account.

Como administrador do workspace, faça login no workspace do Databricks.
Clique no seu nome de usuário na barra superior do workspace do 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, em seguida, clique em Adicionar nova.
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 Databricks.

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

Clique no nome da entidade de serviço para abrir a página de detalhes.
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).
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.

passo 2: criar um segredo OAuth para uma entidade de serviço

Antes de usar o site OAuth para autorizar o acesso ao seu recurso Databricks, o senhor deve primeiro criar um segredo OAuth, que pode ser usado para gerar o acesso OAuth tokens para autenticação. Uma entidade de serviço pode ter até cinco segredos OAuth. Os administradores de contas e os administradores do site workspace podem criar um segredo OAuth para uma entidade de serviço.

Na página de detalhes de sua entidade de serviço, clique em Secrets tab.
Em Segredos do OAuth, clique em Gerar 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. 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.

Como administrador da conta, faça login no console da conta.
Clique em Gerenciamento de usuários.
Na guia Entidades de serviço, selecione sua entidade de serviço.
Em Segredos do OAuth, clique em Gerar segredo.
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.

Etapa 3: Use a autorização OAuth

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

O host do Databricks, especificado como https://accounts.gcp.databricks.com para operações de contas ou a URL do espaço de trabalho de destino, como por exemplo, https://1234567890123456.7.gcp.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 realizar a autenticação da OAuth entidade de serviço, integre o seguinte em seu código, com base na ferramenta participante ou SDK:

Para usar a variável de ambiente para um tipo específico de autenticação Databricks com uma ferramenta ou SDK, consulte Autorização de 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 de nível account, defina as seguintes variáveis de ambiente:

DATABRICKS_HOST, defina para a URL do console da conta do Databricks, https://accounts.gcp.databricks.com.
DATABRICKS_ACCOUNT_ID
DATABRICKS_CLIENT_ID
DATABRICKS_CLIENT_SECRET

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

DATABRICKS_HOST, defina como a URL do workspace do Databricks, como por exemplo https://1234567890123456.7.gcp.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 Autorização de acesso ao recurso Databricks 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 de nível account, defina os seguintes valores no .databrickscfg arquivo . Nesse caso, a URL do console account Databricks é https://accounts.gcp.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 no nível workspace, defina os seguintes valores no seu arquivo .databrickscfg . Nesse caso, o host é a URL do workspace do Databricks, por exemplo, https://1234567890123456.7.gcp.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

OAuth A autenticação da entidade de serviço é suportada em Databricks Connect para Python e Scala para Databricks Runtime 13.3 LTS e acima.

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

Defina os valores no seu arquivo .databrickscfg para operações no nível workspace do Databricks, conforme especificado na seção “Perfil” deste artigo. Defina também a variável de ambiente cluster_id no seu perfil para a URL da instância do seu workspace, por exemplo https://1234567890123456.7.gcp.databricks.com.
Defina as variáveis de ambiente para operações no nível workspace do Databricks, conforme especificado na seção "Ambiente" deste artigo. Defina também a variável de ambiente DATABRICKS_CLUSTER_ID como a URL da instância do seu workspace, por exemplo https://1234567890123456.7.gcp.databricks.com.

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:

Defina os valores no seu arquivo .databrickscfg para operações no nível workspace do 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 Databricks.
Na Paleta de comandos, em Host do Databricks, digite sua URL do workspace, como por exemplo, https://1234567890123456.7.gcp.databricks.com, e pressione Enter.
Na Paleta de comandos, selecione o nome de seu perfil de destino na lista para sua URL.

Para obter mais detalhes, consulte Configurar autorização para a extensão 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.gcp.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://1234567890123456.7.gcp.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 placeholders retrieve por sua própria implementação, para recuperar os valores do console ou de outro armazenamento de configuração, como o Google Cloud Secret Manager. Nesse caso, a URL do console da account Databricks é https://accounts.gcp.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 placeholders retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como Google Cloud Secret Manager. Nesse caso, o host é a URL do workspace do Databricks, por exemplo, https://1234567890123456.7.gcp.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 placeholders retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como Google Cloud Secret Manager). Nesse caso, a URL do console da account Databricks é https://accounts.gcp.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);
// ...

workspacePara operações de nível usando a default autenticação:

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

Para configuração direta (substitua os placeholders retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como Google Cloud Secret Manager). Nesse caso, o host é a URL do workspace do Databricks, por exemplo, https://1234567890123456.7.gcp.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:

Configure o cliente do Databricks Connect para Scala (o cliente do Databricks Connect para Scala usa o SDK do Databricks para Java incluído para autenticação)
Autentique o SDK do Databricks para Java com sua conta ou workspace do Databricks

accountPara operações de nível usando a default autenticação:

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

Para configuração direta (substitua os placeholders retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como Google Cloud Secret Manager). Nesse caso, a URL do console da account Databricks é https://accounts.gcp.databricks.com:

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

workspacePara operações de nível usando a default autenticação:

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

Para configuração direta (substitua os placeholders retrieve por sua própria implementação para recuperar os valores do console ou outro armazenamento de configuração, como Google Cloud Secret Manager). Nesse caso, o host é a URL do workspace do Databricks, por exemplo, https://1234567890123456.7.gcp.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 os tokens de acesso para autenticação da entidade de serviço OAuth

Databricks As ferramentas e os SDKs que implementam o padrão de autenticação unificada do clienteDatabricks gerarão, refresh e usarão automaticamente Databricks OAuth acessar tokens em seu nome, conforme necessário, para a autenticação da entidade de serviço 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:

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

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.

Como administrador da conta, faça login no console da conta.
Clique na seta para baixo ao lado de seu nome de usuário no canto superior direito.
Copie a ID de sua conta.
Construa a URL do endpoint do token substituindo <my-account-id> na URL a seguir pela ID da conta que você copiou.
```
https://accounts.gcp.databricks.com/oidc/accounts/<my-account-id>/v1/token
```
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.

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

O senhor pode usar os OAuth tokens de acesso para se autenticar em Databricks account-level REST APIs e workspace-level REST APIs. A entidade de serviço deve ter privilégios de administrador account para chamar account-level REST APIs.

Inclua os tokens de acesso no cabeçalho de autorização usando a autenticação Bearer. Você pode usar essa abordagem com curl ou com 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.gcp.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

Entidades de serviço
Visão geral do modelo de identidade do Databricks
Mais informações sobre autenticação e controle de acesso