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
O senhor pode criar uma entidade de serviço diretamente em seu Databricks account ou a partir de um Databricks workspace. entidades de serviço criadas no espaço de trabalho são automaticamente adicionadas ao site account. Se o senhor tiver a federação de identidade ativada em seu espaço de trabalho, o site Databricks recomenda criar a entidade de serviço no site account e atribuí-la ao espaço de trabalho. Se o senhor não tiver a federação de identidade ativada e quiser usar a entidade de serviço no nível workspace, deverá criar sua entidade de serviço a partir de um workspace.
Para adicionar uma entidade de serviço à conta usando o console de contas:
Como administrador da conta, faça login no console da conta.
Clique em Gerenciamento de usuários.
Na guia Entidades de serviço, clique em Adicionar entidade de serviço.
Insira um nome para a entidade de serviço.
Clique em Adicionar.
Ou então, na guia Funções, ative Administrador da conta para chamar APIs em nível de conta do Databricks.
Agora você pode atribuir sua entidade de serviço a espaços de trabalho federados por identidade.
Na barra lateral do console de contas, clique em Workspaces.
Clique no nome do workspace.
Na guia Permissões, clique em Adicionar permissões.
Pesquise e selecione a entidade de serviço, atribua o nível de permissão (Usuário ou Administrador do workspace) e clique em Salvar.
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 2: Atribuir permissões em nível de workspace à entidade de serviço do Databricks
Se o console de administração do seu workspace ainda não estiver aberto, clique no seu nome de usuário na barra superior e clique em Configurações.
Clique na guia Identidade e acesso.
Ao lado de Entidades de serviço, clique em Gerenciar.
Clique no nome da entidade de serviço do Databricks para abrir sua página de configurações.
Na guia Configurações, marque a caixa ao lado de cada direito que você deseja que sua entidade de serviço do Databricks tenha para esse workspace e, em seguida, clique em Atualizar.
Na guia Permissões, conceda acesso a todos os usuários, entidades de serviço e grupos da Databricks que você deseja gerenciar e use essa entidade de serviço do Databricks. Consulte 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.
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.
O segredo só será revelado uma vez durante a criação. A ID do cliente é igual à ID do aplicativo da entidade de serviço.
Se o console de administração do seu workspace ainda não estiver aberto, clique no seu nome de usuário na barra superior e clique em Configurações.
Clique na guia Identidade e acesso.
Ao lado de Entidades de serviço, clique em Gerenciar.
Clique no nome da entidade de serviço do Databricks para abrir sua página de configurações.
Clique na guia Segredos.
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.
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.
Conclua a configuração da autenticação M2M do OAuth
Para concluir a configuração da autenticação OAuth M2M, você deve definir as seguintes variáveis de ambiente associadas, campos .databrickscfg
, campos do Terraform ou campos 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 exemplohttps://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:
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. Defina também a variável de ambientecluster_id
em seu perfil como a URL da instância de seu workspace, como por exemplo,https://dbc-a1b2345c-d6e7.cloud.databricks.com
.Defina as variáveis de ambiente para operações em nível de 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 de seu workspace, como por exemplohttps://dbc-a1b2345c-d6e7.cloud.databricks.com
.
Os valores em seu 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 valores em seu arquivo .databrickscfg
, consulte uma das opções a seguir:
Para o Python, consulte Configurar propriedades de conexão para o Python.
Para o Scala, consulte Configurar propriedades de conexão para o Scala.
Para a extensão do Databricks para Visual Studio Code, faça o seguinte:
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.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://dbc-a1b2345c-d6e7.cloud.databricks.com
, e pressioneEnter
.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:
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
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.
Se você precisar gerar, atualizar ou usar manualmente tokens de acesso do OAuth do Databricks para autenticação OAuth M2M, siga as instruções nesta seção.
Etapa 1: Criar uma entidade de serviço do Databricks e um segredo do OAuth
Se você ainda não tiver uma entidade de serviço do Databricks e seu segredo do OAuth correspondente, crie-os seguindo as Etapas 1 a 3 no início deste artigo.
Etapa 2: Gerar manualmente um token de acesso
Use a ID do cliente e o segredo do OAuth da entidade de serviço do Databricks para solicitar um token de acesso do OAuth para autenticar as APIs REST em nível de conta e as APIs REST em nível de workspace . O token de acesso expirará em uma hora. Você deve solicitar um novo token de acesso do OAuth após a expiração. O escopo do token de acesso do OAuth depende do nível do qual você cria o token. Você pode criar um token em nível de conta ou em nível de workspace, da seguinte maneira:
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.cloud.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 escopoall-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.Pule para a Etapa 3: Chamar uma API REST do Databricks.
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 escopoall-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.
Etapa 3: Chamar uma API REST do 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 adbc-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
Visão geral do modelo de identidade do Databricks
Mais informações sobre autenticação e controle de acesso