Utilizza modello di codice

La libreria dei Servizi di identità Google consente agli utenti di richiedere un codice di autorizzazione da Google utilizzando un flusso UX di popup o reindirizzamento basato su browser. Inizia un flusso OAuth 2.0 sicuro 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 un clic del pulsante, il proprietario dell'account Google richiede un codice di autorizzazione a Google.
• Google risponde inviando un codice di autorizzazione univoco a un callback nell'app web JavaScript in esecuzione nel browser dell'utente o 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 token di Google.
• Google convalida il codice di autorizzazione, conferma che la richiesta proviene dalla tua piattaforma sicura, rilascia i token di accesso e di aggiornamento e li restituisce chiamando l'endpoint di accesso ospitato dalla tua piattaforma.
• L'endpoint di accesso riceve i token di accesso e di aggiornamento, memorizzando in modo sicuro il token di aggiornamento per un utilizzo successivo.

Punto chiave: sul server di backend, scambi un codice di autorizzazione con token di aggiornamento e token di accesso chiamando l'endpoint token di Google.

Prerequisiti

Segui i passaggi descritti in Configurazione per configurare la schermata per il consenso OAuth, ottenere un ID client e caricare la libreria client.

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 di callback JavaScript che invia il codice di autorizzazione al tuo server. La modalità popup può essere utilizzata per offrire un'esperienza utente ottimale senza che i visitatori debbano uscire dal tuo sito.

Per inizializzare un client per:

• Flusso UX di reindirizzamento, imposta ux_mode su redirect e il valore di redirect_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 in Google Cloud Console. Deve inoltre rispettare le regole di convalida dell'URI di reindirizzamento.

• Flusso UX popup, imposta ux_mode su popup e il valore di callback sul nome della funzione che utilizzerai per inviare i codici di autorizzazione alla tua piattaforma. Il valore di redirect_uri è impostato per impostazione predefinita sull'origine della pagina che chiama initCodeClient. Questo valore viene utilizzato in un secondo momento nel flusso quando il codice di autorizzazione viene scambiato con un token di accesso o di aggiornamento. Ad esempio, https://www.example.com/index.html chiama initCodeClient e l'origine: https://www.example.com è il valore di redirect_url.

Nota importante: per il miglior equilibrio tra usabilità e sicurezza, è consigliato utilizzare il flusso UX della modalità popup con il modello del codice di autorizzazione.

Proteggiti dagli attacchi CSRF

Per contribuire a prevenire gli attacchi di tipo Cross-Site-Request-Forgery (CSRF), vengono utilizzate tecniche leggermente diverse per i flussi UX delle modalità Reindirizzamento e Popup. Per la modalità Redirect, viene utilizzato il parametro state di OAuth 2.0. Per saperne di più sulla generazione e sulla convalida del parametro state, consulta la sezione 10.12 della RFC6749 Cross-Site Request Forgery. Con la modalità Popup, aggiungi un'intestazione HTTP personalizzata alle tue richieste, quindi sul tuo server verifica che corrisponda al valore e all'origine previsti.

Scegli una modalità UX per visualizzare uno snippet di codice che mostra la gestione del codice di autorizzazione e CSRF:

Modalità di reindirizzamento

Inizializza un client in cui Google reindirizza il browser dell'utente al tuo endpoint di autenticazione, condividendo il codice di autenticazione come parametro URL.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

Punto chiave: un endpoint sul tuo server di backend riceve e convalida il codice di autorizzazione, scambiandolo con token di accesso e di aggiornamento.

Modalità popup

Inizializza un client in cui l'utente inizia il flusso di autorizzazione in una finestra di dialogo popup. Dopo il consenso, il codice di autorizzazione viene restituito da Google al browser dell'utente utilizzando una funzione di callback. Una richiesta POST dal gestore di callback JS invia il codice di autorizzazione a un endpoint sul server di backend, dove viene prima verificato e poi completato il resto del flusso OAuth.

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", 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);
  },
});

Punto chiave: un endpoint sul tuo server di backend riceve e convalida il codice di autorizzazione, scambiandolo con token di accesso e aggiornamento.

Attivare il flusso del 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>

In questo modo, l'utente dovrà accedere a un Account Google e 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 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_uri, condividendo il codice di autorizzazione nel parametro code dell'URL. Per ricevere il codice di autorizzazione:

• Crea un nuovo endpoint di autorizzazione se non disponi di un'implementazione esistente oppure

• Aggiorna l'endpoint esistente per accettare richieste GET e parametri URL. In precedenza, veniva utilizzata una richiesta PUT con il valore del codice di autorizzazione nel payload.

Endpoint di autorizzazione

L'endpoint del codice di autorizzazione deve gestire le richieste GET con questi parametri della stringa di query URL:

Nome	Valore
authuser	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 dell'utente
ambito	Elenco separato da spazi di uno o più ambiti OAuth2 da autorizzare
stato	Variabile di stato CRSF

Esempio di richiesta GET con parametri URL a 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 da librerie JavaScript precedenti o da 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

Importante: in precedenza, POST veniva utilizzato per le richieste. Aggiorna il gestore in modo che accetti le richieste GET e POST oppure valuta la possibilità di ospitare due endpoint diversi se prevedi di continuare a utilizzare librerie JS precedenti o di chiamare direttamente gli endpoint Google OAuth 2.0 durante l'utilizzo della libreria Google Identity Services.

Convalidare la richiesta

Sul server, esegui le seguenti operazioni per evitare attacchi CSRF.

Controlla il valore del parametro state per la modalità di reindirizzamento.

Conferma che l'intestazione X-Requested-With: XmlHttpRequest sia impostata per la modalità popup.

Dovresti quindi procedere con l'ottenimento dei token di aggiornamento e di accesso da Google solo se hai verificato correttamente la richiesta del codice di autorizzazione.

Ottenere i token di accesso e di aggiornamento

Una volta che la piattaforma di backend riceve un codice di autorizzazione da Google e verifica la richiesta, utilizza il codice di autorizzazione per ottenere token di accesso e aggiornamento da Google per effettuare chiamate API.

Segui le istruzioni a partire dal Passaggio 5: scambia il codice di autorizzazione con token di aggiornamento e di accesso della guida Utilizzo di OAuth 2.0 per applicazioni server web.

Nota: quando viene utilizzata la modalità popup, il valore redirect_uri utilizzato nel passaggio 5 e successivamente è l'origine della pagina chiamante. Ad esempio, https://www.example.com/index.html chiama initCodeClient e l'origine: https://www.example.com è il valore di redirect_url.

Gestisci i 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.

Se vuoi, puoi prendere in considerazione RISC per proteggere gli account utente con la protezione cross-account.

In genere, la tua piattaforma di backend chiama le API di Google utilizzando un token di accesso. Se la tua app web chiamerà direttamente anche le API di Google dal browser dell'utente, devi implementare un modo per condividere il token di accesso con la tua applicazione web. Questa operazione 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 consentire alla libreria di chiamare le API di Google.