Scambio di token con l'API Cloud OAuth

Questa guida descrive come scambiare credenziali esterne, codici di autorizzazione o token di aggiornamento con Google Cloud token di accesso utilizzando l'API Cloud OAuth (cloudoauth.googleapis.com) nelle integrazioni della federazione delle identità per la forza lavoro.

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 crea le credenziali client. Per saperne di più, vedi Gestire le applicazioni OAuth.

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

Metodi di autenticazione

L'API Cloud OAuth supporta due metodi di autenticazione client:

  • Autenticazione di base HTTP (consigliata): trasmetti l'ID client e il client secret codificati in Base64 nell'intestazione Authorization:

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

  • Parametri del corpo della richiesta: passa i parametri client_id e client_secret nel corpo della richiesta.

Scambiare un codice di autorizzazione con token

Per scambiare un codice di autorizzazione Google Cloud con un token di accesso e un token di aggiornamento, invia una richiesta HTTP POST:

  • Endpoint con ambito a livello di organizzazione (single-tenant)

    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"

    Credenziali del corpo della richiesta

    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"

Sostituisci quanto segue:

  • BASE64_ENCODED_CREDENTIALS: la stringa con codifica Base64 di CLIENT_ID:CLIENT_SECRET.
  • AUTHORIZATION_CODE: il codice di autorizzazione emesso da Google Cloud.
  • REDIRECT_URI: l'URI di reindirizzamento configurato sul client OAuth.
  • ORGANIZATION_ID: l'ID organizzazione numerico Google Cloud.
  • CLIENT_ID: il tuo ID client OAuth registrato.
  • CLIENT_SECRET: il client secret OAuth.

Aggiornare un token di accesso

Quando un token di accesso scade, utilizza il tipo di concessione refresh_token per ottenere un nuovo token di accesso di breve durata:

  • Endpoint con ambito a livello di organizzazione (single-tenant)

    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"

Sostituisci REFRESH_TOKEN con il token di aggiornamento restituito in precedenza dall'endpoint del token.

Campi di risposta del token

Quando uno scambio di token ha esito positivo, l'API Cloud OAuth restituisce uno stato HTTP 200 OK contenente i seguenti campi:

Campo Tipo Descrizione
access_token string Il token di accesso OAuth 2.0 emesso dall'API Cloud OAuth per chiamare le API Google Cloud .
refresh_token string Il token di aggiornamento utilizzato per ottenere nuovi token di accesso alla scadenza del token attuale.
expires_in integer La durata rimanente del token di accesso in secondi (in genere 3599).
token_type string Il tipo di token (ad esempio, Bearer).
scope string L'elenco degli ambiti associati al token.
id_token string Il token ID OIDC contenente le rivendicazioni di identità autenticata.

Per informazioni sulle risposte di errore restituite dall'API Cloud OAuth, consulta Errori di scambio di token dell'API Cloud OAuth.

Passaggi successivi