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 iscrizioni 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 pool di identità della forza lavoro e un provider. Per saperne di più, consulta Configura 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 Scambia i token con l'API Cloud OAuth.
  3. Assicurati che il tuo token di accesso includa l'ambito openid.

  4. Abilita l'API Cloud OAuth, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (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 a livello di organizzazione (single-tenant) che puoi utilizzare quando l'applicazione client e le risorse sono limitate a un'organizzazioneGoogle Cloud specifica:

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 di token.
  • ORGANIZATION_ID: l'ID organizzazione numerico Google Cloud .

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 provisioning SCIM abilitato, l'endpoint restituisce attributi del profilo, rivendicazioni personalizzate e appartenenze ai gruppi in linea:

{
  "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à per la forza lavoro utilizzi o meno il provisioning SCIM:

Claim in linea (pool di identità non SCIM)

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

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

Claim distribuiti (pool di identità abilitati per SCIM)

Per i pool di identità della forza lavoro con provisioning SCIM abilitato, le appartenenze ai gruppi vengono restituite come rivendicazioni 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 delle rivendicazioni

La risposta contiene i seguenti campi di rivendicazione standard e distribuiti:

Campo Tipo Descrizione
sub string L'identificatore univoco dell'entità per l'utente autenticato nel pool di identità della forza lavoro.
name string Il nome completo dell'utente, se disponibile presso il provider di identità.
email string L'indirizzo email dell'utente autenticato.
groups array of strings (Solo non SCIM) L'elenco delle iscrizioni ai gruppi aziendali per l'utente.
_claim_names object (Solo con SCIM abilitato) Un oggetto JSON che mappa i nomi delle rivendicazioni distribuite (come groups) agli identificatori di origine in _claim_sources.
_claim_sources object (Solo con SCIM abilitato) 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 alle informazioni utente e ai gruppi di Cloud OAuth.

Passaggi successivi