Recuperar informações do usuário com a API Cloud OAuth

Neste guia, descrevemos como recuperar declarações padrão do OpenID Connect (OIDC), declarações de diretório personalizadas e associações a grupos para usuários autenticados da força de trabalho usando o endpoint /userinfo na API Cloud OAuth (cloudoauth.googleapis.com).

Antes de começar

  1. Configure 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 trocar um código de autorização por um token de acesso. Para mais informações, consulte Trocar tokens com a API Cloud OAuth.
  3. Verifique se o token de acesso inclui o escopo openid.

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

Endpoint com escopo de organização

A API Cloud OAuth fornece o endpoint com escopo de organização (locatário único) que pode ser usado quando o aplicativo cliente e os recursos estão restritos a uma organização específica do Google Cloud :

O método organizations.userinfo da API Cloud OAuth recupera declarações padrão do OpenID Connect (OIDC), declarações personalizadas e associações a grupos do usuário autenticado em uma organização específica.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • TOKEN: o token de acesso OAuth 2.0 de curta duração recebido do endpoint de troca de tokens.
  • ORGANIZATION_ID: o ID da organização numérico do Google Cloud .

Método HTTP e URL: 

GET https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/userinfo

Para enviar a solicitação, expanda uma destas opções:

Para pools de identidade de colaboradores sem o provisionamento do SCIM ativado, o endpoint retorna atributos de perfil, declarações personalizadas e associações de grupo inline:

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

Declarações de usuários e grupos distribuídos do SCIM

Quando uma solicitação é bem-sucedida, o endpoint /userinfo retorna um status HTTP 200 OK e um objeto JSON que contém declarações para o usuário autenticado.

O formato das declarações depende se o provedor do pool de identidades de colaboradores usa o provisionamento do SCIM:

Declarações inline (pools de identidade que não são do SCIM)

Para pools de identidade de colaboradores sem o provisionamento do SCIM ativado, o endpoint retorna atributos de perfil, declarações personalizadas e associações de grupo inline:

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "email": "user@example.com",
  "custom_claim1": "engineering",
  "custom_claim2": "us-west",
  "groups": [
    "looker-developers",
    "analytics-viewers"
  ]
}

Declarações distribuídas (pools de identidade com SCIM ativado)

Para pools de identidade de colaboradores com o provisionamento do SCIM ativado, as associações de grupo são retornadas como declarações distribuídas. A resposta inclui _claim_names e _claim_sources que fazem referência ao endpoint /groups:

{
  "sub": "principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com",
  "name": "Jane Doe",
  "email": "user@example.com",
  "_claim_names": {
    "groups": "src1"
  },
  "_claim_sources": {
    "src1": {
      "endpoint": "https://cloudoauth.googleapis.com/v1/common/groups"
    }
  }
}

Campos de declaração

A resposta contém os seguintes campos de declaração padrão e distribuída:

Campo Tipo Descrição
sub string O identificador principal exclusivo do usuário autenticado no pool de identidades de força de trabalho.
name string O nome completo do usuário, se disponível no provedor de identidade.
email string O endereço de e-mail do usuário autenticado.
groups array of strings (Somente para não SCIM) A lista de associações a grupos corporativos do usuário.
_claim_names object (Somente para SCIM) Um objeto JSON que mapeia nomes de declarações distribuídas (como groups) para identificadores de origem em _claim_sources.
_claim_sources object (Somente para SCIM) Um objeto JSON que define o endpoint de origem para cada identificador de declaração distribuída.

Para informações sobre as respostas de erro retornadas pelo endpoint /userinfo, consulte Erros de grupos e informações do usuário do Cloud OAuth.

A seguir