Utiliser le modèle de jeton

La bibliothèque JavaScript google.accounts.oauth2 vous aide à demander le consentement de l'utilisateur et à obtenir un jeton d'accès pour exploiter les données utilisateur. Il est basé sur le flux d'octroi implicite OAuth 2.0 et est conçu pour vous permettre d'appeler directement des API Google à l'aide de REST et CORS, ou d'utiliser la bibliothèque cliente des API Google pour JavaScript (également appelée gapi.client) pour un accès simple et flexible à nos API plus complexes.

Avant d'accéder aux données utilisateur protégées depuis un navigateur, les utilisateurs de votre site déclenchent les processus de sélection de compte, de connexion et de consentement de Google sur le Web. Enfin, les serveurs OAuth de Google génèrent et renvoient un jeton d'accès à votre application Web.

Dans le modèle d'autorisation par jeton, il n'est pas nécessaire de stocker des jetons d'actualisation par utilisateur sur votre serveur backend.

Il est recommandé de suivre l'approche décrite ici plutôt que les techniques abordées dans l'ancien guide OAuth 2.0 pour les applications Web côté client.

Prérequis

Recherchez ou créez un ID client en suivant la procédure décrite dans le guide Obtenir votre ID client pour les API Google. Ensuite, ajoutez la bibliothèque cliente aux pages de votre site qui appelleront les API Google. Enfin, initialisez le client de jeton. En règle générale, cette opération s'effectue dans le gestionnaire onload de la bibliothèque cliente.

Initialiser un client de jeton

Appelez initTokenClient() pour initialiser un nouveau client de jeton avec l'ID client de votre application Web. Vous pouvez éventuellement inclure une liste d'un ou plusieurs champs d'application auxquels l'utilisateur doit accéder:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

Déclencher le flux de jetons OAuth 2.0

Utilisez la méthode requestAccessToken() pour déclencher le flux d'expérience utilisateur du jeton et obtenir un jeton d'accès. Google invite l'utilisateur à effectuer les actions suivantes:

  • Choisissez son compte,
  • connectez-vous au compte Google si ce n'est pas déjà fait.
  • autoriser votre application Web à accéder à chaque champ d'application demandé.

Un geste de l'utilisateur déclenche le flux du jeton: <button onclick="client.requestAccessToken();">Authorize me</button>

Google renvoie ensuite un TokenResponse contenant un jeton d'accès et la liste des niveaux d'accès auxquels l'utilisateur a accordé l'accès, ou une erreur, à votre gestionnaire de rappel.

Les utilisateurs peuvent fermer le sélecteur de compte ou les fenêtres de connexion. Dans ce cas, votre fonction de rappel ne sera pas appelée.

La conception et l'expérience utilisateur de votre application ne doivent être implémentées qu'après un examen approfondi des règles OAuth 2.0 de Google. Ces règles couvrent l'utilisation de plusieurs champs d'application, et la manière de gérer le consentement de l'utilisateur et plus encore.

L'autorisation incrémentielle est une méthodologie de stratégie et de conception d'application utilisée pour demander l'accès aux ressources, en utilisant les champs d'application, uniquement en fonction des besoins plutôt qu'en une seule fois. Les utilisateurs peuvent approuver ou refuser le partage des ressources individuelles demandées par votre application. C'est ce qu'on appelle des autorisations précises.

Au cours de ce processus, Google demande le consentement de l'utilisateur en répertoriant individuellement chaque champ d'application demandé, les utilisateurs sélectionnent les ressources à partager avec votre application. Enfin, Google appelle votre fonction de rappel pour renvoyer un jeton d'accès et les niveaux d'accès approuvés par l'utilisateur. Votre application gère ensuite en toute sécurité les différents résultats possibles avec des autorisations précises.

Autorisation incrémentielle

Pour les applications Web, les deux scénarios de haut niveau suivants mettent en évidence l'autorisation incrémentielle à l'aide de:

  • Application Ajax d'une seule page, utilisant souvent XMLHttpRequest avec un accès dynamique aux ressources.
  • Plusieurs pages Web, les ressources sont séparées et gérées page par page.

Ces deux scénarios sont présentés pour illustrer des considérations et des méthodologies de conception, mais ils ne constituent pas des recommandations complètes sur la façon d'intégrer le consentement dans votre application. Les applications réelles peuvent utiliser une variante ou une combinaison de ces techniques.

Ajax

Ajoutez la prise en charge de l'autorisation incrémentielle à votre application en effectuant plusieurs appels à requestAccessToken() et en utilisant le paramètre scope de l'objet OverridableTokenClientConfig pour demander des champs d'application individuels au moment où ils sont nécessaires et uniquement lorsque cela est nécessaire. Dans cet exemple, les ressources ne sont demandées et visibles qu'après le développement d'une section de contenu réduite par un geste de l'utilisateur.

Application Ajax
Initialisez le client de jeton lors du chargement de la page :
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
      
Demandez le consentement des utilisateurs et obtenez des jetons d'accès à l'aide de gestes utilisateur, puis cliquez sur "+" pour ouvrir:

Documents à lire

Afficher les documents récents

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );
        

Événements à venir

Afficher les informations de l'agenda

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );
        

Afficher des photos

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );
        

Chaque appel à requestAccessToken déclenche un moment de consentement de l'utilisateur. Votre application n'aura accès qu'aux ressources requises par la section qu'un utilisateur choisit de développer, ce qui limitera le partage des ressources par le biais du choix de l'utilisateur.

Plusieurs pages Web

Lors de la conception d'une autorisation incrémentielle, plusieurs pages sont utilisées pour ne demander que les champs d'application requis pour charger une page. Cela réduit la complexité et la nécessité d'effectuer plusieurs appels pour obtenir le consentement de l'utilisateur et récupérer un jeton d'accès.

Application multipage
Page Web Code
Page 1. Docs à lire
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
          
Page 2. Événements à venir
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
          
Page 3. Carrousel de photos
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();
          

Chaque page demande le champ d'application nécessaire et obtient un jeton d'accès en appelant initTokenClient() et requestAccessToken() au moment du chargement. Dans ce scénario, des pages Web individuelles sont utilisées pour séparer clairement les fonctionnalités et ressources utilisateur par champ d'application. En situation réelle, des pages individuelles peuvent demander plusieurs champs d'application associés.

Autorisations précises

Les autorisations précises sont traitées de la même manière dans tous les scénarios. Une fois que requestAccessToken() a appelé votre fonction de rappel et renvoyé un jeton d'accès, vérifiez que l'utilisateur a approuvé les champs d'application demandés à l'aide de hasGrantedAllScopes() ou de hasGrantedAnyScope(). Exemple :

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

Toutes les autorisations précédemment acceptées issues de sessions ou de requêtes précédentes sont également incluses dans la réponse. Un enregistrement du consentement de l'utilisateur est conservé par utilisateur et par ID client, et persiste entre plusieurs appels à initTokenClient() ou requestAccessToken(). Par défaut, le consentement de l'utilisateur n'est nécessaire que la première fois qu'un utilisateur visite votre site Web et demande un nouveau champ d'application. Toutefois, il peut être demandé à chaque chargement de page à l'aide de prompt=consent dans les objets de configuration du client de jetons.

Utiliser des jetons

Dans le modèle de jeton, un jeton d'accès n'est pas stocké par le système d'exploitation ni par le navigateur. À la place, un nouveau jeton est obtenu d'abord au moment du chargement de la page, ou par la suite en déclenchant un appel à requestAccessToken() via un geste de l'utilisateur, tel qu'une pression sur un bouton.

Utiliser REST et CORS avec les API Google

Un jeton d'accès peut être utilisé pour envoyer des requêtes authentifiées aux API Google à l'aide de REST et CORS. Cela permet aux utilisateurs de se connecter, d'accorder leur autorisation, à Google d'émettre un jeton d'accès et à votre site d'utiliser leurs données.

Dans cet exemple, affichez les événements d'agenda à venir des utilisateurs connectés à l'aide du jeton d'accès renvoyé par tokenRequest():

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

Pour en savoir plus, consultez Utiliser CORS pour accéder aux API Google.

La section suivante explique comment intégrer facilement des API plus complexes.

Utilisation de la bibliothèque JavaScript des API Google

Le client de jeton fonctionne avec la bibliothèque cliente des API Google pour JavaScript. Consultez l'extrait de code ci-dessous.

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

Expiration des jetons

Les jetons d'accès ont une courte durée de vie. Si le jeton d'accès expire avant la fin de la session de l'utilisateur, obtenez-en un nouveau en appelant requestAccessToken() à partir d'un événement piloté par l'utilisateur, comme l'appui sur un bouton.

Appelez la méthode google.accounts.oauth2.revoke afin de supprimer le consentement de l'utilisateur et l'accès aux ressources pour tous les niveaux d'accès accordés à votre application. Un jeton d'accès valide est nécessaire pour révoquer cette autorisation:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });