Collegamento semplificato con OAuth e Accedi con Google

Panoramica

Collegamento semplificato di Accedi con Google basato su OAuth aggiunge Accedi con Google in aggiunta al collegamento OAuth. In questo modo, gli utenti Google possono collegare facilmente i propri account e, se vogliono, possono creare un account sul tuo servizio utilizzando il proprio Account Google.

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

1. Per prima cosa, chiedi all'utente di dare il consenso per accedere al suo profilo Google.
2. Utilizza le informazioni nel 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. Se il tuo servizio supporta la creazione di account, puoi creare un utente in base alle informazioni del profilo contenute nel token ID.

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

Collegamento semplificato: flusso OAuth + Accedi con Google

Il seguente diagramma di sequenza descrive in dettaglio le interazioni tra l'utente, Google e l'endpoint di scambio di token per il collegamento semplificato.

Ruoli e responsabilità

La seguente tabella definisce i ruoli e le responsabilità degli attori nel flusso di collegamento semplificato.

Attore / componente	Ruolo GAL	Responsabilità
App / server Google	Client OAuth	Ottiene il consenso dell'utente per Accedi con Google, trasmette le asserzioni di identità (JWT) al tuo server e archivia in modo sicuro i token risultanti.
Endpoint di scambio token	Provider di identità / server di autorizzazione	Convalida le asserzioni di identità, verifica la presenza di account esistenti, gestisce gli intent di collegamento degli account richiesti (check, get) e l'intent facoltativo create ed emette token in base agli intent richiesti.
La tua API di servizio	Resource Server	Fornisce l'accesso ai dati utente quando viene presentato un token di accesso valido.

Requisiti per il collegamento semplificato

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

• Registra il tuo ID client API di Google.

Logica decisionale per il collegamento semplificato

La seguente logica determina come vengono chiamati gli intent durante il flusso di collegamento semplificato:

1. L'utente ha un account nel tuo sistema di autenticazione? (L'utente decide selezionando SÌ o NO)
   1. SÌ : l'utente utilizza l'email associata 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 la conferma)
         1. SÌ : viene chiamato l'intent get e l'account viene collegato se get intent viene restituito correttamente.
         2. NO : Create New Account? (L'utente decide selezionando SÌ o NO; applicabile solo se il tuo servizio supporta la creazione di account)
            1. SÌ : viene chiamato l'intent create e l'account viene collegato se l'intent di creazione viene restituito correttamente.
            2. NO : viene attivato il flusso di collegamento OAuth, l'utente viene indirizzato al browser e gli viene data la possibilità di collegarsi con un'altra email.
      2. NO : viene attivato il flusso di collegamento OAuth, l'utente viene indirizzato al browser e gli viene data la possibilità di collegarsi con un'altra email.
   2. NO : l'utente ha un account corrispondente nel tuo sistema di autenticazione? (check intent viene chiamato per la conferma)
      1. SÌ : viene chiamato l'intent get e l'account viene collegato se get intent viene restituito correttamente.
      2. NO : se il tuo servizio supporta la creazione di account, viene chiamato l'intent create e l'account viene collegato se l'intent di creazione viene restituito correttamente. Se la creazione dell'account non è supportata, l'endpoint deve restituire l'errore HTTP 401 linking_error per attivare il flusso di collegamento OAuth di riserva.

Implementation Recipe

L'endpoint di scambio di token deve implementare gli intent check e get richiesti e, facoltativamente, l'intent create per supportare il collegamento semplificato.

Segui questi passaggi per gestire i diversi intent:

Check for an existing user account (check intent)

Google calls your token exchange endpoint to verify if the Google user exists in your system. For parameter details, see Streamlined Linking Intents.

Implementation Recipe

To handle the required check intent, perform the following actions:

1. Validate the request:

   • Verify client_id, client_secret, and grant_type (must be urn:ietf:params:oauth:grant-type:jwt-bearer).
   • Validate the assertion (JWT) using the criteria in JWT Validation.

2. Lookup user:

   • Check if the Google Account ID (sub) or email address in the JWT matches a user in your database.

3. Respond:

   • If found: Return HTTP 200 OK with {"account_found": "true"}.
   • If not found: Return HTTP 404 Not Found with {"account_found": "false"}.

Gestire il collegamento automatico (ottenere intent)

Se l'account esiste, Google chiama il tuo endpoint con intent=get per recuperare i token. Per i dettagli dei parametri, consulta Intent di collegamento semplificati.

Recipe di implementazione

Per gestire l'intent get richiesto, esegui le seguenti azioni:

1. Convalida la richiesta:

   • Verifica client_id, client_secret e grant_type.
   • Convalida l'assertion (JWT).

2. Cerca l'utente:

   • Verifica che l'utente esista utilizzando l'attestazione sub o email.

3. Reagisci:

   • In caso di esito positivo: genera e restituisci access_token, refresh_token e expires_in in una risposta JSON (HTTP 200 OK).
   • Se il collegamento non riesce: restituisci HTTP 401 Unauthorized con {"error": "linking_error"} e un login_hint facoltativo per eseguire il fallback al collegamento OAuth standard.

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

Se il tuo servizio supporta la creazione di account e non ne esiste nessuno, Google chiama il tuo endpoint con intent=create per creare un nuovo utente. Per i dettagli sui parametri, consulta Intent di collegamento semplificato.

Implementation Recipe

Per gestire l'intent create facoltativo, esegui le seguenti azioni:

1. Convalida la richiesta:

   • Verifica client_id, client_secret e grant_type.
   • Convalida assertion (JWT).

2. Verifica che l'utente non esista:

   • Controlla se sub o email è già presente nel tuo database.
   • Se l'utente esiste: restituisci HTTP 401 Unauthorized con {"error": "linking_error", "login_hint": "USER_EMAIL"} per forzare il fallback al collegamento OAuth.

3. Crea account:

   • Utilizza le attestazioni sub, email, name e picture del JWT per creare un nuovo record utente.

4. Rispondi:

   • Genera e restituisce token in una risposta JSON (HTTP 200 OK).

Ottenere l'ID client API di Google

Ti verrà chiesto di fornire l'ID client API di Google durante la procedura di registrazione del collegamento degli account. Per ottenere l'ID client API utilizzando il progetto che hai creato durante il completamento dei passaggi di collegamento OAuth. Per farlo, completa i seguenti passaggi:

1. Vai alla pagina Clienti.

2. Crea o seleziona un progetto API di Google.

   Se il tuo 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 locali o sviluppo, devi aggiungere sia http://localhost sia http://localhost:<port_number> al campo Origini JavaScript autorizzate.

Convalidare l'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.