La libreria dei Servizi di identità Google consente agli utenti di richiedere un codice di autorizzazione a Google utilizzando un flusso UX basato su popup o reindirizzamento basato su browser. Questa operazione avvia un flusso sicuro OAuth 2.0 e genera un token di accesso utilizzato per chiamare le API di Google per conto di un utente.
Riepilogo del flusso del codice di autorizzazione OAuth 2.0:
- Da un browser, con un gesto come il clic su un pulsante, il proprietario dell'Account Google richiede un codice di autorizzazione a Google.
- Google risponde inviando un codice di autorizzazione univoco a un callback nella tua app web JavaScript in esecuzione nel browser dell'utente oppure richiama direttamente l'endpoint del codice di autorizzazione utilizzando un reindirizzamento del browser.
- La tua piattaforma di backend ospita un endpoint del codice di autorizzazione e riceve il codice. Dopo la convalida, questo codice viene scambiato con token di accesso e aggiornamento per utente utilizzando una richiesta all'endpoint del token di Google.
- Google convalida il codice di autorizzazione, conferma che la richiesta ha avuto origine dalla tua piattaforma sicura, emette token di accesso e di aggiornamento e restituisce i token chiamando l'endpoint di accesso ospitato dalla tua piattaforma.
- L'endpoint di accesso riceve i token di accesso e di aggiornamento e memorizza in modo sicuro il token di aggiornamento per utilizzarlo in seguito.
Inizializzare un client di codice
Il metodo google.accounts.oauth2.initCodeClient()
inizializza un client di codice.
Modalità popup o reindirizzamento
Puoi scegliere di condividere un codice di autorizzazione utilizzando il flusso utente in modalità Reindirizzamento o Popup. Con la modalità di reindirizzamento, ospiti un endpoint di autorizzazione OAuth2 sul tuo server e Google reindirizza lo user agent a questo endpoint, condividendo il codice di autorizzazione come parametro URL. Per la modalità popup, definisci un gestore callback JavaScript che invia il codice di autorizzazione al tuo server. La modalità popup può essere utilizzata per offrire un'esperienza utente fluida senza che i visitatori debbano abbandonare il sito.
Per inizializzare un client per:
Reindirizza il flusso UX, imposta
ux_mode
suredirect
e il valoreredirect_uri
sull'endpoint del codice di autorizzazione della tua piattaforma. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0 che hai configurato nella console API. Deve inoltre rispettare le nostre Regole di convalida degli URI di reindirizzamento.Flusso UX dei popup, impostato
ux_mode
supopup
e il valore dicallback
sul nome della funzione che utilizzerai per inviare i codici di autorizzazione alla piattaforma.
Prevenzione degli attacchi CSRF
Per evitare gli attacchi Cross-Site-Request-Forgery (CSRF) vengono utilizzate tecniche leggermente diverse per i flussi UX in modalità reindirizzamento e popup. Per la modalità di reindirizzamento, viene utilizzato il parametro state OAuth 2.0. Per saperne di più sulla generazione e la convalida del parametro state, consulta la sezione 10.12 di RFC6749 relativa alla falsificazione delle richieste tra siti. Con la modalità popup, aggiungi un'intestazione HTTP personalizzata alle tue richieste e poi, sul tuo server, confermi che corrisponda al valore e all'origine previsti.
Scegli una modalità UX per visualizzare uno snippet di codice che mostra il codice di autorizzazione e la gestione del CSRF:
Modalità di reindirizzamento
Inizializza un client in cui Google reindirizza il browser dell'utente al tuo endpoint di autenticazione, condividendo il codice di autorizzazione come parametro URL.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'redirect',
redirect_uri: "https://your.domain/code_callback_endpoint",
state: "YOUR_BINDING_VALUE"
});
Modalità popup
Inizializza un client in cui il browser dell'utente riceve un codice di autorizzazione da Google e lo invia al tuo server.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'popup',
callback: (response) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', code_receiver_uri, true);
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
// Set custom header for CRSF
xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
xhr.onload = function() {
console.log('Auth code response: ' + xhr.responseText);
};
xhr.send('code=' + response.code);
},
});
Attiva flusso di codice OAuth 2.0
Chiama il metodo requestCode()
del client di codice per attivare il flusso utente:
<button onclick="client.requestCode();">Authorize with Google</button>
Ciò richiederà all'utente di accedere a un Account Google e di acconsentire alla condivisione di singoli ambiti prima di restituire un codice di autorizzazione all'endpoint di reindirizzamento o al gestore di callback.
Gestione del codice di autorizzazione
Google genera un codice di autorizzazione univoco per utente che ricevi e verifichi sul tuo server di backend.
Per la modalità popup, il gestore specificato da callback
, in esecuzione nel browser dell'utente, inoltra il codice di autorizzazione a un endpoint ospitato dalla tua piattaforma.
Per la modalità di reindirizzamento, viene inviata una richiesta GET
all'endpoint specificato da
redirect_url
, condividendo il codice di autorizzazione nel parametro code dell'URL. Per ricevere il codice di autorizzazione:
Crea un nuovo endpoint di autorizzazione se non hai un'implementazione esistente.
Aggiorna l'endpoint esistente per accettare le richieste
GET
e i parametri URL. In precedenza, nel payload veniva utilizzata una richiestaPUT
con il valore del codice di autorizzazione nel payload.
Endpoint di autorizzazione
L'endpoint del codice di autorizzazione deve gestire le richieste GET
con i seguenti parametri della stringa di query dell'URL:
Nome | Valore |
---|---|
utente autorizzato | Richiesta di autenticazione dell'accesso utente |
codice | Un codice di autorizzazione OAuth2 generato da Google |
hd | Il dominio ospitato dell'account utente |
richiesta | Finestra di dialogo per il consenso degli utenti |
ambito | Elenco separato da spazi di uno o più ambiti OAuth2 da autorizzare |
state | Variabile di stato CRSF |
Esempio di richiesta GET
con parametri URL per un endpoint denominato auth-code e ospitato da example.com:
Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent
Quando il flusso del codice di autorizzazione viene avviato dalle librerie JavaScript precedenti o tramite chiamate dirette agli endpoint Google OAuth 2.0, viene utilizzata una richiesta POST
.
Esempio di richiesta POST
contenente il codice di autorizzazione come payload nel corpo della richiesta HTTP:
Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw
Convalidare la richiesta
Sul server, procedi nel seguente modo per evitare attacchi CSRF.
Verifica il valore del parametro state per la modalità di reindirizzamento.
Verifica che l'intestazione X-Requested-With: XmlHttpRequest
sia impostata per la modalità popup.
Dovresti quindi procedere con il recupero dei token di aggiornamento e accesso da Google solo se hai prima verificato la richiesta del codice di autorizzazione.
Ottenere token di accesso e di aggiornamento
Dopo che la tua piattaforma di backend riceve un codice di autorizzazione da Google e verifica la richiesta, utilizza il codice di autorizzazione per ottenere da Google i token di accesso e di aggiornamento ed effettuare chiamate API.
Segui le istruzioni a partire dal Passaggio 5: scambia il codice di autorizzazione per i token di aggiornamento e accesso della guida Utilizzo di OAuth 2.0 per applicazioni server web.
Gestione dei token
La tua piattaforma archivia in modo sicuro i token di aggiornamento. Elimina i token di aggiornamento archiviati quando gli account utente vengono rimossi o il consenso dell'utente viene revocato da google.accounts.oauth2.revoke
o direttamente da https://myaccount.google.com/permissions.
Facoltativamente, puoi valutare l'uso di RISC per proteggere gli account utente con la Protezione su più account.
In genere, la tua piattaforma di backend chiama le API di Google utilizzando un token di accesso. Se anche l'app web chiama direttamente le API di Google dal browser dell'utente, devi implementare un modo per condividere il token di accesso con l'applicazione web. In questo modo, non rientra nell'ambito di questa guida. Se segui questo approccio e utilizzi la libreria client delle API di Google per JavaScript, utilizza gapi.client.SetToken()
per archiviare temporaneamente il token di accesso nella memoria del browser e abilitare la libreria per chiamare le API di Google.