Questa pagina è stata tradotta dall'API Cloud Translation.

Collegamento semplificato con OAuth e Accedi con Google

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.

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 e get.

Registra il tuo ID client API di Google.

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)
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Ì : viene richiamato get intent e l'account viene collegato se l'intent viene restituito correttamente.
    2. NO : vuoi creare un nuovo account? (L'utente decide selezionando SÌ o NO)
      1. SÌ : viene richiamato create intent e l'account viene collegato se la creazione dell'intent è riuscita.
      2. 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.
  2. 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.
2. NO : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (check intent viene chiamato per confermare)
  1. SÌ : viene richiamato get intent e l'account viene collegato se l'intent viene restituito correttamente.
  2. NO: viene richiamato create intent e l'account viene collegato se la creazione dell'intent ha esito positivo.

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 una libreria di decodifica JWT per la tua lingua . Utilizza le chiavi pubbliche di Google, disponibili nei formati JWK o PEM , per verificare la firma del token.

Quando viene decodificata, l'asserzione JWT ha l'aspetto 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'emittente dell'asserzione (campo iss ) sia https://accounts.google.com , che il pubblico (campo aud ) sia l'ID client assegnato e che il token non sia scaduto ( exp campo).

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

Casi in cui Google è autorevole:

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

Gli utenti possono registrarsi per gli account Google senza utilizzare Gmail o G Suite. Quando l' email non contiene un suffisso @gmail.com e hd è assente, Google non è autorevole e si consigliano password o altri metodi di verifica per verificare l'utente. email_verfied può anche essere vero poiché Google ha verificato inizialmente l'utente quando è stato creato l'account Google, tuttavia la proprietà dell'account di posta elettronica di terze parti potrebbe essere cambiata 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",
}

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:

Token endpoint parameters
`intent`	For these requests, the value of this parameter is `get`.
`grant_type`	The type of token being exchanged. For these requests, this parameter has the value `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
`scope`	Optional: Any scopes that you've configured Google to request from users.
`client_id`	The client ID you assigned to Google.
`client_secret`	The client secret you assigned to Google.

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.

Convalida e decodifica l'asserzione JWT

Quando viene decodificata, l'asserzione JWT ha l'aspetto 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
}

Casi in cui Google è autorevole:

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

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.

Handle account creation via Google Sign-In (create intent)

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create.

The request has the following form:

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

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

Token endpoint parameters
`intent`	For these requests, the value of this parameter is `create`.
`grant_type`	The type of token being exchanged. For these requests, this parameter has the value `urn:ietf:params:oauth:grant-type:jwt-bearer`.
`assertion`	A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.
`client_id`	The client ID you assigned to Google.
`client_secret`	The client secret you assigned to Google.

The JWT within the assertion parameter contains the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

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

Validate and decode the JWT assertion.
Validate user information and create new account.

Convalida e decodifica l'asserzione JWT

Quando viene decodificata, l'asserzione JWT ha l'aspetto 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
}

Casi in cui Google è autorevole:

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

Validate user information and create new account

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, prompt the user to link their existing account with their Google Account. To do so, respond to the request with an HTTP 401 error that specifies error=linking_error and gives the user's email address as the login_hint. The following is a sample response:

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

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

If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.

When the creation is completed, 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
}

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 che http://localhost:<port_number> nel campo Origini JavaScript autorizzate.

Punto chiave: aggiungi sia http://localhost che http://localhost:<port_number> al campo Origini JavaScript autorizzate per eseguire test o sviluppo locali.
Nota: un ID client è simile al seguente esempio:
```
1234567890-abc123def456.apps.googleusercontent.com
```

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.