OpenID Connect

Le API OAuth 2.0 di Google possono essere utilizzate sia per l'autenticazione sia per l'autorizzazione. Questo documento descrive la nostra implementazione di OAuth 2.0 per l'autenticazione, conforme alla specifica OpenID Connect ed è certificata OpenID. La documentazione disponibile in Utilizzare OAuth 2.0 per accedere alle API di Google si applica anche a questo servizio. Se vuoi esplorare questo protocollo in modo interattivo, ti consigliamo Google OAuth 2.0 Playground. Per ricevere assistenza su Stack Overflow, contrassegna le tue domande con "google-oauth".

Nota: se vuoi fornire un pulsante "Accedi con Google" per il tuo sito web o la tua app, ti consigliamo di utilizzare i servizi di identità Google, la nostra libreria client di accesso basata sul protocollo OpenID Connect e che fornisce token ID in formato OpenID Connect.

Configurare OAuth 2.0

Prima che l'applicazione possa utilizzare il sistema di autenticazione OAuth 2.0 di Google per l'accesso degli utenti, devi configurare un progetto nella Google API Console per ottenere le credenziali OAuth 2.0, impostare un URI di reindirizzamento e, facoltativamente, personalizzare le informazioni di branding visualizzate dagli utenti nella schermata per il consenso degli utenti. Puoi anche utilizzare API Console per creare un account di servizio, abilitare la fatturazione, configurare i filtri e svolgere altre attività. Per ulteriori dettagli, consulta la Guida diGoogle API Console.

Ottenere le credenziali OAuth 2.0

Per autenticare gli utenti e ottenere l'accesso alle API di Google, devi avere le credenziali OAuth 2.0, inclusi un ID client e un client secret.

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

1. Go to the Credentials page.
2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

Imposta un URI di reindirizzamento

L'URI di reindirizzamento che imposti nella API Console determinazione a cui Google invia le risposte alle tue richieste di autenticazione.

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

1. Go to the Credentials page.
2. In the OAuth 2.0 client IDs section of the page, click a credential.
3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Personalizzare la schermata per il consenso degli utenti

Per i tuoi utenti, l'esperienza di autenticazione OAuth 2.0 include una schermata per il consenso che descrive le informazioni rilasciate dall'utente e i termini applicabili. Ad esempio, quando l'utente accede, potrebbe essere chiesto all'app di accedere al suo indirizzo email e alle informazioni di base dell'account. Per richiedere l'accesso a queste informazioni, utilizza il parametro scope, che la tua app include nella sua richiesta di autenticazione. Puoi anche utilizzare gli ambiti per richiedere l'accesso ad altre API di Google.

La schermata per il consenso dell'utente presenta anche informazioni sul branding come il nome del prodotto, il logo e l'URL della home page. Puoi controllare le informazioni sul branding in API Console.

Per abilitare la schermata di consenso del tuo progetto:

1. Aprire Consent Screen page in Google API Console .
2. If prompted, select a project, or create a new one.
3. Compila il modulo e fai clic su Salva .

La seguente finestra di dialogo per il consenso mostra cosa vedrebbe un utente quando nella richiesta è presente una combinazione di ambiti OAuth 2.0 e Google Drive. Questa finestra di dialogo generica è stata generata utilizzando Google Play 2.0 Playground, pertanto non include le informazioni di branding che potrebbero essere impostate in API Console.

Accedi al servizio

Google e terze parti forniscono librerie che puoi utilizzare per gestire molti dei dettagli di implementazione per l'autenticazione degli utenti e l'accesso alle API di Google. Alcuni esempi sono i servizi di identità Google e le librerie client di Google, disponibili per una varietà di piattaforme.

Nota: date le implicazioni di sicurezza della corretta implementazione dell'implementazione, ti invitiamo vivamente a usufruire di una libreria o un servizio precompilati. Autenticare correttamente gli utenti è importante per loro e per la tua sicurezza e l'utilizzo di codice di cui hai eseguito il debug ben scritto da altri utenti è in genere una best practice. Per maggiori informazioni, consulta la pagina Librerie client.

Se scegli di non utilizzare una libreria, segui le istruzioni nella parte rimanente di questo documento, che descrive i flussi di richieste HTTP che sono alla base delle librerie disponibili.

Autenticazione dell'utente

Per autenticare l'utente è necessario ottenere un token ID e convalidarlo. I token ID sono una funzionalità standardizzata di OpenID Connect progettata per l'utilizzo nella condivisione di asserzioni di identità su Internet.

Gli approcci più comunemente utilizzati per autenticare un utente e ottenere un token ID sono chiamati flusso "server" e "implicit". Il flusso del server consente al server back-end di un'applicazione di verificare l'identità della persona utilizzando un browser o un dispositivo mobile. Il flusso implicito viene utilizzato quando un'applicazione lato client (in genere un'app JavaScript in esecuzione nel browser) deve accedere alle API direttamente anziché tramite il server di backend.

Questo documento descrive come eseguire il flusso del server per l'autenticazione dell'utente. Il flusso implicito è significativamente più complicato a causa dei rischi per la sicurezza nella gestione e nell'utilizzo dei token sul lato client. Se hai bisogno di implementare un flusso implicito, ti consigliamo vivamente di utilizzare i servizi di identità Google.

Flusso del server

Assicurati di configurare la tua app in API Console per abilitare l'utilizzo di questi protocolli e autenticare i tuoi utenti. Quando un utente tenta di accedere con Google, devi:

1. Creare un token di stato anti-falso
2. Inviare una richiesta di autenticazione a Google
3. Confermare il token di stato anti-falso
4. Exchangecode per il token di accesso e il token ID
5. Ottenere informazioni sugli utenti dal token ID
6. Autenticare l'utente

1. Crea un token di stato anti-falso

Devi proteggere la sicurezza dei tuoi utenti evitando attacchi di falsificazione di richieste. Il primo passaggio consiste nel creare un token di sessione univoco che mantiene lo stato tra la tua app e il client dell'utente. In seguito, potrai abbinare questo token di sessione univoco alla risposta di autenticazione restituita dal servizio di accesso OAuth di Google per verificare che l'utente stia effettuando la richiesta e non sia un utente malintenzionato. Questi token sono spesso denominati token di richiesta di falsificazione tra siti (CSRF).

Un'ottima scelta per un token di stato è una stringa di circa 30 caratteri, creata utilizzando un generatore di numeri casuali di alta qualità. Un altro è un hash generato firmando alcune delle variabili di stato della sessione con una chiave mantenuta segreta nel tuo backend.

Il codice seguente illustra la generazione di token di sessione unici.

PHP

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per PHP.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Java.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Python.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Invia una richiesta di autenticazione a Google

Il passaggio successivo consiste nel inviare una richiesta HTTPS GET con i parametri URI appropriati. Tieni presente l'utilizzo di HTTPS anziché di HTTP in tutte le fasi del processo; le connessioni HTTP vengono rifiutate. Recupera l'URI di base dal documento di rilevamento utilizzando il valore dei metadati authorization_endpoint. La seguente discussione presuppone che l'URI di base sia https://accounts.google.com/o/oauth2/v2/auth.

Per una richiesta di base, specifica i seguenti parametri:

• client_id, ottenuto dal API Console Credentials page.
• response_type, che in una richiesta di flusso del codice di autorizzazione di base deve essere code. Scopri di più all'indirizzo response_type.
• scope, che in una richiesta di base dovrebbe essere openid email. Scopri di più all'indirizzo scope.
• redirect_uri deve essere l'endpoint HTTP sul server che riceverà la risposta da Google. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0 che hai configurato in API Console Credentials page. Se questo valore non corrisponde a un URI autorizzato, la richiesta avrà esito negativo con un errore redirect_uri_mismatch.
• state dovrebbe includere il valore del token di sessione univoco anti-falso, nonché qualsiasi altra informazione necessaria per recuperare il contesto quando l'utente torna alla tua applicazione, ad esempio l'URL iniziale. Scopri di più all'indirizzo state.
• nonce è un valore casuale generato dalla tua app che consente la protezione della riproduzione quando presente.
• login_hint può essere l'indirizzo email dell'utente o la stringa sub, che equivale all'ID Google dell'utente. Se non fornisci un login_hint e l'utente ha eseguito l'accesso, la schermata per il consenso include una richiesta di approvazione per rilasciare l'indirizzo email dell'utente nella tua app. (Ulteriori informazioni su login_hint.)
• Utilizza il parametro hd per ottimizzare il flusso OpenID Connect per gli utenti di un particolare dominio associato a un'organizzazione Google Cloud. Scopri di più all'indirizzo hd.

Nota: sopra sono elencati solo i parametri di uso comune. Per un elenco completo, con ulteriori dettagli su tutti i parametri, consulta la pagina Parametri URI di autenticazione.

Ecco un esempio di URI di autenticazione OpenID Connect completo, con interruzioni di riga e spazi per una migliore leggibilità:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Gli utenti devono fornire il consenso se la tua app richiede nuove informazioni su di loro o se richiede l'accesso all'account per acquisti non approvati in precedenza.

3. Conferma il token di stato anti-falso

La risposta viene inviata al redirect_uri specificato nella richiesta. Tutte le risposte vengono restituite nella stringa di query, come mostrato di seguito:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Sul server, devi confermare che il state ricevuto da Google corrisponda al token di sessione che hai creato nel passaggio 1. Questa verifica di andata e ritorno contribuisce a garantire che l'utente, e non uno script dannoso, stia effettuando la richiesta.

Il codice seguente dimostra la conferma dei token di sessione creati al passaggio 1:

PHP

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per PHP.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Java.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Per utilizzare questo esempio, devi scaricare la libreria client delle API di Google per Python.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Scambia code con token di accesso e token ID

La risposta include un parametro code, un codice di autorizzazione una tantum che il server può scambiare con un token di accesso e un token ID. Il server effettua questa piattaforma di scambio inviando una richiesta HTTPS a POST. La richiesta POST viene inviata all'endpoint del token, che dovresti recuperare dal documento di rilevamento utilizzando il valore dei metadati token_endpoint. La seguente discussione presuppone che l'endpoint sia https://oauth2.googleapis.com/token. La richiesta deve includere i seguenti parametri nel corpo POST:

Campi
code	Il codice di autorizzazione restituito dalla richiesta iniziale.
client_id	L'ID client ottenuto da API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
client_secret	Il client secret che ottieni dal API Console Credentials page, come descritto in Ottenere le credenziali OAuth 2.0.
redirect_uri	Un URI di reindirizzamento autorizzato per il client_id specificato in API Console Credentials page, come descritto in Impostare un URI di reindirizzamento.
grant_type	Questo campo deve contenere un valore authorization_code, come definito nella specifica OAuth 2.0.

La richiesta effettiva potrebbe avere il seguente esempio:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Una risposta corretta a questa richiesta contiene i seguenti campi in un array JSON:

Campi
access_token	Un token che può essere inviato a un'API di Google.
expires_in	Durata rimanente del token di accesso in secondi.
id_token	Un JWT che contiene informazioni sull'identità dell'utente firmate digitalmente da Google.
scope	Gli ambiti di accesso concessi da access_token, espressi come elenco di stringhe con distinzione tra maiuscole e minuscole.
token_type	Identifica il tipo di token restituito. Al momento, questo campo ha sempre il valore Bearer.
refresh_token	(facoltativo) Questo campo è presente solo se il parametro access_type è stato impostato su offline nella richiesta di autenticazione. Per i dettagli, vedi Aggiornare i token.

Nota: esiste un limite al numero di token per account utente Google; inoltre, qualsiasi richiesta di autenticazione superiore a questo limite potrebbe invalidare silenziosamente un token di aggiornamento in sospeso. Per maggiori dettagli, consulta Scadenza token.

5. Ottenere informazioni sugli utenti dal token ID

Un token ID è un token web JSON (JWT), ovvero un oggetto JSON con codifica Base64 firmato in modo crittografico. In genere, è fondamentale convalidare un token ID prima di utilizzarlo, ma poiché stai comunicando direttamente con Google tramite un canale HTTPS privo di intermediari e utilizzando il tuo client secret per autenticarti a Google, hai la certezza che il token che ricevi proviene effettivamente da Google ed è valido. Se il server trasmette il token ID ad altri componenti della tua app, è estremamente importante che gli altri componenti convalidino il token prima di utilizzarlo.

Poiché la maggior parte delle librerie API combina la convalida con il lavoro di decodifica dei valori con codifica base64url e di analisi del JSON all'interno, probabilmente finirai per convalidare il token quando accedi alle rivendicazioni nel token ID.

Payload di un token ID

Un token ID è un oggetto JSON contenente un insieme di coppie nome/valore. Ecco un esempio, formattato per la leggibilità:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

I token ID Google possono contenere i seguenti campi (chiamati rivendicazioni):

Rivendicazione	fornito	Descrizione
aud	always	Il pubblico a cui è destinato questo token ID. Deve essere uno degli ID client OAuth 2.0 della tua applicazione.
exp	always	Ora di scadenza in cui il token dell'ID non deve essere accettato. Rappresentato in tempo Unix (secondi interi).
iat	always	L'ora in cui è stato emesso il token ID. Rappresentato in tempo Unix (secondi interi).
iss	always	L'identificatore dell'emittente dell'emittente della risposta. Sempre https://accounts.google.com o accounts.google.com per i token ID Google.
sub	always	Un identificatore dell'utente, univoco tra tutti gli Account Google e mai riutilizzato. Un Account Google può avere più indirizzi email in momenti diversi, ma il valore sub non viene mai modificato. Utilizza sub all'interno dell'applicazione come chiave di identificazione univoca per l'utente. Lunghezza massima di 255 caratteri ASCII sensibili alle maiuscole.
at_hash		Accedi all'hash del token. Fornisce la convalida del token di accesso associato al token di identità. Se il token ID viene emesso con un valore access_token nel flusso del server, questa rivendicazione è sempre inclusa. Questa dichiarazione può essere utilizzata come meccanismo alternativo per proteggersi dagli attacchi di falsificazione di siti tra siti; tuttavia, se segui il Passaggio 1 e il Passaggio 3, non è necessario verificare il token di accesso.
azp		Il client_id del presentatore autorizzato. Questa rivendicazione è necessaria solo quando la parte che richiede il token ID non corrisponde al pubblico del token ID. Questo vale per Google per le app ibride in cui un'applicazione web e un'app Android hanno client_id 2.0 OAuth diverso, ma condividono lo stesso progetto API di Google.
email		L'indirizzo email dell'utente. Questo valore potrebbe non essere univoco per questo utente e non è adatto per essere utilizzato come chiave primaria. Indicato solo se l'ambito includeva il valore dell'ambito email.
email_verified		Vero se l'indirizzo email dell'utente è stato verificato; altrimenti falso.
family_name		Cognome o cognome dell'utente. Potrebbe essere fornito quando è presente una rivendicazione di name.
given_name		Nomi o nomi degli utenti. Potrebbe essere fornito quando è presente una rivendicazione di name.
hd		Il dominio associato all'organizzazione Google Cloud dell'utente. Indicato solo se l'utente appartiene a un'organizzazione Google Cloud.
locale		Le impostazioni internazionali dell'utente, rappresentate da un tag di lingua BCP 47. Potrebbe essere fornito quando è presente una rivendicazione di name.
name		Il nome completo dell'utente, in un formato visibile. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni di name, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che la dichiarazione non è mai presente.
nonce		Il valore dell'elemento nonce fornito dalla tua app nella richiesta di autenticazione. Devi imporre la protezione contro gli attacchi di replica assicurandoti che venga presentata una sola volta.
picture		L'URL dell'immagine del profilo dell'utente. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni di picture, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che la dichiarazione non è mai presente.
profile		L'URL della pagina del profilo dell'utente. Potrebbe essere fornito quando: L'ambito della richiesta includeva la stringa "profile" Il token ID viene restituito da un aggiornamento del token Quando sono presenti rivendicazioni di profile, puoi utilizzarle per aggiornare i record utente della tua app. Tieni presente che la dichiarazione non è mai presente.

6. Autenticare l'utente

Dopo aver ottenuto le informazioni utente dal token ID, devi eseguire una query sul database utente della tua app. Se l'utente esiste già nel tuo database, devi avviare una sessione di applicazione per quell'utente se tutti i requisiti di accesso sono soddisfatti dalla risposta dell'API di Google.

Se l'utente non esiste nel tuo database utenti, devi reindirizzarlo al flusso di registrazione dei nuovi utenti. Potresti essere in grado di registrare automaticamente l'utente in base alle informazioni ricevute da Google o, almeno, potresti essere in grado di precompilare molti dei campi obbligatori nel modulo di registrazione. Oltre alle informazioni nel token ID, puoi ottenere informazioni aggiuntive sul profilo utente nei nostri endpoint del profilo utente.

Argomenti avanzati

Le sezioni seguenti descrivono in modo più dettagliato l'API Google OAuth 2.0. Queste informazioni sono rivolte agli sviluppatori con requisiti avanzati di autenticazione e autorizzazione.

Accesso ad altre API di Google

Uno dei vantaggi di utilizzare OAuth 2.0 per l'autenticazione è che l'applicazione può ottenere l'autorizzazione per utilizzare altre API di Google per conto dell'utente (come YouTube, Google Drive, Calendar o Contatti) contemporaneamente all'autenticazione dell'utente. Per farlo, includi gli altri ambiti di cui hai bisogno nella richiesta di autenticazione che invii a Google. Ad esempio, per aggiungere l'età dell'utente alla richiesta di autenticazione, passa un parametro di ambito openid email https://www.googleapis.com/auth/profile.agerange.read. All'utente viene richiesto in modo appropriato la schermata di consenso. Il token di accesso che ricevi da Google ti consente di accedere a tutte le API relative agli ambiti di accesso che hai richiesto e che ti sono stati concessi.

Nota: se l'applicazione richiede molti ambiti, la schermata per il consenso conterrà molte righe di testo. Maggiore è il numero di ambiti richiesti dall'applicazione, minore è la probabilità che l'utente fornisca il consenso, pertanto l'applicazione deve chiedere solo gli ambiti di cui ha bisogno.

Aggiorna token

Nella richiesta di accesso all'API puoi richiedere la restituzione di un token di aggiornamento durante lo scambio di code. Un token di aggiornamento fornisce alla tua app l'accesso continuo alle API di Google quando l'utente non è presente nella tua applicazione. Per richiedere un token di aggiornamento, aggiungi il parametro access_type a offline nella richiesta di autenticazione.

Considerazioni:

• Assicurati di archiviare il token di aggiornamento in modo sicuro e permanente, perché puoi ottenere un token di aggiornamento solo la prima volta che esegui il flusso di scambio del codice.
• Sono previsti dei limiti al numero di token di aggiornamento emessi: un limite per combinazione di client/utente e un altro per tutti i client. Se la tua applicazione richiede troppi token di aggiornamento, questi potrebbero incorrere in questi limiti, nel qual caso i token di aggiornamento meno recenti smettono di funzionare.

Per ulteriori informazioni, consulta la pagina Aggiornare un token di accesso (accesso offline).

Richiesta di nuovo consenso

Puoi chiedere all'utente di autorizzare nuovamente la tua app impostando il parametro prompt su consent nella richiesta di autenticazione. Se prompt=consent è incluso, la schermata per il consenso viene visualizzata ogni volta che la tua app richiede l'autorizzazione degli ambiti di accesso, anche se tutti gli ambiti sono stati concessi in precedenza al tuo progetto API di Google. Per questo motivo, includi prompt=consent solo quando necessario.

Per ulteriori informazioni sul parametro prompt, consulta prompt nella tabella Parametri URI di autenticazione.

Parametri URI di autenticazione

La seguente tabella fornisce descrizioni più complete dei parametri accettati dall'API OAuth 2.0 di Google.

Parametro	Obbligatorio	Descrizione
client_id	(Obbligatorio)	La stringa ID client ottenuta da API Console Credentials page, come descritto in Ottieni le credenziali OAuth 2.0.
nonce	(Obbligatorio)	Un valore casuale generato dalla tua app che consente la protezione dalla riproduzione.
response_type	(Obbligatorio)	Se il valore è code, avvia un flusso del codice di autorizzazione di base, che richiede un POST all'endpoint del token per ottenere i token. Se il valore è token id_token o id_token token, avvia un flusso implicito, che richiede l'utilizzo di JavaScript all'URI di reindirizzamento per recuperare i token dall'identificatore #fragment URI.
redirect_uri	(Obbligatorio)	Determina dove viene inviata la risposta. Il valore di questo parametro deve corrispondere esattamente a uno dei valori di reindirizzamento autorizzati che hai impostato in API Console Credentials page (inclusi lo schema HTTP o HTTPS, la distinzione tra maiuscole e minuscole e, se presente, la parte "/").
scope	(Obbligatorio)	Il parametro dell'ambito deve iniziare con il valore openid e poi includere il valore profile, il valore email o entrambi. Se è presente il valore dell'ambito profile, il token ID potrebbe (ma non è garantito) includere le rivendicazioni profile predefinite dell'utente. Se è presente il valore dell'ambito email, il token ID include le rivendicazioni email e email_verified. Oltre a questi ambiti specifici di OpenID, l'argomento dell'ambito può includere anche altri valori dell'ambito. Tutti i valori degli ambiti devono essere separati da spazi. Ad esempio, se vuoi che l'accesso ai file di Google Drive di un utente avvenga, il parametro dell'ambito è: openid profile email https://www.googleapis.com/auth/drive.file. Per informazioni sugli ambiti disponibili, consulta la pagina sugli ambiti OAuth 2.0 per le API di Google o la documentazione dell'API di Google che vuoi utilizzare.
state	(facoltativo, ma vivamente consigliato)	Una stringa opaca che è andata e ritorno nel protocollo, vale a dire, viene restituita come parametro URI nel flusso di base e nell'identificatore URI #fragment nel flusso implicito. state può essere utile per correlare richieste e risposte. Poiché è possibile indovinare il tuo redirect_uri, l'utilizzo di un valore di state può aumentare la tua garanzia che una connessione in entrata sia il risultato di una richiesta di autenticazione avviata dalla tua app. Se generi una stringa casuale o codifica l'hash di uno stato di client (ad esempio, un cookie) in questa variabile state, puoi convalidare la risposta per garantire inoltre che la richiesta e la risposta abbiano avuto origine nello stesso browser. In questo modo proteggerai da attacchi come la falsificazione di richieste tra siti.
access_type	(Facoltativo)	I valori consentiti sono offline e online. L'effetto è documentato in Accesso offline; se viene richiesto un token di accesso, il client non riceve un token di aggiornamento a meno che non venga specificato il valore offline.
display	(Facoltativo)	Un valore stringa ASCII per specificare in che modo il server di autorizzazione visualizza le pagine dell'interfaccia utente di consenso e autenticazione. I seguenti valori sono specificati e accettati dai server di Google, ma non hanno alcun effetto sul loro comportamento: page, popup, touch e wap.
hd	(Facoltativo)	Semplifica il processo di accesso per gli account di proprietà di un'organizzazione Google Cloud. Se includi il dominio dell'organizzazione Google Cloud (ad esempio mycollege.edu), puoi indicare che l'UI di selezione degli account deve essere ottimizzata per gli account in quel dominio. Per eseguire l'ottimizzazione in base agli account dell'organizzazione Google Cloud in generale, anziché a un solo dominio dell'organizzazione Google Cloud, imposta un valore di asterisco (*): hd=*. Non fare affidamento su questa ottimizzazione dell'interfaccia utente per controllare chi può accedere alla tua app, poiché le richieste lato client possono essere modificate. Assicurati di convalidare che il token ID restituito ha un valore di rivendicazione hd corrispondente a quello previsto (ad es. mycolledge.edu). A differenza del parametro di richiesta, la rivendicazione del token ID hd è contenuta in un token di sicurezza di Google, quindi il valore è attendibile.
include_granted_scopes	(Facoltativo)	Se questo parametro viene fornito con il valore true e la richiesta di autorizzazione viene concessa, l'autorizzazione includerà le eventuali autorizzazioni precedenti concesse a questa combinazione utente/applicazione per altri ambiti; consulta la sezione Autorizzazione incrementale. Tieni presente che non puoi eseguire un'autorizzazione incrementale con il flusso App installate.
login_hint	(Facoltativo)	Quando la tua app sa quale utente sta tentando di autenticarsi, può fornire questo parametro come suggerimento al server di autenticazione. Il passaggio di questo suggerimento impedisce al selettore di account e alla precompilazione della casella email nel modulo di accesso o alla selezione della sessione corretta (se l'utente utilizza l'accesso simultaneo), che può aiutarti a evitare problemi che si verificano se la tua app esegue l'accesso all'account utente sbagliato. Il valore può essere un indirizzo email o la stringa sub, che corrisponde all'ID Google dell'utente.
prompt	(Facoltativo)	Un elenco di valori stringa delimitato da spazi che specifica se il server di autorizzazione richiede l'autenticazione e il consenso all'utente. I valori possibili sono: none Il server di autorizzazione non mostra alcuna schermata di autenticazione o di consenso dell'utente e restituirà un errore se l'utente non è già autenticato e non ha concesso il consenso preconfigurato per gli ambiti richiesti. Puoi utilizzare none per verificare l'autenticazione e/o il consenso esistenti. consent Il server di autorizzazione richiede all'utente il consenso prima di restituire informazioni al client. select_account Il server di autorizzazione chiede all'utente di selezionare un account utente. In questo modo, un utente con più account sul server di autorizzazione può scegliere tra i diversi account per cui potrebbe avere sessioni attuali. Se non viene specificato alcun valore e l'utente non ha precedentemente un accesso autorizzato, all'utente viene mostrata una schermata per il consenso.

Convalida di un token ID

Devi convalidare tutti i token ID sul tuo server a meno che tu non abbia la certezza che provengono direttamente da Google. Ad esempio, il tuo server deve verificare come autentici tutti i token ID che riceve dalle app client.

Di seguito sono riportate le situazioni più comuni in cui potresti inviare token ID al tuo server:

• Invio di token ID con richieste che devono essere autenticate. I token ID indicano all'utente specifico che ha effettuato la richiesta e per quale client è stato concesso il token ID.

I token ID sono sensibili e possono essere usati in modo improprio se intercettati. Devi assicurarti che questi token siano gestiti in modo sicuro trasmettendoli solo tramite HTTPS e solo tramite dati POST o all'interno delle intestazioni delle richieste. Se memorizzi token ID sul tuo server, devi anche memorizzarli in modo sicuro.

Un aspetto che rende utili i token ID è il fatto che puoi trasferirli su diversi componenti della tua app. Questi componenti possono utilizzare un token ID come meccanismo di autenticazione semplice per autenticare l'app e l'utente. Tuttavia, prima di poter utilizzare le informazioni contenute nel token ID o di considerarle come una dichiarazione che l'utente ha autenticato, devi convalidarle.

La convalida di un token ID richiede diversi passaggi:

1. Verifica che il token ID sia firmato correttamente dall'emittente. I token emessi da Google vengono firmati utilizzando uno dei certificati che si trovano nell'URI specificato nel valore dei metadati jwks_uri del documento di rilevamento.
2. Verifica che il valore della rivendicazione di iss nel token ID sia uguale a https://accounts.google.com o accounts.google.com.
3. Verifica che il valore della rivendicazione di aud nel token ID sia uguale all'ID client della tua app.
4. Verifica che la data di scadenza (exp rivendicazione) del token ID non sia trascorsa.
5. Se hai specificato un valore parametro hd nella richiesta, verifica che il token ID abbia una rivendicazione hd corrispondente a un dominio accettato associato a un'organizzazione Google Cloud.

I passaggi da 2 a 5 prevedono solo confronti di stringhe e date molto semplici, per cui non li illustreremo qui.

Il primo passaggio è più complesso e prevede il controllo della firma crittografica. Ai fini del debug, puoi utilizzare l'endpoint tokeninfo di Google per eseguire il confronto con l'elaborazione locale implementata sul tuo server o dispositivo. Supponiamo che il valore del token ID sia XYZ123. Devi quindi rimuovere l'URI da https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Se la firma del token è valida, la risposta sarà il payload JWT nel suo formato dell'oggetto JSON decodificato.

L'endpoint tokeninfo è utile per il debug, ma a scopo di produzione, recupera le chiavi pubbliche di Google dall'endpoint chiavi ed esegue la convalida localmente. Recupera l'URI delle chiavi dal documento di rilevamento utilizzando il valore dei metadati jwks_uri. Le richieste all'endpoint di debug potrebbero essere limitate o altrimenti soggette a errori intermittenti.

Poiché Google modifica le sue chiavi pubbliche solo raramente, puoi memorizzarle nella cache utilizzando le istruzioni cache della risposta HTTP e, nella maggior parte dei casi, eseguire la convalida locale in modo molto più efficiente rispetto all'utilizzo dell'endpoint tokeninfo. Questa convalida richiede il recupero e l'analisi dei certificati e le chiamate crittografiche appropriate per controllare la firma. Fortunatamente, sono disponibili librerie di cui è stato eseguito il debug in un'ampia varietà di linguaggi per eseguire questa operazione (vedi jwt.io).

Ottenere le informazioni del profilo dell'utente

Per ottenere ulteriori informazioni del profilo dell'utente, puoi utilizzare il token di accesso (che l'applicazione riceve durante il flusso di autenticazione) e lo standard OpenID Connect:

1. Per essere conforme a OpenID, devi includere i valori dell'ambito di openid profile nella richiesta di autenticazione.

   Se vuoi che l'indirizzo email dell'utente sia incluso, puoi specificare un valore di ambito aggiuntivo pari a email. Per specificare sia profile sia email, puoi includere il seguente parametro nell'URI della richiesta di autenticazione:

   scope=openid%20profile%20email

2. Aggiungi il token di accesso all'intestazione di autorizzazione ed effettua una richiesta HTTPS per GET all'endpoint delle informazioni utente, che dovresti recuperare dal documento di rilevamento utilizzando il valore dei metadati userinfo_endpoint. La risposta userinfo include informazioni sull'utente, come descritto in OpenID Connect Standard Claims e il valore dei metadati claims_supported del documento di rilevamento. Gli utenti o le loro organizzazioni potrebbero scegliere di fornire o trattenere alcuni campi, quindi potresti non ricevere informazioni per ogni campo relativo ai tuoi ambiti di accesso autorizzati.

Il documento di rilevamento

Il protocollo OpenID Connect richiede l'uso di più endpoint per l'autenticazione degli utenti e per la richiesta di risorse tra cui token, informazioni sugli utenti e chiavi pubbliche.

Per semplificare le implementazioni e aumentare la flessibilità, OpenID Connect consente di utilizzare un "documento di rilevamento", un documento JSON che si trova in una posizione nota contenente coppie chiave-valore che forniscono dettagli sulla configurazione del provider OpenID Connect, inclusi gli URI di autorizzazione, token, revoca, info utente ed endpoint di chiavi pubbliche. Il documento di rilevamento per il servizio OpenID Connect di Google può essere recuperato da:

https://accounts.google.com/.well-known/openid-configuration

Per utilizzare i servizi OpenID Connect di Google, devi eseguire l'hard-coding dell'URI del documento Discovery (https://accounts.google.com/.well-known/openid-configuration) nell'applicazione. L'applicazione recupera il documento, applica le regole di memorizzazione nella cache nella risposta e recupera gli URI endpoint da sua richiesta. Ad esempio, per autenticare un utente, il codice recupera il valore dei metadati authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth nell'esempio riportato di seguito) come URI di base per le richieste di autenticazione inviate a Google.

Ecco un esempio di documento di questo tipo; i nomi dei campi sono quelli specificati in OpenID Connect Discovery 1.0 (fai riferimento a tale documento per il relativo significato). I valori sono a scopo puramente illustrativo e potrebbero cambiare, anche se vengono copiati da una versione recente del documento effettivo di Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Potresti evitare un round trip HTTP, memorizzando nella cache i valori del documento di rilevamento. Vengono utilizzate intestazioni di memorizzazione nella cache HTTP standard che devono essere rispettate.

Librerie client

Le seguenti librerie client semplificano l'implementazione di OAuth 2.0 mediante l'integrazione con i framework più diffusi:

• Libreria client delle API di Google per Java
• Libreria client delle API di Google per Python
• Libreria client delle API di Google per .NET
• Libreria client delle API di Google per Ruby
• Libreria client delle API di Google per PHP
• Libreria OAuth 2.0 per Google Web Toolkit
• Strumenti Google per controller Mac OAuth 2.0

Conformità di OpenID Connect

Il sistema di autenticazione OAuth 2.0 di Google supporta le funzionalità richieste della specifica OpenID Connect Core. Qualsiasi client progettato per funzionare con OpenID Connect dovrebbe interagire con questo servizio (tranne che con l'oggetto richiesta OpenOpen).