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 proprio 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 il secondo.

Come funziona

Gli utenti delle app di Chrome hanno un Account Google associato al proprio 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 dei provider e acquisisce i reindirizzamenti a pattern URL specifici. Gli URL di reindirizzamento vengono trasmessi all'app e l'app estrae il token dall'URL.

Autenticazione dell'Account Google

Ecco i cinque passaggi da completare:

  1. Aggiungi le autorizzazioni al file manifest e carica l'app.
  2. Copia la chiave nel file manifest.json installato nel tuo 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 in modo da includere l'ID client e gli ambiti.
  5. Recupera il token di autenticazione.

Aggiungi autorizzazioni e carica app

Devi assicurarti che l'autorizzazione per l'identità sia presente nel file manifest. Successivamente, puoi caricare l'app nella pagina di gestione di app ed estensioni (vedi Pubblicazione).

"permissions": [
  "identity"
]

Copia la chiave nel file manifest

Quando registri la tua applicazione nella console OAuth di Google, dovrai fornire il relativo ID, che verrà controllato durante le richieste dei token. È quindi importante avere un ID applicazione coerente durante lo sviluppo.

Per mantenere costante l'ID applicazione, devi copiare la chiave nel file manifest.json installato nel file manifest di origine. Non è l'attività più impegnativa, ma ecco come va:

  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 (sarà una versione all'interno dell'ID dell'app). Apri l'app manifest.json installata (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 l'app nella console API di Google:

  1. Accedi alla Console API di Google con 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 averlo creato e denominato, vai alla voce del menu di navigazione "Servizi" e attiva tutti i servizi Google di cui la tua app ha bisogno.
  4. Vai alla voce del menu di navigazione "Accesso API" e fai clic sul pulsante blu Crea un ID client OAuth 2.0....
  5. Inserisci le informazioni di branding richieste e seleziona il tipo Applicazione installata.
  6. Seleziona Applicazione Chrome e inserisci il tuo ID applicazione (stesso ID visualizzato nella pagina di gestione di app ed estensioni).

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

Devi aggiornare il file manifest in modo che includa l'ID client e gli ambiti. Ecco un esempio "oauth2 " per l'esempio gdrive:

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

Recuperare i token di accesso

Ora è tutto pronto per 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 sopra) che indica se vuoi che l'API venga chiamata in modalità interattiva o silenziosa. Se richiami l'API in modalità interattiva, all'utente verrà mostrata una UI di accesso e/o approvazione quando necessario, come mostrato nello screenshot di seguito:

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 generarne uno senza mostrare alcuna UI. Questo è utile nei casi in cui un'app esegue il flusso all'avvio dell'app, ad esempio, o in generale nei casi in cui non è richiesto alcun gesto dell'utente.

La best practice consigliata prevede l'utilizzo della modalità silenziosa quando non è previsto alcun gesto dell'utente e la modalità interattiva se è presente un gesto dell'utente (ad esempio, se l'utente ha fatto clic sul pulsante Accedi nella tua app). Tieni presente che non applichiamo requisiti relativi ai gesti.

Memorizzazione nella cache

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

Puoi visualizzare lo stato attuale della cache del token su chrome://identity-internals.

In alcuni casi, ad esempio quando l'utente cambia la password, i token di accesso non scaduti smettono di funzionare. Le chiamate API che utilizzano il token inizieranno con un codice di stato HTTP 401. Se rilevi questo problema, 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 di account non Google

Ecco i tre passaggi da completare:

  1. Registrati con il provider.
  2. Aggiungi autorizzazioni per le risorse del provider a cui accederà 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 nel 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 con gli URI di reindirizzamento di altri provider devi utilizzare: https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb

Aggiungi autorizzazioni per il provider

Per creare XHR multiorigine negli endpoint API del provider, devi inserire nella lista consentita i pattern appropriati nelle autorizzazioni:

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

Recupera 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 per eseguire l'autenticazione al provider da un sito web. Ad esempio, supponiamo che tu stia eseguendo un flusso OAuth2 con un provider, che abbia registrato la tua app con l'ID client 123456789012345 e che voglia accedere alle foto dell'utente sul sito web del provider: 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 provider eseguirà l'autenticazione e, se opportuno, mostrerà all'utente l'interfaccia utente di accesso e/o approvazione. quindi ti reindirizzerà a https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=<auth-token>

Chrome lo acquisisce e richiama il callback dell'app con l'URL di reindirizzamento completo. L'app deve estrarre il token dall'URL.

Modalità interattiva e silenzioso

Quando chiami launchWebAuthFlow, puoi passare un flag ('interactive': true nell'esempio sopra) che indica se vuoi che l'API venga chiamata o meno in modalità interattiva (ovvero in modalità silenziosa). Se richiami l'API in modalità interattiva, all'utente viene mostrata la UI, se necessario, per ottenere il token (UI di accesso e/o UI 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 provider è in grado di fornire un token senza mostrare alcuna UI. Questo è utile nei casi in cui un'app esegue il flusso all'avvio, ad esempio, o in generale nei casi in cui non è previsto alcun gesto dell'utente.

La best practice consigliata prevede l'utilizzo della modalità silenziosa quando non è previsto alcun gesto dell'utente e la modalità interattiva se è presente un gesto dell'utente (ad esempio, se l'utente ha fatto clic sul pulsante Accedi nella tua app). Tieni presente che non applichiamo requisiti relativi ai gesti.