Recuperare le informazioni utente con l'API Cloud OAuth

Questa guida descrive come recuperare le attestazioni standard OpenID Connect (OIDC), le attestazioni della directory personalizzate e le appartenenze ai gruppi per gli utenti della forza lavoro autenticati utilizzando l'endpoint /userinfo nell'API Cloud OAuth (cloudoauth.googleapis.com).

Prima di iniziare

  1. Configura un provider e un pool di identità per la forza lavoro. Per ulteriori informazioni, consulta Configurare la federazione delle identità per la forza lavoro.
  2. Registra un client OAuth e scambia un codice di autorizzazione con un token di accesso. Per saperne di più, consulta Scambio di token con l'API Cloud OAuth.
  3. Assicurati che il token di accesso includa l'ambito openid.

  4. Abilita l'API Cloud OAuth.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

Endpoint con ambito a livello di organizzazione

L'API Cloud OAuth fornisce l'endpoint con ambito organizzazione (single-tenant) che puoi utilizzare quando l'applicazione client e le risorse sono limitate a una specifica Google Cloud organizzazione:

Il metodo organizations.userinfo dell'API Cloud OAuth recupera le attestazioni standard OpenID Connect (OIDC), le attestazioni personalizzate e le iscrizioni ai gruppi per l'utente autenticato in un'organizzazione specifica.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • TOKEN: il token di accesso OAuth 2.0 di breve durata ottenuto dall'endpoint di scambio dei token.
  • ORGANIZATION_ID: l'ID organizzazione Google Cloud numerico.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Per i pool di identità della forza lavoro senza il provisioning SCIM abilitato, l'endpoint restituisce in linea gli attributi del profilo, le rivendicazioni personalizzate e le appartenenze ai gruppi:

{
  "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"
  ]
}

Attestazioni utente e gruppi distribuiti SCIM

Quando una richiesta ha esito positivo, l'endpoint /userinfo restituisce uno stato HTTP 200 OK e un oggetto JSON contenente le rivendicazioni per l'utente autenticato.

Il formato delle rivendicazioni dipende dal fatto che il provider del pool di identità della forza lavoro utilizzi il provisioning SCIM:

Attestazioni inline (pool di identità non SCIM)

Per i pool di identità della forza lavoro senza provisioning SCIM abilitato, l'endpoint restituisce attributi del profilo, rivendicazioni personalizzate e appartenenze ai gruppi 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"
  ]
}

Attestazioni distribuite (pool di identità abilitati a SCIM)

Per i pool di identità della forza lavoro con il provisioning SCIM abilitato, le appartenenze ai gruppi vengono restituite come attestazioni distribuite. La risposta include _claim_names e _claim_sources che fanno riferimento all'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"
    }
  }
}

Campi della richiesta in garanzia

La risposta contiene i seguenti campi delle rivendicazioni standard e distribuite:

Campo Tipo Descrizione
sub string L'identificatore univoco del principal per l'utente autenticato nel pool di identità della forza lavoro.
name string Il nome completo dell'utente, se disponibile dal provider di identità.
email string L'indirizzo email dell'utente autenticato.
groups array of strings (Solo non SCIM) L'elenco delle appartenenze ai gruppi aziendali per l'utente.
_claim_names object (Solo SCIM) Un oggetto JSON che mappa i nomi delle attestazioni distribuite (ad esempio groups) agli identificatori di origine in _claim_sources.
_claim_sources object (Solo con SCIM) Un oggetto JSON che definisce l'endpoint di origine per ogni identificatore di rivendicazione distribuita.

Per informazioni sulle risposte di errore restituite dall'endpoint /userinfo, consulta Errori relativi a gruppi e informazioni utente di Cloud OAuth.

Passaggi successivi