Collegamento semplificato con OAuth e Accedi con Google

Panoramica

Il collegamento semplificato di Accedi con Google basato su OAuth aggiunge Accedi con Google oltre ad altre funzionalità. Collegamento OAuth. Ciò fornisce un'esperienza di collegamento perfetta per Per gli utenti Google e consente anche la creazione di account, che consente all'utente di 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 queste informazioni generali passaggi:

1. Per prima cosa, chiedi all'utente di dare il consenso per accedere al suo profilo Google.
2. Utilizzare le informazioni presenti nel profilo dell'utente 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, convalidare il token ID ricevuto da Google. Puoi quindi creare un'interfaccia utente nelle informazioni del profilo contenute nel token ID.

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

Requisiti per il collegamento semplificato

• Implementare il flusso di collegamento OAuth web di base. Il servizio deve supportare la conformità a OAuth 2.0 endpoint di autorizzazione e di scambio di token.
• L'endpoint di scambio di token deve supportare le asserzioni del token web JSON (JWT) e implementare gli intent check, create e get.

• Registra il tuo ID client API di Google.

Implementare il server OAuth

L'endpoint per lo scambio di token deve supportare gli intent check, create e get. Di seguito sono riportati i passaggi completati durante la procedura di collegamento dell'account e viene indicato quando vengono richiamati i diversi intent:

1. L'utente dispone di un account nel tuo sistema di autenticazione? (L'utente decide selezionando SÌ o NO)
   1. SÌ : l'utente utilizza l'indirizzo email associato al proprio Account Google per accedere alla piattaforma? (L'utente decide selezionando SÌ o NO)
      1. SÌ : l'utente dispone di 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 la richiesta di ritorno per intenzione riesce.
         2. NO : creare un nuovo account? (L'utente decide selezionando SÌ o NO)
            1. SÌ : create intent viene chiamato e l'account viene collegato se la funzionalità di creazione dell'intent viene restituita correttamente.
            2. NO : viene attivato il flusso OAuth per il web, l'utente viene indirizzato al browser e gli viene offerta la possibilità di collegarsi a un indirizzo email diverso.
      2. NO : viene attivato il flusso OAuth web, l'utente viene indirizzato al browser e gli viene offerta la possibilità di collegarsi a un'altra email.
   2. NO : l'utente dispone di 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 la richiesta di ritorno per intenzione riesce.
      2. NO : create intent viene chiamato e l'account viene collegato se la funzionalità di creazione dell'intent viene restituita correttamente.

Check for an existing user account (check intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google account is already present in your authentication system, your token exchange endpoint responds with account_found=true. If the Google account doesn't match an existing user, your token exchange endpoint returns an HTTP 404 Not Found error with account_found=false.

The request has the following form:

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

Your token exchange endpoint must be able to handle the following parameters:

To respond to the check intent requests, your token exchange endpoint must perform the following steps:

• Validate and decode the JWT assertion.
• Check if the Google account is already present in your authentication system.

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If either condition is true, the user has already signed up. In that case, return a response like the following:

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

{
  "account_found":"true",
}

If neither the Google Account ID nor the email address specified in the assertion matches a user in your database, the user hasn't signed up yet. In this case, your token exchange endpoint needs to reply with a HTTP 404 error that specifies "account_found": "false", as in the following example:

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

{
  "account_found":"false",
}

Handle automatic linking (get intent)

After the user gives consent to access their Google profile, Google sends a request that contains a signed assertion of the Google user's identity. The assertion contains information that includes the user's Google Account ID, name, and email address. The token exchange endpoint configured for your project handles that request.

If the corresponding Google Account is already present in your authentication system, your token exchange endpoint returns a token for the user. If the Google Account doesn't match an existing user, your token exchange endpoint returns a linking_error error and optional login_hint.

The request has the following form:

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

Your token exchange endpoint must be able to handle the following parameters:

To respond to the get intent requests, your token exchange endpoint must perform the following steps:

• Validate and decode the JWT assertion.
• Check if the Google account is already present in your authentication system.

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Check if the Google account is already present in your authentication system

Check whether either of the following conditions are true:

• The Google Account ID, found in the assertion's sub field, is in your user database.
• The email address in the assertion matches a user in your user database.

If an account is found for the user, issue an access token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

In some cases, account linking based on ID token might fail for the user. If it does so for any reason, your token exchange endpoint needs to reply with a HTTP 401 error that specifies error=linking_error, as the following example shows:

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

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

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

Gestire la creazione di account tramite Accedi con Google (creazione di un intent)

Quando un utente deve creare un account nel tuo servizio, Google effettua una richiesta all'endpoint di scambio di token che specifica intent=create.

La richiesta ha il seguente modulo:

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:

Il JWT all'interno del parametro assertion contiene l'ID dell'Account Google dell'utente, nome e indirizzo email che potrai utilizzare per creare un nuovo account sul tuo completamente gestito di Google Cloud.

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

• Convalida e decodifica l'asserzione JWT.
• Convalida le informazioni dell'utente e crea un nuovo account.

Validate and decode the JWT assertion

You can validate and decode the JWT assertion by using a JWT-decoding library for your language. Use Google's public keys, available in JWK or PEM formats, to verify the token's signature.

When decoded, the JWT assertion looks like the following example:

{
  "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
}

In addition to verifying the token's signature, verify that the assertion's issuer (iss field) is https://accounts.google.com, that the audience (aud field) is your assigned client ID, and that the token has not expired (exp field).

Using the email, email_verified and hd fields you can determine if Google hosts and is authoritative for an email address. In cases where Google is authoritative the user is currently known to be the legitimate account owner and you may skip password or other challenges methods. Otherwise, these methods can be used to verify the account prior to linking.

Cases where Google is authoritative:

• email has a @gmail.com suffix, this is a Gmail account.
• email_verified is true and hd is set, this is a G Suite account.

Users may register for Google Accounts without using Gmail or G Suite. When email does not contain a @gmail.com suffix and hd is absent Google is not authoritative and password or other challenge methods are recommended to verify the user. email_verified can also be true as Google initially verified the user when the Google account was created, however ownership of the third party email account may have since changed.

Convalida le informazioni dell'utente e crea un nuovo account

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, chiedi all'utente di collegare il suo account esistente con il proprio Account Google. Per farlo, 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 è 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 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.

Se nessuna delle due condizioni è vera, crea un nuovo account utente con le informazioni forniti nel JWT. In genere per i nuovi account non è impostata una password. È ti consigliamo di aggiungere 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 la procedura di recupero della password per consentire di impostare una password per accedere su altre piattaforme.

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

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

Ottenere l'ID client API di Google

Ti verrà chiesto di fornire il tuo ID client API di Google durante la procedura di registrazione al collegamento degli account.

Per ottenere il tuo ID client API tramite il progetto che hai creato durante il completamento dei passaggi di collegamento OAuth. Per farlo, segui questa procedura.

1. Apri la pagina Credentials (Credenziali) della Console API di Google.

2. Crea o seleziona un progetto delle API di Google.

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

Convalida dell'implementazione

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

1. Click Configuration settings to open the OAuth 2.0 Configuration window.
2. In the OAuth flow field, select Client-side.
3. In the OAuth Endpoints field, select Custom.
4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

1. Click the Sign-in with Google button.
2. Choose the account you'd like to link.
3. Enter the service ID.
4. Optionally enter one or more scopes that you will request access for.
5. Click Start Demo.
6. When prompted, confirm that you may consent and deny the linking request.
7. Confirm that you are redirected to your platform.