API Google Account Linking

Questa pagina di riferimento documenta gli endpoint e le interfacce offerti da Google che la tua app utilizza durante la procedura di collegamento dell'account basata su OAuth.

Prerequisiti e standard

Per interagire correttamente con questi endpoint di Google, la tua integrazione deve rispettare i seguenti standard:

  • OAuth 2.0: conforme a RFC 6749.
  • JSON Web Token (JWT): conforme a RFC 7519 (per il collegamento semplificato e RISC).
  • Security Event Token: conforme a RFC 8417 (per RISC).
  • HTTPS: tutte le richieste devono essere effettuate tramite una connessione HTTPS sicura.

URI di reindirizzamento OAuth

L'endpoint in cui il tuo servizio reindirizza il browser dell'utente dopo l'autenticazione e il consenso. Il parametro del percorso YOUR_PROJECT_ID è l'ID che configuri durante la registrazione.

  • URL: https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

  • URL sandbox: https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  • Metodo: GET (utilizzando il reindirizzamento del browser)

Parametri di richiesta

Quando reindirizzi l'utente a Google, i parametri devono essere aggiunti all'URL. A seconda del flusso OAuth utilizzato, questi parametri vengono formattati come una stringa di query (flusso del codice di autorizzazione) o come un frammento di URL (flusso implicito).

Parametro Descrizione
code (Obbligatorio per il flusso del codice di autorizzazione) Il codice di autorizzazione generato dal tuo servizio.
state (Obbligatorio) Il valore dello stato non modificato ricevuto originariamente da Google.
access_token (Obbligatorio per il flusso implicito) Il token di accesso a lunga durata generato dal tuo servizio.
token_type (Obbligatorio per il flusso implicito) Deve essere bearer.

Risposte di errore

Se la richiesta all'URI di reindirizzamento OAuth non è valida, riceverai un errore HTTP 400 Richiesta non valida. Il corpo della risposta conterrà un oggetto JSON con la seguente struttura:

Campo Descrizione
sendPostBody Determina se il codice JavaScript deve reindirizzare a redirectUri con POST. In genere false in questo scenario.
errorMessage Un messaggio di errore da visualizzare al client quando non è possibile completare il reindirizzamento. Per i frammenti mancanti, questo è "A URI fragment or query string must be set."

Risposte di errore OAuth 2.0

Se l'utente nega il consenso o il tuo servizio rileva un errore, il tuo servizio deve reindirizzare l'utente all'URI di reindirizzamento OAuth con i parametri di errore OAuth 2.0 standard OAuth 2.0 error parameters (ad esempio error=access_denied). Google elaborerà questi parametri e mostrerà all'utente una schermata di errore appropriata.

API RISC (facoltativa)

Utilizzata dal tuo servizio per notificare in modo proattivo a Google quando un utente scollega il proprio account sulla tua piattaforma utilizzando il RISC, garantendo che entrambe le piattaforme rimangano sincronizzate.

  • URL: https://risc.googleapis.com/v1/events:publish
  • Metodo: POST
  • Autenticazione: richiede un token dell'account di servizio Google con le autorizzazioni appropriate.
  • Content-Type: application/json

Attestazioni del token dell'evento di sicurezza

I token dell'evento di sicurezza che utilizzi per notificare a Google gli eventi di revoca dei token devono essere conformi ai requisiti riportati nella tabella seguente:

Richiedi Descrizione
iss Attestazione dell'emittente: si tratta di un URL che ospiti e che viene condiviso con Google durante la registrazione.
aud Attestazione del pubblico: identifica Google come destinatario del JWT. Deve essere impostato su google_account_linking.
jti Attestazione ID JWT: si tratta di un ID univoco che generi per ogni token dell'evento di sicurezza.
iat Attestazione "Emesso a": si tratta di un valore NumericDate che rappresenta l'ora in cui è stato creato questo token dell'evento di sicurezza.
toe Attestazione "Ora dell'evento": si tratta di un valore NumericDate facoltativo che rappresenta l'ora in cui il token è stato revocato.
exp Attestazione "Ora di scadenza": non includere questo campo, perché l'evento che ha generato questa notifica è già avvenuto.
events Attestazione "Eventi di sicurezza": si tratta di un oggetto JSON e deve includere un solo evento di revoca del token contenente i seguenti campi:

  • subject_type: deve essere impostato su oauth_token.
  • token_type: si tratta del tipo di token revocato, access_token o refresh_token.
  • token_identifier_alg: si tratta dell'algoritmo utilizzato per codificare il token e deve essere hash_SHA512_double.
  • token: si tratta dell'ID del token revocato.

Per ulteriori informazioni sui tipi e sui formati dei campi, consulta JSON Web Token (JWT)

Interfaccia "Flip-Back" di App Flip

Per App Flip, la tua app mobile deve restituire il codice di autorizzazione o il token di accesso all'app Google.

Android (risultato dell'intent)

La tua app viene aperta utilizzando un intent. Dopo il consenso, termina e restituisce un risultato a Google. Per ulteriori informazioni, consulta la guida all'implementazione di Android.

  • Azione: com.google.android.gms.auth.CODE_AVAILABLE
  • Extra: code, state, access_token, token_type.

La tua app apre Google utilizzando uno schema URL personalizzato o un link universale HTTPS. Per ulteriori informazioni, consulta la guida all'implementazione di iOS.

  • Formato: <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING