Autenticação com tokens de ID do Google

Para autenticar nas APIs REST do Databricks, você tem duas opções:

Databricks pessoal access token. O senhor pode usá-las somente para APIs REST no nível do espaço de trabalho.
tokens OpenID Connect (OIDC). Você pode usá-los para todas as APIs REST do Databricks.

Os tokens OpenID Connect (OIDC) são um padrão aberto para oferecer suporte à autenticação. OIDC 1.0 é uma camada de identidade simples sobre o protocolo OAuth 2.0. Ele permite que os aplicativos verifiquem a identidade dos usuários com base na autenticação executada por um servidor de autorização OAuth. Os aplicativos também podem obter informações básicas de perfil de usuários a partir de tokens OIDC. Os tokens OIDC, por default , expiram após uma hora.

Importante

As APIs REST do Databricks suportam apenas os tokens OIDC emitidos pelo Google, que são comumente conhecidos como tokens de ID do Google. Para reduzir a confusão, o restante deste artigo usa o termo tokensde ID do Google e não tokensOIDC.

Este artigo descreve os passos para autenticação para usar APIs REST do Databricks e como criar a clouds serviço de do Google necessária account e gerar tokens para essas account.

Um único token de ID do Google pode ser usado para account-level APIs ou workspace-level APIs, mas não pode ser usado para ambas as finalidades. Os passos para configurar o site tokens para workspace-level e account-level APIs são praticamente os mesmos. As diferenças importantes são mencionadas nas instruções.

Para um ambiente de produção, a Databricks recomenda que utilize duas account de serviço para trabalhar com APIs REST da Databricks.

Crie uma account de serviço (SA-1) para executar suas cargas de trabalho.
Crie outra account de serviço (SA-2) para manter permissões para seu recurso Databricks e Google clouds .
Conceda permissão ao SA-1 para representar o SA-2 para chamar APIs REST do Databricks.

Com esse modelo de representação, uma equipe pode gerenciar a segurança da carga de trabalho e outra equipe pode gerenciar a segurança dos recursos. Como você concede permissões de representação apenas conforme necessário, essa abordagem oferece segurança e flexibilidade à sua organização.

Este artigo descreve detalhadamente como executar esses passos para uso em produção. Você pode adaptar estas instruções para uso e teste não relacionados à produção usando uma das seguintes estratégias:

Use sua accountde usuário do Google para se passar por SA-2. A account do usuário deve ter a função roles/iam.serviceAccountTokenCreator.
Use uma de serviço de do Google clouds account para SA-1 e SA-2.

APIs no nível da conta e APIs no nível do espaço de trabalho

Para compreender a autenticação para utilizar APIs REST do Databricks, deve compreender os tipos de APIs REST e a sua relação com a hierarquia de recursos do Databricks.

Você pode ter uma ou mais account do Databricks. Uma account do Databricks contém zero, um ou mais workspace do Databricks. Você pode usar o console account para criar workspace e gerenciar recursos clouds necessários para configurar um workspace (como credenciais, armazenamento e redes).

O SITE Databricks workspace tem uma variedade de recursos, como Job e Notebook. Um administrador do workspace, às vezes chamado apenas de administrador, pode modificar as configurações definidas no nível do workspace, inclusive as configurações da página de configurações do administrador.

Devido a essa diferença, existem dois tipos de APIs:

Databricks accountO nível APIs só pode ser chamado pelos proprietários de account e administradores de account. Esses APIs estão hospedados no URLhttps://accounts.gcp.databricks.com do console account .
Databricks workspaceO nível APIs só pode ser chamado por administradores do workspace e usuários do workspace. Esses APIs são hospedados nos URLs workspace, comohttps://1234567890123456.7.gcp.databricks.com.

Para autenticar uma API REST do Databricks, você precisa passar tokens de ID do Google com um público (aud) que corresponda à URL base da API, que é diferente entre esses dois tipos de APIs. Para chamar APIs REST do Databricks com URLs base diferentes, você deve usar tokens de ID do Google diferentes.

Passagem de credenciais

Alguns métodos da API REST do Databricks exigem passagem de credenciais. Para chamar esses métodos, além do ID do Google, você também deve passar um access tokenGoogle OAuth com escopo cloud-platform em um cabeçalho HTTP. O servidor Databricks usa o access token Google OAuth para chamar APIs clouds do Google em nome do chamador.

O Databricks não valida nem preserva o access token.

Importante

Para determinar se a passagem de credenciais é necessária para uma operação, consulte a documentação da API para cada operação da API. Essas APIs exigem o cabeçalho HTTP X-Databricks-GCP-SA-Access-Token na solicitação.

o passo 1: Crie duas accountde serviço

Crie duas novas de clouds serviço do account Google. Siga as instruções nos artigos do Google Criando uma accountde serviço. Para usar o Console do Google clouds , acesse a página accountde serviço e escolha um projeto do Google clouds para criá-lo. O projeto clouds do Google no qual você cria essas account de serviço não precisa corresponder ao projeto que você usa para workspace do Databricks, nem a nova account de serviço precisa usar o mesmo projeto clouds do Google.
- account de serviço de criação de token (SA-1): esta account de serviço automatiza a criação de tokens para a account de serviço principal. Esses tokens serão usados para chamar APIs REST do Databricks. A documentação do Google chama isso de SA-1.
- account de serviço principal para APIs REST do Databricks (SA-2): esta account de serviço atua como principal (o usuário de automação) para APIs REST do Databricks e fluxo de trabalho automatizado. A documentação do Google chama isso de SA-2.
Salve o endereço email de ambas account de serviço para usar nos passos posteriores.
Crie uma keyde conta de serviço para sua conta de serviço de criação de tokens (SA-1) e salve-a em um arquivo local chamado SA-1-key.json.
1. Na página da conta do Google clouds Console account , clique no endereço email do SA-1.
2. Clique na key tab.
3. Clique em ADICIONAR key.
4. Certifique-se de que JSON (o default) esteja selecionado.
5. Clique em Criar.
6. A página da web downloads um arquivo key para o seu navegador. Mova esse arquivo para seu diretório de trabalho local e renomeie-o como SA-1-key.json.
Para obter instruções adicionais, consulte os artigos do Google Criando keyde conta de serviço.
Conceda à sua de serviço de criação (SA-1) a função de criador de serviço em sua de serviço principal (SA-2).tokens account account tokens account Siga as instruções nos artigos do Google Solicitar permissões diretas.
1. Na página da conta do Google clouds Console account , clique no endereço email do SA-2.
Importante

No Google clouds Console, certifique-se de editar seu SA principal (SA-2), não seu SA de criação de tokens (SA-1):
1. Clique em PERMISSÕES.
2. Clique em Conceder acesso.
3. No campo Novos Diretores , cole o endereço email dos seus tokens-criando SA (SA-1).
4. No campo Função , escolha Função do criador de serviço account tokens .
5. Clique em Salvar.

o passo 2: Crie um tokensde ID do Google

A Databricks recomenda usar a CLI do Google clouds (gcloud) para gerar tokens de ID para chamar APIs REST do Databricks.

Importante

Os tokens de ID gerados expiram em uma hora. Você deve terminar todos os passos restantes dentro desse tempo. Se os tokens expirarem antes de você concluir as etapas posteriores, como chamar APIs do Databricks, você deverá repetir esta etapa para gerar um novo tokens de ID do Google.

Instale a CLI do Google clouds em sua máquina. Consulte os artigos do Google sobre como instalar a ferramenta gcloud.
Gere tokens de ID para sua account de serviço principal executando o comando a seguir.
- Substitua <SA-1-key-json> pelo caminho do arquivo key SA-1 no formato JSON.
- Substitua <SA-2-email> pelo endereço email do SA-2.
- Substitua <audience> da seguinte maneira com base no seu caso de uso:
  - Para APIs no nível do espaço de trabalho, substitua pelo URL do seu espaço de trabalho, que tem o formato https://<numbers>.<digit>.gcp.databricks.com, por exemplo https://999999999992360.0.gcp.databricks.com. Cada workspace tem um URL workspace exclusivo e diferente. Para chamar APIs em vários workspace, você precisa criar vários tokens de ID do Google, cada um com valores audience diferentes.
  - Para API no nível account, substitua por https://accounts.gcp.databricks.com. Todas account diferentes compartilham o mesmo valor audience.
execute o seguinte comando para uso com sistemas de produção:
```
gcloud auth login --cred-file=<SA-1-key-json>

gcloud auth print-identity-token --impersonate-service-account="<SA-2-email-address>" --include-email --audiences="<audience>"
```
Para uso não relacionado à produção, se você usar sua account de usuário para representar o SA-2, use estes comandos:
```
gcloud auth login

gcloud auth print-identity-token --impersonate-service-account=<SA-2-email-address> --audiences="<audience>" --include-email
```
Para uso fora da produção, se você usar uma de serviço account para SA-1 e SA-2, use estes comandos com o account key arquivo JSON da de serviço:
```
gcloud auth login --cred-file=<SA-key-json>

gcloud auth print-identity-token --audiences="<audience>"
```

Salve a linha longa no final da saída em um arquivo chamado google-id-token-sa-2.txt.

Ele gera um texto semelhante ao seguinte:

WARNING: This command is using service account impersonation. All API calls will be executed as [<SA-2-email-address>].

eyJhba7s86dfa9s8f6a99das7fa68s7d6...N8s67f6saa78sa8s7dfiLlA

o passo 3: Crie um access token Google OAuth (somente para APIs que exigem passagem de credenciais)

.. nota:: Este passo é necessário apenas para chamar APIs que requerem passagem de credenciais. Para determinar se a passagem de credenciais é necessária para uma operação, consulte a documentação da API para cada operação da API.

A solicitação para gerar um access token inclui um campo lifetime que define por quanto tempo o access token é válido. Se você precisar que os tokens fiquem ativos apenas por cinco minutos, defina como 300s (300 segundos). O exemplo a seguir usa 3600s, que representa uma hora.

Importante

Você deve terminar todos os passos restantes dentro desse prazo. Se o tempo expirar antes de você concluir as etapas posteriores, como chamar APIs do Databricks, você deverá repetir esta etapa para gerar um novo access token OAuth do Google.
Por default, uma hora (3600s) é a duração máxima que você pode definir para o campo lifetime. Para estender esse limite, entre em contato com o suporte ao cliente do Google e solicite uma exceção.

execute o seguinte comando. Substitua <SA-2-email-address> pelo endereço de serviço account email do SA-2. Para uso ou teste que não seja de produção, se você estiver usando uma única account de serviço ou uma account de usuário para representar uma account de serviço , substitua <SA-2-email-address> pelo endereço email da account de serviço .
```
gcloud auth print-access-token --impersonate-service-account=<SA-2-email-address>
```

Salve a linha longa no final da saída em um arquivo chamado access-token-sa-2.txt.

Ele gera um texto semelhante ao seguinte:

WARNING: This command is using service account impersonation. All API calls will be executed as [<SA-2-email-address>].

eyJhba7s86dfa9s8f6a99das7fa68s7d6...N8s67f6saa78sa8s7dfiLlA

o passo 4: Adicione a conta de serviço como um espaço de trabalho ou usuário da conta

Você pode usar tokens de ID do Google para chamar APIs no nível da conta do Databricks ou APIs no nível do espaço de trabalho. As instruções são diferentes dependendo do caso de uso. Observe que você não pode usar um tokens de ID do Google para acessar os dois tipos de APIs devido à diferença no campo audience ao criar os tokensde ID do Google.

APIs do espaço de trabalho

Para autenticar APIs do workspace com os tokens de ID do Google, use a página de configurações do administrador do workspace para adicionar sua account de serviço principal (SA-2) como se fosse um endereço email do usuário.

Como administrador do workspace, acesse a página de configurações do administrador.
Siga as instruções em gerenciar usuários em seu workspace e use account email o endereço do seu serviço principal quando for solicitado a fornecê-lo na página de configurações do administrador.
Opcionalmente, adicione quaisquer associações de grupo que possam ser necessárias para o seu novo serviço account com base em qual Databricks REST APIs o senhor planeja chamar e os objetos de dados que deseja usar. Ver grupos de gerenciar.
Opcionalmente, adicione as configurações de controle de acesso do Databricks para esse usuário. Consulte Listas de controle de acesso.

APIs no nível da conta

Para autenticar APIs no nível account (como a API account ) com os tokens de ID do Google , use o console da account para adicionar sua account de serviço principal (SA-2) como administrador account . Adicione a account de serviço usando seu endereço email , como faria para adicionar um usuário.

Como proprietário ou administrador account account acesse a tab Usuários no console account .
Clique em Adicionar usuário.

Observação

Não clique em Add entidade de serviço. O senhor não pode usar um serviço account para criar uma Databricks entidade de serviço.
No campo de endereço , insira email o account email endereço da sua de serviço principal (SA-2).
Defina os campos obrigatórios para nome e sobrenome de uma forma que reflita a finalidade da account de serviço.
Clique em Adicionar usuário.

o passo 5: Chame uma API do Databricks

Os tokens que você precisa fornecer durante a autenticação da API REST variam de acordo com o uso planejado: API de conta ou APIs no nível do espaço de trabalho. Observe que você não pode usar um tokens de ID do Google para acessar os dois tipos de APIs devido à diferença no campo audiences ao criar os tokensde ID do Google.

Os cabeçalhos HTTP a seguir são usados para autenticação do Databricks com IDs do Google.

Nome do cabeçalho HTTP	Descrição	Quais tipos de APIs exigem isso?
`Authorization`	tokens de ID do Google para SA-2 como tokens ao portador. A sintaxe é `Authentication: Bearer <token>`.	Todas as APIs
`X-Databricks-GCP-SA-Access-Token`	access token Google OAuth para SA-2.	somente APIs no nível account

Exemplo de solicitação de API no nível do espaço de trabalho

Para chamar uma API REST do Databricks para um workspace, transmita tokens de ID do Google no cabeçalho HTTP Authorization com a seguinte sintaxe:

Authorization: Bearer <google-id-token>

Os tokens fornecidos devem ter os seguintes atributos:

A workspace que você acessa deve corresponder à URL workspace fornecida ao criar os tokens. Veja o passo 2: Crie um tokensde ID do Google.
A account de serviço representada (SA-2) deve ser um usuário do workspace. Consulte APIs do espaço de trabalho.

O exemplo a seguir chama uma API no nível do espaço de trabalho para listar os clusters.

Substitua <google-id-token> pelos tokens de ID do Google que você salvou no arquivo google-id-token-sa-2.txt.
Substitua <workspace-URL> pelo URL base do seu workspace , que tem o formato semelhante a https://1234567890123456.7.gcp.databricks.com.

curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  <workspace-URL>/api/2.0/clusters/list

Exemplo de solicitação de API no nível da conta para uma API que não usa passagem de credenciais

O exemplo a seguir chama a API da account para obter uma lista de workspace.

Substitua <google-id-token> pelos tokens de ID do Google que você salvou no arquivo google-id-token-sa-2.txt.
Substitua <account-id> pelo ID da sua account . Para encontrar o ID da sua account :
1. Como administrador account , acesse o console account do Databricks.
2. Clique na seta para baixo ao lado do seu nome de usuário no canto superior direito.
3. No menu dropdown você pode copiar o ID da suaaccount .

curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  https://accounts.gcp.databricks.com/api/2.0/example/<account-id>/operation-name

Exemplo de solicitação de API no nível da conta com passagem de credenciais

O exemplo a seguir chama a API da account para obter uma lista de workspace.

Substitua <google-id-token> pelos tokens de ID do Google que você salvou no arquivo google-id-token-sa-2.txt.
Substitua <access-token-sa-2> pelo access token SA-2 que você salvou no arquivo access-token-sa-2.txt.
Substitua <account-id> pelo ID da sua account . Para encontrar o ID da sua account :
1. Como administrador account , acesse o console account do Databricks.
2. Na parte inferior do menu esquerdo (talvez seja necessário rolar), clique no botão Usuário (o ícone da pessoa).
3. No pop-up que aparece, copie o ID account clicando no ícone à direita do ID.

curl \
  -X DELETE \
  --header 'Authorization: Bearer <google-id-token>' \
  --header 'X-Databricks-GCP-SA-Access-Token: <access-token-sa-2>' \
  https://accounts.gcp.databricks.com/api/2.0/accounts/<account-id>/workspaces/<workspace-id>