Autenticação OAuth máquina a máquina (M2M)

A autenticação OAuth máquina a máquina (M2M) usa as credenciais de uma entidade automatizada (neste caso, uma entidade de serviço do Databricks) para autenticar a entidade de destino. Depois que o Databricks autentica com êxito a entidade de serviço de destino por meio da solicitação de autenticação OAuth M2M, um token OAuth é fornecido à ferramenta participante ou SDK para realizar a autenticação baseada em token a partir desse momento em nome da entidade de serviço. O token OAuth tem vida útil de uma hora, após a qual a ferramenta ou o SDK envolvido fará uma tentativa automática em segundo plano para obter um novo token que também seja válido por uma hora.

Para começar a configurar a autenticação OAuth M2M, faça o seguinte:

Observação

O senhor deve ser um administrador do account para gerenciar as credenciais do OAuth para a entidade de serviço.

passo 1: criar uma entidade de serviço

O senhor pode criar uma entidade de serviço diretamente no site account ou em um site 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, a 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 a entidade de serviço a partir de um workspace.

Para adicionar uma entidade de serviço ao account usando o 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 account Gerenciamento de usuários.

  3. Na guia Entidades de serviço, clique em Adicionar entidade de serviço.

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

  5. Clique em Adicionar.

  6. Opcionalmente, em Roles tab, ative account admin para chamar as APIs de nível accountda Databricks.

Agora o senhor pode atribuir a entidade de serviço ao espaço de trabalho federado por identidade.

  1. Na barra lateral do console account, clique em workspace.

  2. Clique no nome do workspace.

  3. Na guia Permissões , clique em Adicionar permissões.

  4. Pesquise e selecione a entidade de serviço, atribua o nível de permissão ( usuário ou administradordo espaço de trabalho) e clique em Salvar.

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

  2. Clique em seu nome de usuário na barra superior do workspace do Databricks e selecione Administração de configurações.

  3. Clique em Identity and access (Identidade e acesso ) tab.

  4. Ao lado de entidade de serviço, clique em gerenciar.

  5. Clique em Add entidade de serviço.

  6. Clique na seta suspensa na caixa de pesquisa e, em seguida, clique em Add new (Adicionar novo).

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

  8. Clique em Adicionar.

A entidade de serviço é adicionada ao site workspace e ao Databricks account.

o passo 2: Atribuir permissões no nível do espaço de trabalho à entidade de serviço Databricks

  1. 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 Admin Settings.

  2. Clique em Identity and access (Identidade e acesso ) tab.

  3. Ao lado de entidade de serviço, clique em gerenciar.

  4. Clique no nome da entidade de serviço da Databricks para abrir sua página de configurações.

  5. Em Configurations (Configurações ) tab, marque a caixa ao lado de cada direito que você deseja que a entidade de serviço Databricks tenha para este workspace e, em seguida, clique em Update (Atualizar).

  6. Em Permissions (Permissões ) tab, conceda acesso a todos os usuários da Databricks, diretores de serviço e grupos que o senhor deseja gerenciar e usar essa entidade de serviço da Databricks. Consulte gerenciar funções em uma entidade de serviço.

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

Antes de usar o OAuth para se autenticar na Databricks, o senhor deve primeiro criar um segredo do OAuth, que pode ser usado para gerar o token de acesso do OAuth. Uma entidade de serviço pode ter até cinco segredos OAuth. Para criar um segredo OAuth para uma entidade de serviço usando o 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 account Gerenciamento de usuários.

  3. Na entidade de serviço tab, selecione sua entidade de serviço.

  4. Em OAuth secrets, clique em Generate secret (Gerar segredo).

  5. Copie o segredo e o ID do cliente exibidos e clique em Done (Concluído).

    O segredo só será revelado uma vez durante a criação. O ID do cliente é o mesmo que o ID do aplicativo da entidade de serviço.

Observação

Para permitir que a entidade de serviço use clusters ou o SQL warehouse, o senhor deve conceder acesso a eles à entidade de serviço. Consulte as permissões do sitecompute ou gerenciar a SQL warehouse.

Concluir a configuração da autenticação OAuth M2M

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 account ou a URL do espaço de trabalho de destino, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com para operações de espaço de trabalho.

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

  • O ID do cliente principal do serviço.

  • O segredo principal do serviço.

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

Para utilizar a variável de ambiente para um tipo específico de autenticação Databricks com uma ferramenta ou SDK, consulte Tipos de autenticação suportados pela ferramenta ou SDK Databricks ou a documentação da ferramenta ou do SDK. Consulte também variável de ambiente e campos para autenticação unificada do cliente e a ordemdefault de avaliação para métodos e credenciais de autenticação unificada do cliente.

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

  • DATABRICKS_HOST, configure para a URL do console da conta 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 espaço de trabalho do Databricks, 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 campos a seguir em seu arquivo .databrickscfg . Se você criar o perfil, substitua os espaços reservados pelos valores apropriados. Para utilizar o perfil com uma ferramenta ou SDK, consulte Tipos de autenticação suportados pela ferramenta Databricks ou SDK ou a documentação da ferramenta ou do SDK. Consulte também variável de ambiente e campos para autenticação unificada do cliente e a ordemdefault de avaliação para métodos e credenciais de autenticação unificada do cliente.

Para operações no nível da conta, defina os seguintes valores no arquivo .databrickscfg . Nesse caso, a URL do console da conta 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 no nível workspace , defina os valores a seguir no arquivo .databrickscfg. Nesse caso, o host é a URL do espaço de trabalho do Databricks, 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, siga um destes procedimentos:

  • Defina a variável de ambiente conforme especificado na seção “Meio Ambiente” deste artigo.

  • Defina os valores em seu arquivo .databrickscfg conforme especificado na seção “Perfil” deste artigo.

variável de ambiente sempre tem precedência sobre valores em seu arquivo .databrickscfg .

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

Observação

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

  • Para Python, Databricks Connect for Databricks Runtime 13.1 e acima.

  • Para Scala, Databricks Connect for Databricks Runtime 13.3 LTS e acima.

Para o Databricks Connect, você pode fazer o seguinte:

  • Defina os valores em seu arquivo .databrickscfg para operações no nível workspacedo Databricks conforme especificado na seção “Perfil” deste artigo. Configure também a variável de ambiente cluster_id em seu perfil para o URL da instância do espaço de trabalho, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com.

  • Defina a variável de ambiente para operações em nível de workspacedo Databricks conforme especificado na seção “Ambiente” deste artigo. Configure também a variável de ambiente DATABRICKS_CLUSTER_ID para o URL da instância do seu espaço de trabalho, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com.

Os valores no seu arquivo .databrickscfg sempre têm precedência sobre a variável de ambiente.

Para inicializar o cliente Databricks Connect com essas variáveis de ambiente ou valores em seu arquivo .databrickscfg , consulte um dos seguintes:

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

  1. Defina os valores em seu arquivo .databrickscfg para operações no nível workspacedo Databricks conforme especificado na seção “Perfil” deste artigo.

  2. No painel Configuração da extensão Databricks para Visual Studio Code, clique em Configurar Databricks.

  3. No comando Palette, para Databricks Host, insira a URL do seu espaço de trabalho, por exemplo https://dbc-a1b2345c-d6e7.cloud.databricks.com e pressione Enter.

  4. Na paleta de comando, selecione o nome do seu perfil de destino na lista do seu URL.

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

Para operações em nível de account , para autenticaçãodefault :

provider "databricks" {
  alias = "accounts"
}

Para configuração direta (substitua os placeholders 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 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 no nível workspace , para autenticaçãodefault :

provider "databricks" {
  alias = "workspace"
}

Para configuração direta (substitua os espaços reservados retrieve por sua própria implementação para recuperar os valores do console ou de algum outro armazenamento de configuração, como HashiCorp Vault. Consulte também Provedor do Vault). Nesse caso, o host é a URL do espaço de trabalho do Databricks, 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 a autenticação com o fornecedor Databricks Terraform, consulte Autenticação.

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

from databricks.sdk import AccountClient

a = AccountClient()
# ...

Para configuração direta, use o seguinte, substituindo os espaços reservados retrieve por sua própria implementação para recuperar os valores do console ou de algum outro armazenamento de configuração, como o AWS Systems Manager Parameter Store. Nesse caso, o URL do console da Databricks account é 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 de nível workspace, especificamente a autenticaçãodefault:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
# ...

Para configuração direta, substitua os espaços reservados retrieve por sua própria implementação para recuperar os valores do console ou de algum outro armazenamento de configuração, como o AWS Systems Manager Parameter Store. Nesse caso, o host é o URL do espaço de trabalho do Databricks, 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 a autenticação com ferramentas e SDKs do Databricks que usam Python e que implementam a autenticação unificada do cliente do Databricks, consulte:

Para operações em nível de account , para autenticaçãodefault :

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

Para configuração direta (substitua os placeholders do retrieve por sua própria implementação para recuperar os valores do console ou algum outro armazenamento de configuração, como AWS Systems Manager Parameter Store). Nesse caso, a URL do console da conta 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 no nível workspace , para autenticaçãodefault :

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

Para configuração direta (substitua os espaços reservados retrieve por sua própria implementação para recuperar os valores do console ou de algum outro armazenamento de configuração, como AWS Systems Manager Parameter Store). Nesse caso, o host é a URL do espaço de trabalho do Databricks, 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 a autenticação com ferramentas e SDKs do Databricks que usam Java e implementam a autenticação unificada do cliente do Databricks, consulte:

Para operações em nível de account , para autenticaçãodefault :

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

Para configuração direta (substitua os placeholders do retrieve por sua própria implementação para recuperar os valores do console ou algum outro armazenamento de configuração, como AWS Systems Manager Parameter Store). Nesse caso, a URL do console da conta 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 no nível workspace , para autenticaçãodefault :

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

Para configuração direta (substitua os espaços reservados retrieve por sua própria implementação para recuperar os valores do console ou de algum outro armazenamento de configuração, como AWS Systems Manager Parameter Store). Nesse caso, o host é a URL do espaço de trabalho do Databricks, 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 obter mais informações sobre a autenticação com ferramentas e SDKs do Databricks que usam Go e que implementam a autenticação unificada do cliente Databricks, consulte Autenticar o SDK do Databricks para Go com sua account ou workspacedo Databricks.

Gerar e usar manualmente o token de acesso para autenticação OAuth máquina a máquina (M2M)

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

Se, por algum motivo, for necessário gerar manualmente, refresh, ou usar o token de acesso OAuth da Databricks para autenticação OAuth M2M, siga as instruções desta seção.

o passo 1: Criar uma entidade de serviço Databricks e um segredo OAuth

Se o senhor ainda não tiver uma entidade de serviço Databricks e seu segredo OAuth correspondente, crie-os seguindo os passos 1-3 no início deste artigo.

o passo 2: Gerar manualmente um access token

O senhor pode usar o ID do cliente e o segredo do OAuth da entidade de serviço da Databricks para solicitar um OAuth access token para autenticação nas APIs REST de nível accounte nas APIs REST de nível workspace. 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, como segue:

Gerar manualmente um nível de conta access token

Um OAuth access token criado no nível account pode ser usado nas APIs REST da Databricks em account e em qualquer espaço de trabalho ao qual 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 do seu nome de usuário no canto superior direito.

  3. Copie sua IDaccount .

  4. Construa o URL do endpoint de tokens substituindo <my-account-id> no URL a seguir pelo ID account que o senhor copiou.

    https://accounts.cloud.databricks.com/oidc/accounts/<my-account-id>/v1/token
    
  5. Use um cliente como curl para solicitar um OAuth access token com o URL do endpoint dos tokens, o ID do cliente da entidade de serviço (também conhecido como ID do aplicativo) e o segredo OAuth da entidade de serviço que o senhor criou. O escopo all-apis solicita um OAuth access token que pode ser usado para acessar todas as APIs REST da Databricks às quais a entidade de serviço recebeu acesso.

    • Substitua <token-endpoint-URL> pelos tokens anteriores endpoint URL.

    • Substitua <client-id> pelo ID do cliente da entidade de serviço, que também é conhecido como ID do aplicativo.

    • Substitua <client-secret> pelo segredo OAuth da entidade de serviço que o senhor criou.

    export CLIENT_ID=<client-id>
    export CLIENT_SECRET=<client-secret>
    
    curl --request POST \
    --url <token-endpoint-URL> \
    --user "$CLIENT_ID:$CLIENT_SECRET" \
    --data 'grant_type=client_credentials&scope=all-apis'
    

    Isso gera uma resposta semelhante a:

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

    Copie o access_token da resposta.

    O access token expirará em uma hora. O senhor deve gerar manualmente um novo OAuth access token após a expiração.

  6. Avance para o passo 3: Chamar uma API REST da Databricks.

Gerar manualmente um nível de espaço de trabalho access token

Um OAuth access token criado a partir do nível workspace só pode acessar APIs REST nesse workspace, mesmo que a entidade de serviço seja um administrador do account ou seja membro de outro espaço de trabalho.

  1. Construa o URL do endpoint de tokens substituindo https://<databricks-instance> pelo URL do workspace de sua implantação do Databricks:

    https://<databricks-instance>/oidc/v1/token
    
  2. Use um cliente como curl para solicitar um OAuth access token com o URL do endpoint dos tokens, o ID do cliente da entidade de serviço (também conhecido como ID do aplicativo) e o segredo OAuth da entidade de serviço que o senhor criou. O escopo all-apis solicita um OAuth access token que pode ser usado para acessar todas as APIs REST da Databricks às quais a entidade de serviço recebeu acesso dentro do workspace do qual o senhor está solicitando os tokens.

    • Substitua <token-endpoint-URL> pelos tokens anteriores endpoint URL.

    • Substitua <client-id> pelo ID do cliente da entidade de serviço, que também é conhecido como ID do aplicativo.

    • Substitua <client-secret> pelo segredo OAuth da entidade de serviço que o senhor criou.

    export CLIENT_ID=<client-id>
    export CLIENT_SECRET=<client-secret>
    
    curl --request POST \
    --url <token-endpoint-URL> \
    --user "$CLIENT_ID:$CLIENT_SECRET" \
    --data 'grant_type=client_credentials&scope=all-apis'
    

    Isso gera uma resposta semelhante a:

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

    Copie o access_token da resposta.

    O access token expirará em uma hora. O senhor deve gerar manualmente um novo OAuth access token após a expiração.

o passo 3: Chamar uma API REST da Databricks

Agora, o senhor pode usar o OAuth access token para autenticar as APIs REST de nível accounte as APIs REST de nível workspaceda Databricks. A entidade de serviço deve ser um administrador do account para chamar as APIs REST de nível account.

O senhor pode incluir os tokens no cabeçalho usando a autenticação Bearer. O senhor pode usar essa abordagem com curl ou com qualquer cliente que construir.

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

Este exemplo usa a autenticação Bearer para obter uma lista de todos os espaços de trabalho associados a um account.

  • Substitua <oauth-access-token> pelo OAuth access token da entidade de serviço que o senhor copiou no passo anterior.

  • Substitua <account-id> por sua ID account.

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 no nível do espaço de trabalho

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

  • Substitua <oauth-access-token> pelo OAuth access token da entidade de serviço que o senhor copiou no passo anterior.

  • Substitua <workspace-URL> pelo URL do workspace de base, que tem a forma 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'