Panoramica
Il collegamento semplificato di Accedi con Google basato su OAuth aggiunge la funzionalità Accedi con Google oltre a Collegamento OAuth. In questo modo puoi garantire agli utenti di Google un'esperienza di collegamento senza soluzione di continuità e puoi anche creare un account che consente di creare sul tuo servizio un nuovo account utilizzando l'Account Google.
Per eseguire il collegamento dell'account con OAuth e Accedi con Google, segui questi passaggi generali:
- Innanzitutto, chiedi all'utente di acconsentire all'accesso al suo profilo Google.
- Utilizzare le informazioni del profilo per verificare se l'account utente esiste.
- Per gli utenti esistenti, collega gli account.
- Se non riesci a trovare una corrispondenza per l'utente Google nel tuo sistema di autenticazione, convalida il token ID ricevuto da Google. Poi, potrai creare un utente in base alle informazioni del profilo contenute nel token ID.
![Questa figura mostra i passaggi per collegare un account Google all'utente utilizzando il flusso di collegamento semplificato. Il primo screenshot mostra in che modo un utente può selezionare la tua app per il collegamento. Il secondo screenshot consente all'utente di confermare se dispone o meno di un account sul tuo servizio. Il terzo screenshot consente all'utente di selezionare l'Account Google a cui vuole collegarsi. 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.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/account-linking/images/streamlined-linking-flow.png?authuser=6&hl=it)
Figura 1. Collegamento dell'account sul telefono di un utente con il Collegamento semplificato
Requisiti per il collegamento semplificato
- Implementare il flusso di base del collegamento OAuth web. Il servizio deve supportare gli endpoint di autorizzazione e scambio di token conformi a OAuth 2.0.
- L'endpoint di token Exchange deve supportare le asserzioni di JSON Web Token (JWT) e implementare gli intent
check
,create
eget
.
Implementare il server OAuth
L'endpoint di scambio di token deve supportare gli intent check
, create
e get
. Di seguito sono riportati i passaggi completati tramite il flusso di collegamento dell'account e indicano quando vengono chiamati i diversi intent:
- L'utente ha un account nel tuo sistema di autenticazione? (L'utente decide selezionando SÌ o NO)
- SÌ : l'utente utilizza l'indirizzo email associato al suo Account Google per accedere alla tua piattaforma? (L'utente decide selezionando SÌ o NO)
- SÌ : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (
check intent
viene chiamato per confermare)- SÌ : viene richiamato
get intent
e l'account viene collegato se l'intent viene restituito correttamente. - NO : vuoi creare un nuovo account? (L'utente decide selezionando SÌ o NO)
- SÌ : viene richiamato
create intent
e l'account viene collegato se la creazione dell'intent è riuscita. - NO : viene attivato il flusso OAuth web, l'utente viene indirizzato al proprio browser e l'utente ha la possibilità di creare un link con un indirizzo email diverso.
- SÌ : viene richiamato
- SÌ : viene richiamato
- NO : viene attivato il flusso OAuth web. L'utente viene indirizzato al proprio browser e l'utente ha la possibilità di creare un link con un indirizzo email diverso.
- SÌ : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (
- NO : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (
check intent
viene chiamato per confermare)- SÌ : viene richiamato
get intent
e l'account viene collegato se l'intent viene restituito correttamente. - NO: viene richiamato
create intent
e l'account viene collegato se la creazione dell'intent ha esito positivo.
- SÌ : viene richiamato
- SÌ : l'utente utilizza l'indirizzo email associato al suo Account Google per accedere alla tua piattaforma? (L'utente decide selezionando SÌ o NO)
Verificare la presenza di un account utente esistente (intent di verifica)
Dopo che l'utente dà il consenso ad accedere al proprio profilo Google, Google invia una richiesta contenente un'affermazione firmata dell'identità dell'utente Google. L'asserzione contiene informazioni che includono l'ID account Google, il nome e l'indirizzo email dell'utente. L'endpoint di scambio di token configurato per il tuo progetto gestisce questa richiesta.
Se l'Account Google corrispondente è già presente nel tuo sistema di autenticazione, l'endpoint di scambio di token risponde con account_found=true
. Se l'Account Google non corrisponde a un utente esistente, l'endpoint di scambio di token restituisce un errore HTTP 404 (Risorsa non trovata) con account_found=false
.
La richiesta ha il seguente formato:
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 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 una dichiarazione 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. |
Per rispondere alle richieste di intent check
, l'endpoint di scambio di token deve eseguire i seguenti passaggi:
- Convalida e decodifica l'asserzione JWT.
- Controlla se l'Account Google è già presente nel tuo 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 ehd
è 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.
Controlla se l'Account Google è già presente nel tuo sistema di autenticazione
Controlla se una delle seguenti condizioni è vera:
- L'ID dell'Account Google, che si trova nel campo
sub
dell'asserzione, si trova nel database utente. - L'indirizzo email nell'asserzione corrisponde a un utente nel database degli utenti.
Se una delle condizioni è vera, l'utente si è già registrato. In questo caso, restituisci una risposta simile alla seguente:
HTTP/1.1 200 Success Content-Type: application/json;charset=UTF-8 { "account_found":"true", }
Se né l'ID dell'Account Google né l'indirizzo email specificato nell'istruzione corrispondono a un utente nel database, l'utente non si è ancora registrato. 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 (mostrare l'intenzione)
Dopo che l'utente dà il consenso ad accedere al proprio profilo Google, Google invia una richiesta contenente un'affermazione firmata dell'identità dell'utente Google. L'asserzione contiene informazioni che includono l'ID account Google, il nome e l'indirizzo email dell'utente. L'endpoint di scambio di token configurato per il tuo progetto gestisce questa richiesta.
Se l'Account Google corrispondente è già presente nel sistema di autenticazione, l'endpoint di scambio di token restituisce un token per l'utente. Se l'Account Google non corrisponde a un utente esistente, l'endpoint di scambio di token restituisce un errore linking_error
e un login_hint
facoltativo.
La richiesta ha il seguente formato:
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 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 una dichiarazione firmata dell'identità dell'utente Google. Il JWT contiene informazioni che includono l'ID account Google, il nome e l'indirizzo email dell'utente. |
scope |
Facoltativo: gli ambiti che hai configurato su Google per richiedere gli 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 di scambio di token deve eseguire i seguenti passaggi:
- Convalida e decodifica l'asserzione JWT.
- Controlla se l'Account Google è già presente nel tuo 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 ehd
è 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.
Controlla se l'Account Google è già presente nel tuo sistema di autenticazione
Controlla se una delle seguenti condizioni è vera:
- L'ID dell'Account Google, che si trova nel campo
sub
dell'asserzione, si trova nel database utente. - L'indirizzo email nell'asserzione corrisponde a un utente nel database degli 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, ad esempio nell'esempio seguente:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
In alcuni casi, il collegamento dell'account basato sul token ID potrebbe non riuscire per l'utente. Se per qualche motivo questo accade, l'endpoint di scambio di token deve rispondere con un errore HTTP 401 che specifica error=linking_error
, come illustrato 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 al tuo endpoint di autorizzazione con login_hint
come parametro. L'utente completa il collegamento dell'account utilizzando il flusso di collegamento OAuth del browser.
Gestire la creazione dell'account tramite Accedi con Google (creare un intent)
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 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 una dichiarazione 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, il nome e l'indirizzo email
dell'Account Google 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:
- Convalida e decodifica l'asserzione JWT.
- Convalidare le informazioni degli utenti 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 ehd
è 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 le informazioni degli utenti e creare un nuovo account
Controlla se una delle seguenti condizioni è vera:
- L'ID dell'Account Google, che si trova nel campo
sub
dell'asserzione, si trova nel database utente. - L'indirizzo email nell'asserzione corrisponde a un utente nel database degli utenti.
Se una delle condizioni è vera, chiedi all'utente di collegare il proprio account esistente al proprio Account Google. A tale scopo, rispondi alla richiesta con un errore HTTP 401 che
specifica error=linking_error
e fornisce l'indirizzo email dell'utente come
login_hint
. Di seguito è riportata una risposta di esempio:
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 del browser.
Se nessuna delle condizioni è vera, crea un nuovo account utente con le informazioni fornite in JWT. Solitamente per i nuovi account non è impostata una password. Ti consigliamo di aggiungere l'opzione Accedi con Google ad altre piattaforme per consentire agli utenti di accedere con Google sulle piattaforme della tua applicazione. In alternativa, puoi inviare all'utente via email un link che avvia il flusso di recupero della password per consentire all'utente di impostare una password per accedere su altre piattaforme.
Una volta completata la creazione, invia un token di accesso e restituisce i valori in un oggetto JSON nel corpo della risposta HTTPS, come nell'esempio seguente:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Ottenere il tuo ID client API di Google
Durante la procedura di registrazione al collegamento dell'account, ti verrà chiesto di fornire il tuo ID client API di Google.
Per ottenere il tuo ID client API tramite il progetto che hai creato durante la procedura di collegamento OAuth. Per farlo, segui questa procedura.
- Apri la pagina Credenziali della console API di Google.
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 credenziali > ID client OAuth 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
chehttp://localhost:<port_number>
nel campo Origini JavaScript autorizzate.
Convalidare l'implementazione
È possibile convalidare l'implementazione utilizzando il parco giochi OAuth 2.0 strumento.
Nello strumento, eseguire le seguenti operazioni:
- Fare clic su Configurazione per aprire la finestra di configurazione OAuth 2.0.
- Nel campo di flusso OAuth, selezionare sul lato client.
- Nel campo OAuth endpoint, selezionare Personalizzato.
- Specifica il tuo endpoint OAuth 2.0 e l'ID client che hai assegnato a Google nei campi corrispondenti.
- Nella sezione Passaggio 1, non selezionare tutti gli ambiti di Google. Lascia invece vuoto questo campo o digita un ambito valido per il tuo server (o una stringa arbitraria se non utilizzi gli ambiti OAuth). Quando hai finito, clicca API Autorizza.
- Nelle sezioni Fase 2 e Fase 3, passare attraverso il flusso OAuth 2.0 e verificare che ogni passo funziona come previsto.
È possibile convalidare l'implementazione utilizzando l' account Google Linking Demo strumento.
Nello strumento, eseguire le seguenti operazioni:
- Fare clic sul segno-in con pulsante di Google.
- Scegli l'account che desideri collegare.
- Inserisci l'ID del servizio.
- Facoltativamente, inserisci uno o più ambiti per i quali richiedere l'accesso.
- Fare clic su Start Demo.
- Quando richiesto, conferma che puoi acconsentire e negare la richiesta di collegamento.
- Conferma di essere reindirizzato alla tua piattaforma.