Collegamento dell'Account Google a OAuth

I collegamenti degli account vengono eseguiti utilizzando i flussi implicito e codice di autorizzazione OAuth 2.0 standard del settore.

Il tuo servizio deve supportare gli endpoint di autorizzazione e scambio di token conformi a OAuth 2.0.

Nel flusso implicito, Google apre l'endpoint di autorizzazione nel browser dell'utente. Dopo aver eseguito l'accesso, restituisci a Google un token di accesso di lunga durata. Questo token di accesso è ora incluso in ogni richiesta inviata da Google.

Nel flusso del codice di autorizzazione, sono necessari due endpoint:

L'endpoint di autorizzazione, che mostra l'interfaccia utente di accesso agli utenti che non hanno ancora eseguito l'accesso. L'endpoint di autorizzazione crea anche un codice di autorizzazione di breve durata per registrare il consenso degli utenti all'accesso richiesto.
L'endpoint di scambio di token, che è responsabile di due tipi di scambi:
1. Scambia un codice di autorizzazione con un token di aggiornamento a lunga durata e un token di accesso a breve durata. Questo scambio avviene quando l'utente segue il flusso di collegamento dell'account.
2. Scambia un token di aggiornamento di lunga durata con un token di accesso di breve durata. Questo scambio avviene quando Google ha bisogno di un nuovo token di accesso perché quello precedente è scaduto.

Scegliere un flusso OAuth 2.0

Sebbene il flusso implicito sia più semplice da implementare, Google consiglia che i token di accesso emessi dal flusso implicito non scadano mai. Questo perché l'utente è costretto a collegare nuovamente il proprio account dopo la scadenza di un token con il flusso implicito. Se hai bisogno della scadenza del token per motivi di sicurezza, ti consigliamo vivamente di utilizzare invece il flusso del codice di autorizzazione.

Istruzioni sul design

Questa sezione descrive i requisiti e i consigli di progettazione per la schermata utente che ospiti per i flussi di collegamento OAuth. Dopo essere stata chiamata dall'app di Google, la tua piattaforma mostra all'utente una pagina di accesso a Google e una schermata di consenso per il collegamento dell'account. Dopo aver dato il consenso per collegare gli account, l'utente viene reindirizzato all'app di Google.

Questa figura mostra i passaggi che un utente deve seguire per collegare il proprio Account Google
al tuo sistema di autenticazione. Il primo screenshot mostra
il collegamento avviato dall'utente dalla tua piattaforma. La seconda immagine mostra
l'accesso dell'utente a Google, mentre la terza mostra il consenso dell'utente e
la conferma dell'utente per il collegamento del suo Account Google alla tua app. Lo
screenshot finale mostra un account utente collegato correttamente nell'app
Google. — **Figura 1.** Schermate di accesso e consenso dell'utente per il collegamento dell'account.

Requisiti

Devi comunicare che l'account dell'utente verrà collegato a Google, non a un prodotto Google specifico come Google Home o l'Assistente Google.

Consigli

Ti consigliamo di procedere come segue:

Visualizza le Norme sulla privacy di Google. Includi un link alle Norme sulla privacy di Google nella schermata per il consenso.
Dati da condividere. Utilizza un linguaggio chiaro e conciso per comunicare all'utente quali dati di sua proprietà sono richiesti da Google e perché.
Invito all'azione chiaro. Indica un invito all'azione chiaro nella schermata del consenso, ad esempio "Accetta e collega". Questo perché gli utenti devono capire quali dati sono tenuti a condividere con Google per collegare i propri account.
Possibilità di annullare l'abbonamento. Fornisci agli utenti un modo per tornare indietro o annullare se scelgono di non collegare l'account.
Procedura di accesso chiara. Assicurati che gli utenti dispongano di un metodo chiaro per accedere al proprio Account Google, ad esempio campi per il nome utente e la password o Accedi con Google.
Possibilità di scollegare. Offri agli utenti un meccanismo per scollegare gli account, ad esempio un URL alle impostazioni dell'account sulla tua piattaforma. In alternativa, puoi includere un link all'Account Google in cui gli utenti possono gestire il proprio account collegato.
Possibilità di cambiare account utente. Suggerisci un metodo per consentire agli utenti di cambiare i propri account. Ciò è particolarmente utile se gli utenti tendono ad avere più account.
- Se un utente deve chiudere la schermata per il consenso per cambiare account, invia un errore recuperabile a Google in modo che l'utente possa accedere all'account desiderato con il collegamento OAuth e il flusso implicito.
Includi il tuo logo. Mostra il logo della tua azienda nella schermata per il consenso. Utilizza le linee guida di stile per posizionare il logo. Se vuoi mostrare anche il logo di Google, consulta Loghi e marchi.

Create the project

To create your project to use account linking:

Go to the Google API Console.
Click Create project.
Enter a name or accept the generated suggestion.
Confirm or edit any remaining fields.
Click Create.

To view your project ID:

Go to the Google API Console.
Find your project in the table on the landing page. The project ID appears in the ID column.

Configure your OAuth Consent Screen

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

Open the OAuth consent screen page of the Google APIs console.
If prompted, select the project you just created.
On the "OAuth consent screen" page, fill out the form and click the “Save” button.

Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

Support email: For users to contact you with questions about their consent.

Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery
Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

Implementare il server OAuth

Per supportare il flusso implicito OAuth 2.0, il tuo servizio rende disponibile un endpoint di autorizzazione tramite HTTPS. Questo endpoint è responsabile dell'autenticazione e dell'ottenimento del consenso degli utenti per l'accesso ai dati. L'endpoint di autorizzazione presenta un'interfaccia utente di accesso agli utenti che non hanno ancora eseguito l'accesso e registra il consenso all'accesso richiesto.

Quando un'applicazione Google deve chiamare una delle API autorizzate del tuo servizio, Google utilizza questo endpoint per ottenere l'autorizzazione dagli utenti a chiamare queste API per loro conto.

Collegamento dell'Account Google: flusso implicito OAuth

Il seguente diagramma di sequenza descrive in dettaglio le interazioni tra l'utente, Google e gli endpoint del tuo servizio.

Figure 1. La sequenza di eventi nel flusso implicito OAuth 2.0 per il collegamento dell'Account Google.

Ruoli e responsabilità

La tabella seguente definisce i ruoli e le responsabilità degli attori nel flusso implicito OAuth di collegamento dell'Account Google (GAL). Tieni presente che in GAL Google funge da client OAuth, mentre il tuo servizio funge da provider di identità/servizi.

Attore / componente	Ruolo GAL	Responsabilità
App / server Google	Client OAuth	Avvia il flusso, riceve il token di accesso utilizzando un reindirizzamento del browser, e lo archivia in modo sicuro per accedere alle API del tuo servizio.
Endpoint di autorizzazione	Server di autorizzazione	Autentica gli utenti, ottiene il loro consenso ed emette token di accesso di lunga durata accesso direttamente a Google.
URI di reindirizzamento di Google	Endpoint di richiamata	Riceve il reindirizzamento dell'utente dal tuo servizio di autorizzazione con i `access_token` e `state` valori nel frammento dell'URL.

Una sessione tipica del flusso implicito OAuth 2.0 avviata da Google ha il seguente flusso:

Google apre l'endpoint di autorizzazione nel browser dell'utente. L'utente esegue l'accesso, se non l'ha già fatto, e concede a Google l'autorizzazione ad accedere ai suoi dati con la tua API, se non l'ha già fatto.
Il tuo servizio crea un token di accesso e lo restituisce a Google. Per farlo, reindirizza il browser dell'utente a Google con il token di accesso allegato alla richiesta.
Google chiama le API del tuo servizio e allega il token di accesso a ogni richiesta. Il tuo servizio verifica che il token di accesso conceda a Google l'autorizzazione ad accedere all'API e completa la chiamata API.

Gestire le richieste di autorizzazione

Quando un'applicazione Google deve eseguire il collegamento dell'account utilizzando un flusso implicito OAuth 2.0, Google invia l'utente all'endpoint di autorizzazione con una richiesta che include i seguenti parametri:

Parametri dell'endpoint di autorizzazione
`client_id`	L'ID client che hai assegnato a Google.
`redirect_uri`	L'URL a cui invii la risposta a questa richiesta.
`state`	Un valore di riferimento che viene restituito a Google senza modifiche nell' URI di reindirizzamento.
`response_type`	Il tipo di valore da restituire nella risposta. Per il flusso implicito OAuth 2.0 il tipo di risposta è sempre `token`.
`user_locale`	L'impostazione della lingua dell'Account Google in RFC5646 formato utilizzata per localizzare i contenuti nella lingua preferita dell'utente.

Ad esempio, se l'endpoint di autorizzazione è disponibile all'indirizzo https://myservice.example.com/auth, una richiesta potrebbe avere il seguente aspetto:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

Per consentire all'endpoint di autorizzazione di gestire le richieste di accesso:

Verifica i valori client_id e redirect_uri per impedire la concessione dell'accesso ad app client non intenzionali o configurate in modo errato:
- Verifica che client_id corrisponda all'ID client che hai assegnato a Google.
- Verifica che l'URL specificato dal parametro redirect_uri abbia il seguente formato:
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
```
Controlla se l'utente ha eseguito l'accesso al tuo servizio. Se l'utente non ha eseguito l'accesso, completa il flusso di accesso o registrazione del tuo servizio.
Genera un token di accesso che Google possa utilizzare per accedere alla tua API. Il token di accesso può essere qualsiasi valore stringa, ma deve rappresentare in modo univoco l' utente e il client per cui è destinato e non deve essere intuibile.
Invia una risposta HTTP che reindirizza il browser dell'utente all'URL specificato dal parametro redirect_uri. Includi tutti i seguenti parametri nel frammento di URL:
- access_token: il token di accesso appena generato
- token_type: la stringa bearer
- state: il valore dello stato non modificato della richiesta originale
Di seguito è riportato un esempio dell'URL risultante:
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING
```

Il gestore di reindirizzamento OAuth 2.0 di Google riceve il token di accesso e conferma che il valore state non è cambiato. Dopo che Google ha ottenuto un token di accesso per il tuo servizio, lo allega alle chiamate successive alle API del tuo servizio.

Gestire le richieste di informazioni utente

L'endpoint userinfo è una risorsa protetta da OAuth 2.0 che restituisce attestazioni sull'utente collegato. L'implementazione e l'hosting dell'endpoint userinfo sono facoltative, ad eccezione dei seguenti casi d'uso:

Accesso a un account collegato con Google One Tap.
Abbonamento senza problemi su AndroidTV.

Dopo che il token di accesso è stato recuperato correttamente dall'endpoint del token, Google invia una richiesta all'endpoint userinfo per recuperare le informazioni di base del profilo dell'utente collegato.

intestazioni delle richieste endpoint userinfo
`Authorization header`	Il token di accesso di tipo Bearer.

Ad esempio, se l'endpoint userinfo è disponibile su https://myservice.example.com/userinfo, una richiesta potrebbe avere il seguente aspetto:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Affinché l'endpoint userinfo possa gestire le richieste, segui questi passaggi:

Estrai il token di accesso dall'intestazione Autorizzazione e restituisci le informazioni per l'utente associato al token di accesso.
Se il token di accesso non è valido, restituisce un errore HTTP 401 Autorizzazione non autorizzata utilizzando l'intestazione della risposta WWW-Authenticate. Di seguito è riportato un esempio di risposta di errore userinfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
Se durante la procedura di collegamento viene restituito un errore 401 Autorizzazione o qualsiasi altra risposta di errore non riuscita durante la procedura di collegamento, l'errore non sarà recuperabile, il token recuperato verrà eliminato e l'utente dovrà avviare nuovamente la procedura di collegamento.

Se il token di accesso è valido, restituisce e invia una risposta HTTP 200 con il seguente oggetto JSON nel corpo dell'HTTPS risposta:

{
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}

Se l'endpoint userinfo restituisce una risposta HTTP 200 riuscita, il token e le attestazioni recuperati vengono registrati in base all'Account Google dell'utente.

risposta endpoint userinfo
`sub`	Un ID univoco che identifica l'utente nel sistema.
`email`	Indirizzo email dell'utente.
`given_name`	Facoltativo:nome dell'utente.
`family_name`	Facoltativo:il cognome dell'utente.
`name`	Facoltativo:nome completo dell'utente.
`picture`	(Facoltativo) Immagine del profilo dell'utente.

Convalidare l'implementazione

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

Nello strumento, segui questi passaggi:

Fai clic su Configurazione per aprire la finestra di configurazione di OAuth 2.0.
Nel campo Flusso OAuth, seleziona Lato client.
Nel campo Endpoint OAuth, seleziona Personalizzato.
Specifica l'endpoint OAuth 2.0 e l'ID client che hai assegnato a Google nei campi corrispondenti.
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.
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.