Autenticazione degli utenti

I protocolli di autenticazione web utilizzano le funzionalità HTTP, ma le app di Chrome vengono eseguite all'interno del contenitore dell'app; non vengono caricate tramite HTTP e non possono eseguire reindirizzamenti o impostare cookie.

Utilizza l'API Chrome Identity per autenticare gli utenti: getAuthToken per gli utenti che hanno eseguito l'accesso al loro Account Google e launchWebAuthFlow per gli utenti che hanno eseguito l'accesso a un account non Google. Se la tua app utilizza il proprio server per autenticare gli utenti, dovrai utilizzare quest'ultimo.

Come funziona

Gli utenti delle app di Chrome hanno un Account Google associato al loro profilo. Le app possono ottenere token OAuth2 per questi utenti utilizzando l'API getAuthToken.

Le app che vogliono eseguire l'autenticazione con provider di identità diversi da Google devono chiamare launchWebAuthFlow. Questo metodo utilizza un popup del browser per mostrare le pagine del fornitore e acquisisce i reindirizzamenti ai pattern URL specifici. Gli URL di reindirizzamento vengono passati all'app, che estrae il token dall'URL.

Autenticazione dell'Account Google

Ecco i cinque passaggi da completare:

  1. Aggiungi le autorizzazioni al manifest e carica l'app.
  2. Copia la chiave nell'manifest.json installato nel file manifest di origine, in modo che l'ID applicazione rimanga costante durante lo sviluppo.
  3. Ottieni un ID client OAuth2 per la tua app Chrome.
  4. Aggiorna il file manifest includendo l'ID client e gli ambiti.
  5. Recupera il token di autenticazione.

Aggiungi le autorizzazioni e carica l'app

Devi assicurarti che l'autorizzazione di accesso all'identità sia presente nel manifest. Puoi quindi caricare l'app nella pagina di gestione di app ed estensioni (vedi Pubblicare).

"permissions": [
  "identity"
]

Copia la chiave nel file manifest

Quando registri la tua applicazione nella console OAuth di Google, fornisci il suo ID, che verrà controllato durante le richieste di token. Pertanto, è importante avere un ID applicazione coerente durante lo sviluppo.

Per mantenere costante l'ID applicazione, devi copiare la chiave in manifest.json installato nel manifest di origine. Non è un'attività molto graziosa, ma ecco come funziona:

  1. Vai alla directory dei dati utente. Esempio su macOS: ~/Library/Application\ Support/Google/Chrome/Default/Extensions
  2. Elenca le app e le estensioni installate e associa il tuo ID app nella pagina di gestione di app ed estensioni allo stesso ID qui.
  3. Vai alla directory dell'app installata (si tratta di una versione inclusa nell'ID dell'app). Apri il manifest.json installato (pico è un modo rapido per aprire il file).
  4. Copia la "chiave" nel file manifest.json installato e incollala nel file manifest di origine dell'app.

Ottenere l'ID client OAuth2

Per ottenere l'ID client, devi registrare la tua app nella console API di Google:

  1. Accedi alla console API di Google utilizzando lo stesso Account Google utilizzato per caricare l'app sul Chrome Web Store.
  2. Per creare un nuovo progetto, espandi il menu a discesa nell'angolo in alto a sinistra e seleziona la voce di menu Crea....
  3. Dopo aver creato e assegnato un nome, vai alla voce del menu di navigazione "Servizi" e attiva gli eventuali servizi Google di cui la tua app ha bisogno.
  4. Vai alla voce di menu di navigazione "Accesso API" e fai clic sul pulsante blu Crea un ID client OAuth 2.0.
  5. Inserisci le informazioni sul branding richieste, seleziona il tipo Applicazione installata.
  6. Seleziona Applicazione di Chrome e inserisci l'ID applicazione (lo stesso ID visualizzato nella pagina di gestione di app ed estensioni).

Aggiorna il manifest con l'ID client e gli ambiti OAuth2

Devi aggiornare il file manifest in modo da includere l'ID client e gli ambiti. Ecco l'esempio "oauth2" per il sample gdrive:

"oauth2": {
    "client_id": "665859454684.apps.googleusercontent.com",
    "scopes": [
      "https://www.googleapis.com/auth/drive"
    ]
  }

Ottieni token di accesso

Ora puoi ottenere il token di autenticazione chiamando identity.getAuthToken.

chrome.identity.getAuthToken({ 'interactive': true }, function(token) {
  // Use the token.
});

Interazione utente

Quando chiami getAuthToken, puoi passare un flag ('interactive': true nell'esempio precedente) che indica se vuoi che l'API venga chiamata in modalità interattiva o silenziosa. Se richiami l'API in modalità interattiva, all'utente viene mostrata un'interfaccia utente di accesso e/o approvazione quando necessario, come mostrato nello screenshot seguente:

screenshot che mostra l'interfaccia utente quando un'app utilizza l'API Identity per autenticare un Account Google

Se richiami l'API in modalità silenziosa, l'API restituirà un token solo se è possibile produrne uno senza mostrare alcuna interfaccia utente. Questo è utile, ad esempio, quando un'app esegue il flusso all'avvio o in generale nei casi in cui non è coinvolto alcun gesto dell'utente.

La best practice che suggeriamo è di utilizzare la modalità silenziosa quando non è previsto alcun gesto dell'utente e di utilizzare la modalità interattiva se è presente un gesto dell'utente (ad esempio, l'utente ha fatto clic sul pulsante Accedi nell'app). Tieni presente che non applichiamo alcun requisito relativo ai gesti.

Memorizzazione nella cache

Chrome ha una cache in memoria dei token di accesso, quindi puoi chiamare getAuthToken ogni volta che devi utilizzare un token. La scadenza del token viene gestita automaticamente dalla cache.

Puoi vedere lo stato attuale della cache dei token su chrome://identity-internals.

In alcuni casi, ad esempio quando l'utente cambia la password, i token di accesso non scaduti smetteranno di funzionare. Le chiamate API che utilizzano il token inizieranno a tornare con un codice di stato HTTP 401. Se lo rilevi, puoi rimuovere il token non valido dalla cache di Chrome chiamando identity.removeCachedAuthToken.

Esempio di utilizzo di removeCachedAuthToken:

// callback = function (error, httpStatus, responseText);
function authenticatedXhr(method, url, callback) {
  var retry = true;
  function getTokenAndXhr() {
    chrome.identity.getAuthToken({/* details */},
                                 function (access_token) {
      if (chrome.runtime.lastError) {
        callback(chrome.runtime.lastError);
        return;
      }

      var xhr = new XMLHttpRequest();
      xhr.open(method, url);
      xhr.setRequestHeader('Authorization',
                           'Bearer ' + access_token);

      xhr.onload = function () {
        if (this.status === 401 && retry) {
          // This status may indicate that the cached
          // access token was invalid. Retry once with
          // a fresh token.
          retry = false;
          chrome.identity.removeCachedAuthToken(
              { 'token': access_token },
              getTokenAndXhr);
          return;
        }

        callback(null, this.status, this.responseText);
      }
    });
  }
}

Autenticazione dell'account non Google

Ecco i tre passaggi da completare:

  1. Registrati con il fornitore.
  2. Aggiungi le autorizzazioni per le risorse del provider a cui avrà accesso la tua app.
  3. Recupera il token di autenticazione.

Registrati con il provider

Devi registrare un ID client OAuth2 con il provider e configurare l'ID client come sito web. Per l'URI di reindirizzamento da inserire durante la registrazione, utilizza l'URL del modulo: https://<extension-id>.chromiumapp.org/<anything-here>

Ad esempio, se l'ID app è abcdefghijklmnopqrstuvwxyzabcdef e vuoi che provider_cb sia il percorso, per distinguerlo dagli URI di reindirizzamento di altri provider, devi utilizzare: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

Aggiungi le autorizzazioni per il fornitore

Per eseguire richieste XHR cross-origin agli endpoint dell'API del fornitore, devi inserire nella lista consentita i pattern appropriati nelle autorizzazioni:

"permissions": [
  ...
  "https://www.website-of-provider-with-user-photos.com/photos/*"
]

Ottieni il token

Per ottenere il token:

chrome.identity.launchWebAuthFlow(
  {'url': '<url-to-do-auth>', 'interactive': true},
  function(redirect_url) { /* Extract token from redirect_url */ });

<url-to-do-auth> è l'URL utilizzato per eseguire l'autenticazione del provider da un sito web. Ad esempio, supponiamo che tu stia eseguendo il flusso OAuth2 con un fornitore e che tu abbia registrato la tua app con l'ID cliente 123456789012345 e che tu voglia accedere alle foto dell'utente sul sito web del fornitore: https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345& redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&response_type=token&scope=user_photos

Il fornitore eseguirà l'autenticazione e, se opportuno, mostrerà all'utente l'interfaccia utente di accesso e/o approvazione. Verrà eseguito il reindirizzamento a https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>

Chrome lo acquisirà e chiamerà il callback dell'app con l'URL di reindirizzamento completo. L'app dovrebbe estrarre il token dall'URL.

Confronto tra modalità interattiva e modalità silenziosa

Quando chiami launchWebAuthFlow, puoi passare un flag ('interactive': true nell'esempio precedente) che indica se vuoi che l'API venga chiamata in modalità interattiva o meno (ovvero in modalità silenziosa). Se richiami l'API in modalità interattiva, all'utente viene mostrata, se necessario, l'interfaccia utente per ottenere il token (UI di accesso e/o interfaccia utente di approvazione o, in tal caso, qualsiasi UI specifica del provider).

Se richiami l'API in modalità silenziosa, l'API restituirà un token solo se il fornitore è in grado di fornire un token senza mostrare alcuna interfaccia utente. Ciò è utile, ad esempio, nei casi in cui un'app esegue il flusso all'avvio dell'app, o in generale nei casi in cui non sia previsto alcun gesto dell'utente.

La best practice che suggeriamo è di utilizzare la modalità silenziosa quando non è previsto alcun gesto dell'utente e di utilizzare la modalità interattiva se è presente un gesto dell'utente (ad esempio, l'utente ha fatto clic sul pulsante Accedi nell'app). Tieni presente che non applichiamo il requisito relativo ai gesti.