Scambio di token con l'API Cloud OAuth

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Puoi utilizzare l'API Cloud OAuth (cloudoauth.googleapis.com) per scambiare codici di autorizzazione o token di aggiornamento con token di accesso OAuth 2.0 di breve durata Google Cloude token ID OpenID Connect (OIDC). Nelle integrazioni della federazione delle identità per la forza lavoro, le tue applicazioni possono quindi verificare i token ID restituiti utilizzando le chiavi pubbliche della tua organizzazione e utilizzare i token di accesso per chiamare le APIGoogle Cloud per conto degli utenti federati.

Prima di iniziare

1. Configura un pool di identità per la 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 crea le credenziali client. Per saperne di più, consulta Gestisci le applicazioni OAuth.

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

Metodi di autenticazione

Per autenticare il tuo client OAuth con l'API Cloud OAuth, passa l'ID client e il client secret in uno dei seguenti modi:

• Autenticazione di base HTTP (consigliata): trasmetti l'ID client e il client secret con codifica 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.

Nota: utilizza un solo metodo di autenticazione per richiesta. La combinazione di più metodi di autenticazione restituisce un errore. L'API Cloud OAuth non supporta le asserzioni client dei token di connessione JSON Web Token (JWT) (client_assertion).

Scambia un codice di autorizzazione con i token

Dopo che un utente federato ha eseguito l'accesso con il proprio provider di identità (IdP) presso l'endpoint di autorizzazione unificato diGoogle Cloud(https://auth.cloud.google/authorize), l'endpoint di autorizzazione reindirizza l'utente all'URI di reindirizzamento della tua applicazione con un codice di autorizzazione. Per scambiare questo codice di autorizzazione con un token di accesso, un token di aggiornamento e un token ID OIDC, invia una richiesta HTTP POST all'endpoint con ambito organizzazione (single-tenant):

• Autenticazione di base HTTP (consigliata):

  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"
  

• Parametri 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:

• ORGANIZATION_ID: l'ID organizzazione numerico Google Cloud.
• BASE64_ENCODED_CREDENTIALS: la stringa con codifica in base64 di CLIENT_ID:CLIENT_SECRET.
• AUTHORIZATION_CODE: il codice di autorizzazione restituito dall'endpoint di autorizzazione unificato di Google Cloud(https://auth.cloud.google/authorize).
• REDIRECT_URI: l'URI di reindirizzamento configurato sul tuo client OAuth.
• CLIENT_ID: il tuo ID client OAuth registrato.
• CLIENT_SECRET: il client secret OAuth.

Aggiorna un token di accesso

Quando un token di accesso scade, utilizza il grant type refresh_token per ottenere un nuovo token di accesso di breve durata dall'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 quanto segue:

• ORGANIZATION_ID: l'ID organizzazione numerico Google Cloud.
• BASE64_ENCODED_CREDENTIALS: la stringa con codifica in base64 di CLIENT_ID:CLIENT_SECRET.
• REFRESH_TOKEN: il token di aggiornamento restituito in precedenza dall'endpoint token.
• REDIRECT_URI: l'URI di reindirizzamento configurato sul tuo client OAuth.

Campi di risposta del token

Quando uno scambio di token va a buon fine, 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 corrente.
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	Un elenco degli ambiti associati al token.
id_token	string	Il token ID OIDC contenente le rivendicazioni di identità autenticate.

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

Verifica il token ID OIDC

Per le integrazioni OIDC di Looker, puoi verificare la firma crittografica di id_token restituita dall'API Cloud OAuth utilizzando le chiavi web JSON (JWK) pubbliche della tua organizzazione.

Importante: Gli endpoint /.well-known/openid-configuration e /.well-known/jwks.json sono disponibili solo per Looker.

Recupera i JWK pubblici dell'organizzazione in uno dei seguenti modi:

• Esegui una query direttamente sull'endpoint del set di chiavi web JSON (JWKS): invia una richiesta HTTP GET a https://cloudoauth.googleapis.com/v1/organizations/ORGANIZATION_ID/.well-known/jwks.json.
• Utilizza il documento di rilevamento OIDC: invia una richiesta HTTP GET all'endpoint di rilevamento OIDC (https://auth.cloud.google/oidc/organizations/ORGANIZATION_ID/.well-known/openid-configuration) per recuperare l'URL dell'endpoint JWKS dal campo jwks_uri.

In entrambi gli URL degli endpoint, sostituisci ORGANIZATION_ID con l'ID numerico della tua organizzazione Google Cloud .

Passaggi successivi

• Recupera le informazioni utente con l'API Cloud OAuth
• Recupera i gruppi aziendali con l'API Cloud OAuth
• Panoramica dell'API Cloud OAuth
• Gestisci le applicazioni OAuth per la federazione delle identità per la forza lavoro
• Riferimento API REST Cloud OAuth