Pular para o conteúdo principal

Autenticação com tokens de ID do Google

Para se autenticar nas APIs REST da Databricks, o senhor tem duas opções:

Os tokens OpenID Connect (OIDC) são um padrão aberto para dar suporte à autenticação. 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 realizada por um servidor de autorização OAuth. Os aplicativos também podem obter informações básicas sobre o perfil dos usuários do OIDC tokens. OIDC tokens por default expira após uma hora.

important

As APIs REST da 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 tokens de ID do Google e não tokens OIDC .

Este artigo descreve as etapas de autenticação para usar Databricks REST APIs e como criar a conta de serviço do Google Cloud necessária e gerar tokens para essa conta.

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. As etapas para configurar tokens para workspace-level e account-level APIs são praticamente as mesmas. As diferenças importantes são apresentadas nas instruções.

Em um ambiente de produção, o site Databricks recomenda que o senhor use duas contas de serviço para trabalhar com Databricks REST APIs.

  • Crie um serviço account (SA-1) para executar suas cargas de trabalho.
  • Crie outro serviço account (SA-2) para manter as permissões do seu recurso Databricks e do Google Cloud.
  • Conceder permissão ao SA-1 para se passar por SA-2 para chamar as APIs REST da Databricks.

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

Este artigo descreve em detalhes como executar essas etapas para uso na produção. Você pode adaptar essas instruções para uso e teste fora da produção usando uma das seguintes estratégias:

  • Use seu usuário do Google account para se passar por SA-2. O usuário account deve ter a função roles/iam.serviceAccountTokenCreator.
  • Use um serviço do Google Cloud account para o SA-1 e o SA-2.

nível de conta APIs e workspace-level APIs​

Para entender a autenticação para usar Databricks REST APIs, o senhor deve entender os tipos de REST APIs e sua relação com a hierarquia de recursos Databricks.

O Databricks senhor pode ter uma ou mais contas. Um Databricks account contém zero, um ou mais espaços de trabalho Databricks. É possível usar o console account para criar um espaço de trabalho e gerenciar os recursos de nuvem 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, há 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 se autenticar em um Databricks REST API, o senhor precisa passar um token de ID do Google com um público (aud) que corresponda ao URL de base do API, que é diferente entre esses dois tipos de APIs. Para chamar as APIs REST da Databricks com URLs de base diferentes, o senhor deve usar tokens de ID do Google diferentes.

Passagem de credenciais​

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

Databricks não valida nem preserva os tokens de acesso.

important

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

Etapa 1: Criar duas contas de serviço​

  1. Crie duas novas contas de serviço do Google Cloud. Siga as instruções nos artigos do Google Criando um serviço account. Para usar o Google Cloud Console, acesse a página da conta do serviço e escolha um projeto do Google Cloud para criá-lo. O projeto do Google Cloud no qual o senhor cria essa conta de serviço não precisa corresponder ao projeto que o senhor usa para Databricks workspace, nem a nova conta de serviço precisa usar o mesmo projeto do Google Cloud.

    • serviço de criação de tokens account (SA-1) : Esse serviço account automatiza a criação de tokens para o serviço principal account. Esses tokens serão usados para chamar as APIs REST da Databricks. A documentação do Google chama isso de SA-1 .
    • Serviço principal account para Databricks REST APIs (SA-2) : Esse serviço account atua como principal (o usuário de automação) para Databricks REST APIs e fluxo de trabalho automatizado. A documentação do Google chama isso de SA-2 .

    Salve o endereço email de ambas as contas de serviço para uso em etapas posteriores.

  2. Crie um serviço account keypara seu serviço de criação de tokens account (SA-1) e salve-o em um arquivo local chamado SA-1-key.json.

    1. Na página da conta de serviço do Google Cloud Console, clique no endereço email do SA-1.
    2. Clique na tecla tab.
    3. Clique em ADD 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 seu navegador. Mova esse arquivo para seu diretório de trabalho local e renomeie-o para SA-1-key.json.

    Para obter instruções adicionais, consulte os artigos do Google Criando serviço account key.

  3. Conceda ao seu serviço de criação de tokens account (SA-1) a função de criador de tokens de conta de serviço em seu serviço principal account (SA-2). Siga as instruções no artigo do Google Direct para solicitar permissões.

    1. Na página da conta de serviço do Google Cloud Console, clique no endereço email do SA-2.
important

No Google Cloud Console, certifique-se de editar sua SA principal (SA-2), não sua SA de criação de tokens (SA-1):

  1. Clique em PERMISSÕES .
  2. Clique em Conceder acesso .
  3. No campo New Principals , cole o endereço email do SA (SA-1) que está criando tokens.
  4. No campo Role (Função ), escolha serviço account tokens Creator Role (Função de criador de tokens de conta de serviço ).
  5. Clique em SALVAR .

Etapa 2: Criar tokens de ID do Google​

A Databricks recomenda usar o Google Cloud CLI (gcloud) para gerar tokens de ID para chamar as APIs REST da Databricks.

important

Os tokens de ID gerados expiram em uma hora. Você deve concluir todas as etapas restantes dentro desse período. Se os tokens expirarem antes de o senhor concluir as etapas posteriores, como ligar para Databricks APIs, será necessário repetir esta etapa para gerar novos tokens de ID do Google.

  1. Instale o Google Cloud CLI em seu computador. Consulte os artigos do Google sobre a instalação da ferramenta gcloud.

  2. Gere o ID tokens para seu serviço principal account executando o seguinte comando.

    • Substitua <SA-1-key-json> pelo caminho do arquivo SA-1 key no formato JSON.
    • Substitua <SA-2-email> pelo endereço email do SA-2.
    • Substitua <audience> da seguinte forma com base no seu caso de uso:
      • Para workspace-level APIs, substitua pelo URL workspace, 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 espaços de trabalho, o senhor precisa criar vários Google ID tokens, cada um com valores audience diferentes.
      • Para account-level API, substitua por https://accounts.gcp.databricks.com. Todas as contas diferentes compartilham o mesmo valor audience.

    executar o seguinte comando para uso com sistemas de produção:

    Bash
    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 fora da produção, se o senhor usar o usuário account para se passar por SA-2, use este comando:

    Bash
    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 o senhor usar um serviço account para SA-1 e SA-2, use esses comandos com o account key JSON arquivo do serviço:

    Bash
    gcloud auth login --cred-file=<SA-key-json>

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

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

Etapa 3: Crie um token de acesso ao Google OAuth (somente para APIs que exige a passagem de credenciais)​

nota

Essa etapa é necessária apenas para chamar APIs que exigem a passagem de credenciais. Para determinar se a passagem de credenciais é necessária para uma operação, consulte a documentação API para cada operação API.

A solicitação para gerar tokens de acesso inclui um campo lifetime que define por quanto tempo os tokens de acesso são válidos. Se o senhor só precisar que os tokens fiquem ativos por cinco minutos, defina como 300s (300 segundos). O exemplo a seguir usa 3600s, que representa uma hora.

important
  • Você deve concluir todas as etapas restantes dentro desse limite de tempo. Se o tempo expirar antes de concluir as etapas posteriores, como ligar para Databricks APIs, o senhor deverá repetir esta etapa para gerar um novo token de acesso ao Google OAuth.
  • Em default, uma hora (3600s) é a duração máxima que o senhor pode definir para o campo lifetime. Para estender esse limite, entre em contato com o atendimento ao cliente do Google e solicite uma exceção.

  1. executar o seguinte comando. Substitua <SA-2-email-address> pelo endereço do serviço account email para SA-2. Para uso não produtivo ou testes, se o senhor estiver usando um único serviço account ou usando um usuário account para se passar por um serviço account, substitua <SA-2-email-address> pelo endereço email do serviço account.

    Bash
    gcloud auth print-access-token --impersonate-service-account=<SA-2-email-address>

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

Etapa 4: Adicione o serviço account como um usuário workspace ou account​

O senhor pode usar o Google tokens Databricks workspaceID para APIs accountligar para -level APIs ou -level. As instruções são diferentes com base no caso de uso. Observe que o senhor não pode usar um token de ID do Google para acessar os dois tipos de APIs devido à diferença no campo audience ao criar os tokens de ID do Google.

espaço de trabalho APIs​

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

  1. Como administrador do workspace, acesse a página de configurações do administrador.
  2. 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.
  3. 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.
  4. Opcionalmente, adicione as configurações de controle de acesso do Databricks para esse usuário. Consulte Listas de controle de acesso.

em nível de conta APIs​

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

  1. Como administrador do account, acesse Users tab no console account.

  2. Clique em Adicionar usuário .

nota

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.

  1. No campo de endereço de e-mail , digite seu endereço principal do serviço account (SA-2) email.

  2. Defina os campos obrigatórios para o nome e sobrenome de uma forma que reflita a finalidade do serviço account.

  3. Clique em Adicionar usuário .

Etapa 5: chamar uma API da Databricks​

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

Os seguintes cabeçalhos HTTP 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 portadores. A sintaxe é Authentication: Bearer <token>.

Todas as APIs

X-Databricks-GCP-SA-Access-Token

Google OAuth tokens de acesso para SA-2.

account-level APIs only

Exemplo workspace-level API request​

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

Authorization: Bearer <google-id-token>

Os tokens fornecidos pelo senhor devem ter os seguintes atributos:

O exemplo a seguir chama workspace-level API para listar o clustering.

  • Substitua <google-id-token> pelos tokens de ID do Google que o senhor salvou no arquivo google-id-token-sa-2.txt.
  • Substitua <workspace-URL> pela URL de seu workspace básico, que tem um formato semelhante a https://1234567890123456.7.gcp.databricks.com.
Bash
curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  <workspace-URL>/api/2.0/clusters/list

Exemplo account-level API solicitação para um API que não usa a passagem de credenciais​

O exemplo a seguir chama a conta API para obter uma lista de espaços de trabalho.

  • Substitua <google-id-token> pelos tokens de ID do Google que o senhor salvou no arquivo google-id-token-sa-2.txt.
  • Substitua <account-id> por sua ID account. Para encontrar sua ID account:
    1. Como administrador do account, acesse o consoleDatabricks account.
    2. Clique na seta para baixo ao lado de seu nome de usuário no canto superior direito.
    3. No menu dropdown, o senhor pode copiar o ID da sua conta.
Bash
curl \
  -X GET \
  --header 'Authorization: Bearer <google-id-token>' \
  https://accounts.gcp.databricks.com/api/2.0/example/<account-id>/operation-name

Exemplo account-level API request with credential passthrough​

O exemplo a seguir chama a conta API para obter uma lista de espaços de trabalho.

  • Substitua <google-id-token> pelos tokens de ID do Google que o senhor salvou no arquivo google-id-token-sa-2.txt.

  • Substitua <access-token-sa-2> pelos tokens de acesso SA-2 que o senhor salvou no arquivo access-token-sa-2.txt.

  • Substitua <account-id> por sua ID account. Para encontrar sua ID account:

    1. Como administrador do account, acesse o consoleDatabricks account.
    2. Na parte inferior do menu à esquerda (talvez seja necessário rolar a tela), clique no botão Usuário (o ícone da pessoa).
    3. Na janela pop-up que aparece, copie o ID do account clicando no ícone à direita do ID.

    Encontre seu account ID.

Bash
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>
Última atualização em