Collegamento semplificato con OAuth e Accedi con Google

Panoramica

Il collegamento semplificato di Accedi con Google basato su OAuth aggiunge Accedi con Google a l collegamento OAuth. In questo modo, gli utenti Google possono collegare i propri account in modo semplice e creare un nuovo account sul tuo servizio utilizzando il proprio Account Google.

Per eseguire il collegamento dell'account con OAuth e Accedi con Google, segui questi passaggi generali:

  1. Innanzitutto, chiedi all'utente di dare il consenso per accedere al suo profilo Google.
  2. Utilizza le informazioni del profilo per verificare se l'account utente esiste.
  3. Per gli utenti esistenti, collega gli account.
  4. Se non riesci a trovare una corrispondenza per l'utente Google nel tuo sistema di autenticazione, convalida il token ID ricevuto da Google. Poi, puoi creare un utente in base alle informazioni del profilo contenute nel token ID.
Questa figura mostra i passaggi che un utente deve seguire per collegare il proprio Account Google utilizzando il flusso di collegamento semplificato. Il primo screenshot mostra come un utente può selezionare la tua app per il collegamento. La seconda schermata consente all'utente di confermare se ha o meno un account esistente sul tuo servizio. La terza schermata consente all'utente di selezionare l'Account Google da collegare. Il quarto screenshot mostra la conferma del collegamento dell'Account Google all'app. Il quinto screenshot mostra un account utente collegato correttamente nell'app Google.

Figura 1. Collegamento dell'account sullo smartphone di un utente con il collegamento semplificato

Requisiti per il collegamento semplificato

  • Implementa il flusso di collegamento OAuth web di base. Il tuo servizio deve supportare gli endpoint di autorizzazione e scambio di token conformi a OAuth 2.0.
  • L'endpoint di scambio di token deve supportare le asserzioni JWT (JSON Web Token) e implementare gli intent check, create e get.

Implementare il server OAuth

L'endpoint di scambio di token deve supportare gli intent check, create e get. Segui questi passaggi per completare il flusso di collegamento dell'account e scoprire quando vengono utilizzati i diversi intent:

  1. L'utente ha un account nel tuo sistema di autenticazione? (L'utente decide selezionando SÌ o NO)
    1. SÌ : l'utente utilizza l'indirizzo email associato al suo Account Google per accedere alla tua piattaforma? (L'utente decide selezionando SÌ o NO)
      1. SÌ : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (check intent viene chiamato per confermare)
        1. SÌ : get intent viene chiamato e l'account viene collegato se l'intent get viene restituito correttamente.
        2. NO : creare un nuovo account? (L'utente decide selezionando SÌ o NO)
          1. SÌ : viene chiamato create intent e l'account viene collegato se l'intent create viene restituito correttamente.
          2. NO : viene attivato il flusso OAuth web, l'utente viene indirizzato al browser e gli viene data la possibilità di collegare un altro indirizzo email.
      2. NO : viene attivato il flusso OAuth web, l'utente viene indirizzato al browser e gli viene data la possibilità di collegare un altro indirizzo email.
    2. NO : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (check intent viene chiamato per confermare)
      1. SÌ : get intent viene chiamato e l'account viene collegato se l'intent get viene restituito correttamente.
      2. NO : create intent viene chiamato e l'account viene collegato se l'intent create viene restituito correttamente.

Verificare la presenza di un account utente esistente (check intent)

Dopo che l'utente acconsente ad accedere al proprio profilo Google, Google invia una contenente un'asserzione firmata dell'identità dell'utente Google. La l'asserzione contiene informazioni che includono l'ID dell'Account Google dell'utente, nome e indirizzo email. L'endpoint di scambio di token configurato per il progetto gestisce la richiesta.

Se l'Account Google corrispondente è già presente nella tua autenticazione di sistema, il tuo endpoint di scambio di token risponde con account_found=true. Se L'Account Google non corrisponde a un utente esistente, il tuo endpoint di scambio di token restituisce un errore HTTP 404 - Non trovato con account_found=false.

La richiesta ha il seguente modulo:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

L'endpoint di scambio di token deve essere in grado di gestire i seguenti parametri:

Parametri endpoint token
intent Per queste richieste, il valore di questo parametro è check.
grant_type Il tipo di token che viene scambiato. Per queste richieste, ha il valore urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion un token JWT (JSON Web Token) che fornisce un'asserzione firmata dei l'identità dell'utente. Il JWT contiene informazioni che includono il ID dell'Account Google, nome e indirizzo email.
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.

Per rispondere alle richieste di intent check, l'endpoint dello scambio di token deve eseguire i seguenti passaggi:

  • Convalida e decodifica l'asserzione JWT.
  • Verifica se l'Account Google è già presente nel sistema di autenticazione.
convalida e decodifica l'asserzione JWT

Puoi convalidare e decodificare l'asserzione JWT utilizzando un Libreria di decodifica JWT per la tua lingua. Utilizza le funzionalità di Chiavi pubbliche di Google, disponibili in JWK o formati PEM, per verificare la firma del token.

Una volta decodificata, l'asserzione JWT è simile all'esempio seguente: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Oltre a verificare la firma del token, verifica che l'asserzione l'emittente (campo iss) è https://accounts.google.com, che il pubblico (campo aud) è l'ID cliente che ti è stato assegnato e che il token non è scaduto (campo exp).

Utilizzando i campi email, email_verified e hd puoi determinare se Google ospita un indirizzo email ed è autorevole. Nei casi in cui Google ufficiale che l'utente sia attualmente noto per essere il legittimo proprietario dell'account e puoi saltare l'uso della password o altri metodi di verifica. In caso contrario, questi metodi può essere utilizzato per verificare l'account prima del collegamento.

Casi in cui Google è autorevole:

  • email ha un suffisso @gmail.com, questo è un account Gmail.
  • email_verified è true e hd è impostato, questo è un account G Suite.

Gli utenti possono registrarsi per creare Account Google senza utilizzare Gmail o G Suite. Quando email non contiene un suffisso @gmail.com e hd non è presente autoritativi e con password o altri metodi di verifica per verificare per l'utente. Il valore email_verified può anche essere vero perché Google ha verificato inizialmente il valore all'utente quando è stato creato l'account Google, ma la proprietà della terza parte l'account email potrebbe essere cambiato da allora.

Controllare se l'Account Google è già presente nel sistema di autenticazione

Controlla se è vera una delle seguenti condizioni:

  • L'ID Account Google, che si trova nel campo sub dell'asserzione, è nel tuo utente per configurare un database.
  • L'indirizzo email nell'asserzione corrisponde a un utente nel tuo database utenti.

Se una delle condizioni è vera, l'utente ha già effettuato la registrazione. In questo caso, restituiscono una risposta simile alla seguente:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Se né l'ID Account Google né l'indirizzo email specificato nella asserzione corrisponde a un utente presente nel tuo database, l'utente non si è ancora registrato. Nella In questo caso, l'endpoint di scambio di token deve rispondere con un errore HTTP 404. che specifica "account_found": "false", come nell'esempio seguente:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}

Gestire il collegamento automatico (ottenere l'intenzione)

Dopo che l'utente acconsente ad accedere al proprio profilo Google, Google invia una contenente un'asserzione firmata dell'identità dell'utente Google. La l'asserzione contiene informazioni che includono l'ID dell'Account Google dell'utente, nome e indirizzo email. L'endpoint di scambio di token configurato per il progetto gestisce la richiesta.

Se l'Account Google corrispondente è già presente nell'autenticazione il tuo endpoint di scambio di token restituisce un token per l'utente. Se L'Account Google non corrisponde a un utente esistente, il tuo endpoint di scambio di token restituisce un errore linking_error e un valore facoltativo per il campo login_hint.

La richiesta ha il seguente modulo:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

L'endpoint di scambio di token deve essere in grado di gestire i seguenti parametri:

Parametri endpoint token
intent Per queste richieste, il valore di questo parametro è get.
grant_type Il tipo di token che viene scambiato. Per queste richieste, ha il valore urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion un token JWT (JSON Web Token) che fornisce un'asserzione firmata dei l'identità dell'utente. Il JWT contiene informazioni che includono il ID dell'Account Google, nome e indirizzo email.
scope Facoltativo:tutti gli ambiti che hai configurato per le richieste da parte di Google utenti.
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.

Per rispondere alle richieste di intent get, l'endpoint dello scambio di token deve eseguire i seguenti passaggi:

  • Convalida e decodifica l'asserzione JWT.
  • Verifica se l'Account Google è già presente nel sistema di autenticazione.
convalida e decodifica l'asserzione JWT

Puoi convalidare e decodificare l'asserzione JWT utilizzando un Libreria di decodifica JWT per la tua lingua. Utilizza le funzionalità di Chiavi pubbliche di Google, disponibili in JWK o formati PEM, per verificare la firma del token.

Una volta decodificata, l'asserzione JWT è simile all'esempio seguente: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Oltre a verificare la firma del token, verifica che l'asserzione l'emittente (campo iss) è https://accounts.google.com, che il pubblico (campo aud) è l'ID cliente che ti è stato assegnato e che il token non è scaduto (campo exp).

Utilizzando i campi email, email_verified e hd puoi determinare se Google ospita un indirizzo email ed è autorevole. Nei casi in cui Google ufficiale che l'utente sia attualmente noto per essere il legittimo proprietario dell'account e puoi saltare l'uso della password o altri metodi di verifica. In caso contrario, questi metodi può essere utilizzato per verificare l'account prima del collegamento.

Casi in cui Google è autorevole:

  • email ha un suffisso @gmail.com, questo è un account Gmail.
  • email_verified è true e hd è impostato, questo è un account G Suite.

Gli utenti possono registrarsi per creare Account Google senza utilizzare Gmail o G Suite. Quando email non contiene un suffisso @gmail.com e hd non è presente autoritativi e con password o altri metodi di verifica per verificare per l'utente. Il valore email_verified può anche essere vero perché Google ha verificato inizialmente il valore all'utente quando è stato creato l'account Google, ma la proprietà della terza parte l'account email potrebbe essere cambiato da allora.

Controllare se l'Account Google è già presente nel sistema di autenticazione

Controlla se è vera una delle seguenti condizioni:

  • L'ID Account Google, che si trova nel campo sub dell'asserzione, è nel tuo utente per configurare un database.
  • L'indirizzo email nell'asserzione corrisponde a un utente nel tuo database utenti.

Se viene trovato un account per l'utente, invia un token di accesso e restituisci i valori in un oggetto JSON nel corpo della risposta HTTPS, come nell'esempio seguente: 

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

In alcuni casi, il collegamento dell'account basato sul token ID potrebbe non riuscire per l'utente. Se lo fa per qualsiasi motivo, l'endpoint di scambio di token deve rispondere con un Errore 401 che specifica error=linking_error, come mostrato nell'esempio seguente:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Quando Google riceve una risposta di errore 401 con linking_error, invia l'utente all'endpoint di autorizzazione con login_hint come parametro. La l'utente completa il collegamento dell'account utilizzando il flusso di collegamento OAuth nel proprio browser.

Gestire la creazione dell'account utilizzando Accedi con Google (intent=create)

Quando un utente deve creare un account sul tuo servizio, Google invia una richiesta al tuo endpoint di scambio di token che specifica intent=create.

La richiesta ha il seguente formato:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT&client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET

L'endpoint di scambio di token deve essere in grado di gestire i seguenti parametri:

Parametri dell'endpoint token
intent Per queste richieste, il valore di questo parametro è create.
grant_type Il tipo di token scambiato. Per queste richieste, questo parametro ha 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 Account Google, il nome e l'indirizzo email dell'utente.
client_id L'ID client che hai assegnato a Google.
client_secret Il client secret che hai assegnato a Google.

Il JWT all'interno del parametro assertion contiene l'ID Account Google, il nome e l'indirizzo email dell'utente, che puoi utilizzare per creare un nuovo account sul tuo servizio.

Per rispondere alle richieste di intent create, l'endpoint di scambio di token deve eseguire i seguenti passaggi:

  • Convalidare e decodificare l'asserzione JWT.
  • Convalidare i dati dell'utente e creare un nuovo account.
convalida e decodifica l'asserzione JWT

Puoi convalidare e decodificare l'asserzione JWT utilizzando un Libreria di decodifica JWT per la tua lingua. Utilizza le funzionalità di Chiavi pubbliche di Google, disponibili in JWK o formati PEM, per verificare la firma del token.

Una volta decodificata, l'asserzione JWT è simile all'esempio seguente: 

{
  "sub": "1234567890",      // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The assertion's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
  "iat": 233366400,         // Unix timestamp of the assertion's creation time
  "exp": 233370000,         // Unix timestamp of the assertion's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "email_verified": true,   // true, if Google has verified the email address
  "hd": "example.com",      // If present, the host domain of the user's GSuite email address
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
  "locale": "en_US"         // User's locale, from browser or phone settings
}

Oltre a verificare la firma del token, verifica che l'asserzione l'emittente (campo iss) è https://accounts.google.com, che il pubblico (campo aud) è l'ID cliente che ti è stato assegnato e che il token non è scaduto (campo exp).

Utilizzando i campi email, email_verified e hd puoi determinare se Google ospita un indirizzo email ed è autorevole. Nei casi in cui Google ufficiale che l'utente sia attualmente noto per essere il legittimo proprietario dell'account e puoi saltare l'uso della password o altri metodi di verifica. In caso contrario, questi metodi può essere utilizzato per verificare l'account prima del collegamento.

Casi in cui Google è autorevole:

  • email ha un suffisso @gmail.com, questo è un account Gmail.
  • email_verified è true e hd è impostato, questo è un account G Suite.

Gli utenti possono registrarsi per creare Account Google senza utilizzare Gmail o G Suite. Quando email non contiene un suffisso @gmail.com e hd non è presente autoritativi e con password o altri metodi di verifica per verificare per l'utente. Il valore email_verified può anche essere vero perché Google ha verificato inizialmente il valore all'utente quando è stato creato l'account Google, ma la proprietà della terza parte l'account email potrebbe essere cambiato da allora.

Convalidare i dati dell'utente e creare un nuovo account

Verifica se è vera una delle due seguenti condizioni:

  • L'ID Account Google, che si trova nel campo sub dell'asserzione, è presente nel tuo database utenti.
  • L'indirizzo email nell'asserzione corrisponde a un utente nel tuo database utenti.

Se una delle due condizioni è vera, chiedi all'utente di collegare il suo account esistente al suo Account Google. Per farlo, rispondi alla richiesta con un errore HTTP 401 che specifica error=linking_error e indica l'indirizzo email dell'utente come login_hint. Di seguito è riportato un esempio di risposta:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

Quando Google riceve una risposta di errore 401 con linking_error, invia l'utente al tuo endpoint di autorizzazione con login_hint come parametro. L'utente completa il collegamento dell'account utilizzando il flusso di collegamento OAuth nel browser.

Se nessuna delle due condizioni è vera, crea un nuovo account utente con i dati forniti nel JWT. In genere, i nuovi account non hanno una password impostata. Ti consigliamo di aggiungere Accedi con Google ad altre piattaforme per consentire agli utenti di accedere con Google su tutte le piattaforme della tua applicazione. In alternativa, puoi inviare all'utente un'email con un link che avvia il flusso di recupero della password per consentirgli di impostare una password per accedere su altre piattaforme.

Al termine della creazione, emetti un token di accesso e restituisci i valori in un oggetto JSON nel corpo della risposta HTTPS, come nell'esempio seguente: 

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": SECONDS_TO_EXPIRATION
}

Recuperare l'ID client API di Google

Durante la procedura di registrazione del collegamento dell'account, ti verrà chiesto di fornire l'ID client API di Google.

Per recuperare l'ID client API utilizzando il progetto creato durante il completamento dei passaggi di collegamento OAuth: Per farlo, segui questa procedura.

  1. Vai alla pagina Client.

  2. Crea o seleziona un progetto API di Google.

    Se il progetto non ha un ID client per il tipo di applicazione web, fai clic su Crea client per crearne uno. Assicurati di includere il dominio del tuo sito nella casella Origini JavaScript autorizzate. Quando esegui test o sviluppo locali, devi aggiungere sia http://localhost sia http://localhost:<port_number> al campo Origini JavaScript autorizzate.

Convalidare l'implementazione

Puoi convalidare l'implementazione utilizzando lo strumento OAuth 2.0 Playground.

Nello strumento, segui questi passaggi:

  1. Fai clic su Configurazione per aprire la finestra di configurazione di OAuth 2.0.
  2. Nel campo Flusso OAuth, seleziona Lato client.
  3. Nel campo Endpoint OAuth, seleziona Personalizzato.
  4. Specifica l'endpoint OAuth 2.0 e l'ID client che hai assegnato a Google nei campi corrispondenti.
  5. Nella sezione Passaggio 1, non selezionare alcun ambito Google. Lascia invece questo campo vuoto o digita un ambito valido per il tuo server (o una stringa arbitraria se non utilizzi gli ambiti OAuth). Quando hai finito, fai clic su Autorizza API.
  6. Nelle sezioni Passaggio 2 e Passaggio 3, segui il flusso OAuth 2.0 e verifica che ogni passaggio funzioni come previsto.

Puoi convalidare l'implementazione utilizzando lo strumento Demo di collegamento dell'Account Google.

Nello strumento, segui questi passaggi:

  1. Fai clic sul pulsante Accedi con Google.
  2. Scegli l'account che vuoi collegare.
  3. Inserisci l'ID servizio.
  4. (Facoltativo) Inserisci uno o più ambiti per i quali richiederai l'accesso.
  5. Fai clic su Avvia demo.
  6. Quando richiesto, conferma che puoi dare il consenso e rifiutare la richiesta di collegamento.
  7. Verifica di essere reindirizzato alla tua piattaforma.