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

Este guia descreve como recuperar declarações padrão do OpenID Connect (OIDC), declarações de diretório personalizadas e associações a grupos de 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 da força de trabalho. Para mais informações, consulte Configurar a federação de identidade de colaboradores.
  2. Registre um cliente OAuth e troque 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.

    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 com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o 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 no escopo da organização (locatário único) que pode ser usado quando o aplicativo e os recursos do cliente são restritos a umaGoogle Cloud organização específica:

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 obtido do endpoint de troca de token.
  • ORGANIZATION_ID: o ID da organização numérico da sua 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 a grupos 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ário 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 de o provedor de pool de identidade da força de trabalho usar o provisionamento do SCIM:

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

Para pools de identidades de colaboradores sem o provisionamento do SCIM ativado, o endpoint retorna atributos de perfil, declarações personalizadas e associações a grupos 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"
  ]
}

Reivindicações distribuídas (pools de identidade habilitados para SCIM)

Para pools de identidade de colaboradores com provisionamento do SCIM ativado, as associações a grupos 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 colaboradores.
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 não SCIM) A lista de associações a grupos empresariais do usuário.
_claim_names object (Somente com 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 respostas de erro retornadas pelo endpoint /userinfo, consulte Erros de grupos e informações do usuário do Cloud OAuth.

A seguir