La tua API Account Linking

Questa pagina di riferimento documenta gli endpoint API che il tuo servizio deve implementare per supportare il collegamento degli account con Google. Ciò include il collegamento dell'account basato su OAuth, il collegamento dell'account semplificato e il trasferimento app.

Prerequisiti e standard

Per implementare correttamente questi endpoint, il tuo servizio deve rispettare i seguenti standard:

  • OAuth 2.0: conforme alla RFC 6749.
  • Revoca del token: conforme a RFC 7009.
  • JSON Web Token (JWT): conforme a RFC 7519 (obbligatorio per il collegamento semplificato).
  • HTTPS: tutti gli endpoint devono essere pubblicati tramite una connessione HTTPS sicura.

Endpoint di autorizzazione

L'endpoint di autorizzazione è responsabile dell'autenticazione degli utenti e dell'ottenimento del loro consenso per collegare i propri account a Google.

  • URL:configurato nella console Actions o nella console Google Cloud.
  • Metodo: GET

Parametri di richiesta

Parametri Descrizione
client_id L'ID client che hai assegnato a Google.
redirect_uri L'URL a cui invii la risposta a questa richiesta.
state Un valore di riferimento ritrasmesso a Google senza modifiche nell'URI di reindirizzamento.
response_type Deve essere code per il flusso del codice di autorizzazione.
scope (Facoltativo) Elenco degli ambiti separati da spazi per i dati richiesti da Google.
user_locale (Facoltativo) L'impostazione della lingua dell'Account Google, specificata utilizzando un tag di lingua BCP-47 (ad es. en-US).

Endpoint di scambio dei token

Questo endpoint è responsabile dello scambio dei codici di autorizzazione con i token e del rinnovo dei token di accesso scaduti.

  • URL:configurato nella console Actions o nella console Google Cloud.
  • Metodo: POST
  • Content-Type: application/x-www-form-urlencoded

Scambia codice di autorizzazione per i token

I seguenti parametri vengono utilizzati nella richiesta iniziale di scambio di token.

Parametri di richiesta

Parametri Descrizione
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.
grant_type Deve essere authorization_code.
code Il codice di autorizzazione ricevuto dall'endpoint di autorizzazione.
redirect_uri Lo stesso URI di reindirizzamento utilizzato nella richiesta iniziale.

Scambia il token di aggiornamento con il token di accesso

I seguenti parametri vengono utilizzati durante l'aggiornamento di un token di accesso.

Parametri di richiesta

Parametri Descrizione
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.
grant_type Deve essere refresh_token.
refresh_token Il token di aggiornamento emesso in precedenza per Google.

Risposta (JSON)

Restituisci una risposta riuscita con un oggetto JSON nel corpo della risposta HTTPS.

  • Stato HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8
Campi Descrizione
token_type Obbligatorio. Deve essere bearer.
access_token Obbligatorio. Un token di breve durata utilizzato per accedere alle API del servizio.
refresh_token Obbligatorio per authorization_code grant_type. Un token di lunga durata utilizzato per ottenere nuovi token di accesso.
expires_in Obbligatorio. La durata rimanente del token di accesso in secondi.

Risposte di errore

Se una richiesta all'endpoint token non va a buon fine, restituisci un errore HTTP 400 Bad Request insieme a una risposta JSON contenente i seguenti campi:

  • Stato HTTP: 400 Bad Request
  • Content-Type: application/json;charset=UTF-8
Campi di errore (JSON) Descrizione
error Obbligatorio. Deve essere invalid_grant.
error_description (Facoltativo) Testo leggibile che fornisce informazioni aggiuntive.

Gestire gli intent di collegamento semplificato

Se il tuo servizio supporta il collegamento degli account semplificato (OAuth con Accedi con Google), l'endpoint di scambio dei token deve supportare anche le asserzioni JSON Web Token (JWT) e implementare gli intent check, create e get.

Nelle richieste vengono utilizzati i seguenti parametri:

Parametri di richiesta

Parametri Descrizione
intent L'intent di collegamento semplificato specifico richiesto: check, get o create.
grant_type Per queste richieste, questo parametro ha sempre il valore urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Un token JWT (JSON Web Token) che fornisce un'asserzione firmata dell'identità dell'utente Google. Il JWT contiene informazioni che includono l'ID, il nome e l'indirizzo email dell'Account Google dell'utente.

Il server deve convalidare questo JWT utilizzando i criteri elencati nella sezione Convalida JWT.
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.
scope (Facoltativo) Tutti gli ambiti che hai configurato in modo che Google li richieda agli utenti. Di solito presente durante gli intent get e create.
response_type Obbligatorio per l'intent create:deve essere impostato su token.

Convalida JWT

Per garantire la sicurezza del collegamento semplificato, il server deve convalidare il assertion (JWT) utilizzando i seguenti criteri:

  • Firma: verifica la firma rispetto alle chiavi pubbliche di Google (disponibili all'endpoint JWK di Google).
  • Emittente (iss): deve essere https://accounts.google.com.
  • Audience (aud): deve corrispondere all'ID client API di Google assegnato alla tua integrazione.
  • Scadenza (exp): deve essere nel futuro.

Risposta per l'intent check

Una richiesta con intent=check verifica se l'Account Google (identificato dall'attestazione sub o email nel JWT decodificato) esiste nel tuo database utenti.

  • Stato HTTP: 200 OK (Account trovato) o 404 Not Found (Account non trovato)
  • Content-Type: application/json;charset=UTF-8
Campi Descrizione
account_found Obbligatorio. true se l'account esiste, false altrimenti.

Risposta per l'intent get

Una richiesta con intent=get richiede un token di accesso per un Account Google esistente.

  • Stato HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

L'oggetto JSON della risposta riuscita utilizza la stessa struttura di una risposta di scambio di token standard riuscita (restituendo access_token, refresh_token e così via).

Se l'account non può essere collegato, viene restituito un errore HTTP 401.

  • Stato HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Campi di errore (JSON) Descrizione
error Obbligatorio. Deve essere linking_error.
login_hint (Facoltativo) L'indirizzo email dell'utente da passare al flusso di collegamento OAuth di riserva.

Risposta per l'intent create

Una richiesta con intent=create richiede la creazione di un nuovo account utente con le informazioni fornite nel JWT.

  • Stato HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

L'oggetto JSON della risposta riuscita utilizza la stessa struttura di una risposta di scambio di token standard riuscita (restituendo access_token, refresh_token e così via).

Se l'utente esiste già, viene restituito un errore HTTP 401 per chiedere all'utente di collegare il proprio account esistente.

  • Stato HTTP: 401 Unauthorized
  • Content-Type: application/json;charset=UTF-8
Campi di errore (JSON) Descrizione
error Obbligatorio. Deve essere linking_error.
login_hint L'indirizzo email dell'utente da passare al flusso di collegamento OAuth di riserva.

Endpoint UserInfo (facoltativo)

Utilizzato per recuperare le informazioni di base del profilo dell'utente collegato, come specificato nella specifica OpenID Connect Core 1.0. Questo è necessario per funzionalità come "Collegamento semplificato" o "Accesso con un tocco".

  • Metodo: GET
  • Autenticazione: Authorization: Bearer ACCESS_TOKEN

Risposta (JSON)

Restituisci una risposta riuscita con un oggetto JSON nel corpo della risposta HTTPS.

  • Stato HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Campi di risposta

Campi Descrizione
sub Obbligatorio. Un ID univoco che identifica l'utente nel tuo sistema.
email Obbligatorio. L'indirizzo email dell'utente.
email_verified Obbligatorio. Un valore booleano che indica se l'indirizzo email è stato verificato.
given_name (Facoltativo) Il nome dell'utente.
family_name (Facoltativo) Il cognome dell'utente.
name (Facoltativo) Il nome completo dell'utente.
picture (Facoltativo) Un URL all'immagine del profilo dell'utente.

Risposte di errore

Se il token di accesso non è valido o è scaduto, restituisci un errore HTTP 401 - Non autorizzato. Devi includere anche l'intestazione della risposta WWW-Authenticate.

Qualsiasi risposta non riuscita (4xx o 5xx) restituita durante la procedura di collegamento è considerata non recuperabile. In questi casi, Google eliminerà tutti i token recuperati e l'utente dovrà avviare di nuovo la procedura di collegamento dell'account.

Endpoint di revoca del token (facoltativo)

Consente a Google di inviare una notifica al tuo servizio quando un utente scollega il proprio account dalla piattaforma Google. Questo endpoint deve soddisfare i requisiti descritti nella RFC 7009.

  • Metodo: POST
  • Content-Type: application/x-www-form-urlencoded

Parametri di richiesta

Parametri Descrizione
client_id Una stringa che identifica l'origine della richiesta come Google. Questa stringa deve essere registrata nel tuo sistema come identificatore univoco di Google.
client_secret Una stringa segreta registrata con Google per il tuo servizio.
token Il token da revocare.
token_type_hint (Facoltativo) Un suggerimento sul tipo di token revocato, access_token o refresh_token. Se non specificato, il valore predefinito è access_token.

Risposte

Restituisce una risposta positiva quando il token viene eliminato correttamente o se il token non è più valido.

  • Stato HTTP: 200 OK
  • Content-Type: application/json;charset=UTF-8

Risposte di errore

Se il token non può essere eliminato per qualsiasi motivo (ad es. indisponibilità del database), restituisci un errore HTTP 503. Google riproverà a inviare la richiesta in un secondo momento o come indicato nell'intestazione Retry-After.

  • Stato HTTP: 503 Service Unavailable
  • Content-Type: application/json;charset=UTF-8
  • Intestazioni: Retry-After: <HTTP-date / delay-seconds>