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

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.

Etapa 1: Atribuir permissões à 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 todos os Databricks usuários, entidades de serviço e grupos que o senhor deseja gerenciar e usar essa entidade de serviço. Veja como gerenciar funções em uma entidade de serviço.

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

   

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

   

5. Copie o Segredo e a ID do cliente exibidos e clique em Concluído .

nota

Para permitir que a entidade de serviço use o armazenamento em cluster ou SQL, o senhor deve conceder à entidade de serviço acesso a eles. Consulte computar permissões ou gerenciar SQL warehouse a.

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 Databricks host, especificado como https://accounts.cloud.databricks.com para account operações ou o workspace URL de destino, por exemplo,https://dbc-a1b2345c-d6e7.cloud.databricks.com para workspace operações.
• 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:

Environment

To use environment variables for a specific Databricks authentication type with a tool or SDK, see Authorizing access to Databricks resources or the tool’s or SDK’s documentation. See also Environment variables and fields for client unified authentication and the Default methods for client unified authentication.

For account-level operations, set the following environment variables:

• DATABRICKS_HOST, set to the Databricks account console URL, https://accounts.cloud.databricks.com.
• DATABRICKS_ACCOUNT_ID
• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET

For workspace-level operations, set the following environment variables:

• DATABRICKS_HOST, set to the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com.
• DATABRICKS_CLIENT_ID
• DATABRICKS_CLIENT_SECRET

Profile

Create or identify a Databricks configuration profile with the following fields in your .databrickscfg file. If you create the profile, replace the placeholders with the appropriate values. To use the profile with a tool or SDK, see Authorizing access to Databricks resources or the tool’s or SDK’s documentation. See also Environment variables and fields for client unified authentication and the Default methods for client unified authentication.

For account-level operations, set the following values in your .databrickscfg file. In this case, the Databricks account console URL is 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>

For workspace-level operations, set the following values in your .databrickscfg file. In this case, the host is the Databricks workspace URL, for example 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>

CLI

For the Databricks CLI, do one of the following:

• Set the environment variables as specified in this article’s “Environment” section.
• Set the values in your .databrickscfg file as specified in this article’s “Profile” section.

Environment variables always take precedence over values in your .databrickscfg file.

See also OAuth machine-to-machine (M2M) authentication.

Connect

nota

OAuth service principal authentication is supported on the following Databricks Connect versions:

• For Python, Databricks Connect for Databricks Runtime 13.1 and above.

• For Scala, Databricks Connect for Databricks Runtime 13.3 LTS and above.

For Databricks Connect, you can do one of the following:

• Set the values in your .databrickscfg file for Databricks workspace-level operations as specified in this article’s “Profile” section. Also set the cluster_id environment variable in your profile to your workspace instance URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com.
• Set the environment variables for Databricks workspace-level operations as specified in this article’s “Environment” section. Also set the DATABRICKS_CLUSTER_ID environment variable to your workspace instance URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com.

Values in your .databrickscfg file always take precedence over environment variables.

To initialize the Databricks Connect client with these environment variables or values in your .databrickscfg file, see Compute configuration for Databricks Connect.

VS Code

For the Databricks extension for Visual Studio Code, do the following:

1. Set the values in your .databrickscfg file for Databricks workspace-level operations as specified in this article’s “Profile” section.
2. In the Configuration pane of the Databricks extension for Visual Studio Code, click Configure Databricks.
3. In the Command Palette, for Databricks Host, enter your workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com, and then press Enter.
4. In the Command Palette, select your target profile’s name in the list for your URL.

For more details, see Set up authorization for the Databricks extension for Visual Studio Code.

Terraform

For account-level operations, for default authentication:

provider "databricks" {
  alias = "accounts"
}

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console or some other configuration store, such as HashiCorp Vault. See also Vault Provider). In this case, the Databricks account console URL is 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>
}

For workspace-level operations, for default authentication:

provider "databricks" {
  alias = "workspace"
}

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console or some other configuration store, such as HashiCorp Vault. See also Vault Provider). In this case, the host is the Databricks workspace URL, for example 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>
}

For more information about authenticating with the Databricks Terraform provider, see Authentication.

Python

For account-level operations, use the following for default authentication:

Python

from databricks.sdk import AccountClient

a = AccountClient()
# ...

For direct configuration, use the following, replacing the retrieve placeholders with your own implementation, to retrieve the values from the console or other configuration store, such as AWS Systems Manager Parameter Store. In this case, the Databricks account console URL is https://accounts.cloud.databricks.com:

Python

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()
)
# ...

For workspace-level operations, specifically default authentication:

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

For direct configuration, replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store. In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient(
  host          = retrieve_workspace_url(),
  client_id     = retrieve_client_id(),
  client_secret = retrieve_client_secret()
)
# ...

For more information about authenticating with Databricks tools and SDKs that use Python and that implement Databricks client unified authentication, see:

• Set up the Databricks Connect client for Python
• Set up authorization for the Databricks extension for Visual Studio Code
• Authenticate the Databricks SDK for Python with your Databricks account or workspace

Java

For account-level operations, for default authentication:

Java

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the Databricks account console URL is https://accounts.cloud.databricks.com:

Java

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);
// ...

For workspace-level operations using default authentication:

Java

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

Java

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);
// ...

For more information about authenticating with Databricks tools and SDKs that use Java and implement Databricks client unified authentication, see:

• Set up the Databricks Connect client for Scala (the Databricks Connect client for Scala uses the included Databricks SDK for Java for authentication)
• Authenticate the Databricks SDK for Java with your Databricks account or workspace

Go

For account-level operations using default authentication:

Go

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the Databricks account console URL is https://accounts.cloud.databricks.com:

Go

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

For workspace-level operations using default authentication:

Go

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

For direct configuration (replace the retrieve placeholders with your own implementation to retrieve the values from the console, or other configuration store, such as AWS Systems Manager Parameter Store). In this case, the host is the Databricks workspace URL, for example https://dbc-a1b2345c-d6e7.cloud.databricks.com:

Go

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

For more information about authenticating with Databricks tools and SDKs that use Go and that implement Databricks client unified authentication, see Authenticate the Databricks SDK for Go with your Databricks account or workspace.

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 de cliente; no entanto, se for necessário gerar manualmente, refresh, ou usar Databricks OAuth acessar 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 token de acesso OAuth para autenticar tanto o account-level REST APIs quanto o workspace-level REST APIs. Os tokens de acesso expirarão em uma hora. O senhor deve solicitar um novo OAuth access tokens após a expiração. O escopo dos tokens de acesso OAuth 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 account-level e workspace-level REST APIs dentro da conta e do espaço de trabalho aos quais a entidade de serviço tem acesso, gere manualmente um token de acesso no nível account.
• Para chamar REST APIs em apenas um dos espaços de trabalho aos quais a entidade de serviço tem acesso, gere manualmente um token de acesso no nível workspace apenas para esse workspace.

Gerar manualmente tokens de acesso no nível account

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

   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:

   JSON

   {
     "access_token": "eyJraWQiOiJkYTA4ZTVjZ…",
     "token_type": "Bearer",
     "expires_in": 3600
   }

   Copie access_token da resposta.

Gerar manualmente um workspace-level access tokens

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 o URL de tokens endpoint substituindo https://<databricks-instance> pelo URLworkspace de sua implantação 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.
   Bash

   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:

   JSON

   {
     "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 account-level REST API request

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.

Bash

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 workspace-level REST API request

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.

Bash

export OAUTH_TOKEN=<oauth-access-token>

curl --request GET --header "Authorization: Bearer $OAUTH_TOKEN" \
'https://<workspace-URL>/api/2.0/clusters/list'

Recurso adicional

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