Trocar tokens com a API Cloud OAuth

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Use a API Cloud OAuth (cloudoauth.googleapis.com) para trocar códigos de autorização ou tokens de atualização por tokens de acesso do OAuth 2.0 Google Cloud e tokens de ID do OpenID Connect (OIDC) de curta duração. Nas integrações da federação de identidade de colaboradores, seus aplicativos podem verificar os tokens de ID retornados usando as chaves públicas da sua organização e usar os tokens de acesso para chamar APIs doGoogle Cloud em nome de usuários federados.

Antes de começar

1. Configurar um pool e um provedor de identidade de colaboradores. Saiba mais em Configurar a federação de identidade de colaboradores.
2. Registrar um cliente OAuth e criar credenciais de cliente. Para mais informações, consulte Gerenciar aplicativos OAuth.

3. Ative a API Cloud OAuth, se ainda não estiver ativada.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

Métodos de autenticação

Para autenticar seu cliente OAuth com a API Cloud OAuth, transmita o ID do cliente e a chave secreta do cliente de uma das seguintes maneiras:

• Autenticação básica HTTP (recomendada): transmita o ID do cliente e a chave secreta do cliente codificados em base64 no cabeçalho Authorization:

  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)"
  

• Parâmetros do corpo da solicitação: transmita os parâmetros client_id e client_secret no corpo da solicitação.

Observação:use apenas um método de autenticação por solicitação. A combinação de vários métodos de autenticação retorna um erro. A API Cloud OAuth não é compatível com declarações de cliente de token do portador JSON Web Token (JWT) (client_assertion).

Trocar um código de autorização por tokens

Depois que um usuário federado faz login com o provedor de identidade (IdP) no endpoint de autorização unificado doGoogle Cloud (https://auth.cloud.google/authorize), o endpoint de autorização redireciona o usuário para o URI de redirecionamento do aplicativo com um código de autorização. Para trocar esse código de autorização por um token de acesso, um token de atualização e um token de ID do OIDC, envie uma solicitação HTTP POST para o endpoint com escopo da organização (locatário único):

• Autenticação básica HTTP (recomendada):

  curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
  -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=REDIRECT_URI"
  

• Parâmetros do corpo da solicitação:

  curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=REDIRECT_URI" \
  --data-urlencode "client_id=CLIENT_ID" \
  --data-urlencode "client_secret=CLIENT_SECRET"
  

Substitua:

• ORGANIZATION_ID: o ID da organização numérico do Google Cloud.
• BASE64_ENCODED_CREDENTIALS: a string codificada em base64 de CLIENT_ID:CLIENT_SECRET.
• AUTHORIZATION_CODE: o código de autorização retornado pelo endpoint de autorização unificado do Google Cloud (https://auth.cloud.google/authorize).
• REDIRECT_URI: o URI de redirecionamento configurado no seu cliente OAuth.
• CLIENT_ID: o ID do cliente OAuth registrado.
• CLIENT_SECRET: a chave secreta do cliente OAuth.

Atualizar um token de acesso

Quando um token de acesso expirar, use o tipo de permissão de acesso refresh_token para receber um novo token de acesso de curta duração do endpoint no escopo da organização (locatário único):

curl -X POST https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/token \
  -H "Authorization: Basic BASE64_ENCODED_CREDENTIALS" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=REFRESH_TOKEN" \
  --data-urlencode "redirect_uri=REDIRECT_URI"

Substitua:

• ORGANIZATION_ID: o ID da organização numérico do Google Cloud.
• BASE64_ENCODED_CREDENTIALS: a string codificada em base64 de CLIENT_ID:CLIENT_SECRET.
• REFRESH_TOKEN: o token de atualização que o endpoint de token retornou anteriormente.
• REDIRECT_URI: o URI de redirecionamento configurado no seu cliente OAuth.

Campos de resposta de token

Quando uma troca de token é bem-sucedida, a API Cloud OAuth retorna um status HTTP 200 OK contendo os seguintes campos:

Campo	Tipo	Descrição
access_token	string	O token de acesso do OAuth 2.0 emitido pela API Cloud OAuth para chamar as APIs do Google Cloud .
refresh_token	string	O token de atualização usado para receber novos tokens de acesso quando o token atual expirar.
expires_in	integer	A vida útil restante do token de acesso em segundos (normalmente 3599).
token_type	string	O tipo de token (por exemplo, Bearer).
scope	string	Uma lista dos escopos associados ao token.
id_token	string	O token de ID do OIDC que contém declarações de identidade autenticadas.

Para informações sobre as respostas de erro retornadas pela API Cloud OAuth, consulte Erros de troca de token da API Cloud OAuth.

Verificar o token de ID do OIDC

Para integrações do OIDC do Looker, é possível verificar a assinatura criptográfica do id_token retornado pela API Cloud OAuth usando as chaves da Web JSON (JWKs) públicas da sua organização.

Importante:os endpoints /.well-known/openid-configuration e /.well-known/jwks.json estão disponíveis apenas para o Looker.

Recupere os JWKs públicos da organização de uma das seguintes maneiras:

• Consulte o endpoint do conjunto de chaves da Web JSON (JWKS) diretamente: envie uma solicitação HTTP GET para https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/.well-known/jwks.json.
• Use o documento de descoberta do OIDC: envie uma solicitação HTTP GET para o endpoint de descoberta do OIDC (https://auth.cloud.google/oidc/organizations/ORGANIZATION_ID/.well-known/openid-configuration) para recuperar o URL do endpoint JWKS do campo jwks_uri.

Nos dois URLs de endpoint, substitua ORGANIZATION_ID pelo ID numérico da organização do Google Cloud .

A seguir

• Recuperar informações do usuário com a API Cloud OAuth
• Recuperar grupos corporativos com a API Cloud OAuth
• Visão geral da API Cloud OAuth
• Gerenciar aplicativos OAuth para federação de identidade de colaboradores
• Referência da API REST do Cloud OAuth