La bibliothèque JavaScript google.accounts.oauth2 vous aide à demander le consentement de l'utilisateur et à obtenir un jeton d'accès pour travailler avec les données utilisateur. Il est basé sur le droit d'accès implicite OAuth 2.0 et conçu pour vous permettre d'appeler directement les API Google à l'aide de REST et de CORS, ou d'utiliser notre 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 à partir d'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 basé sur les jetons, il n'est pas nécessaire de stocker des jetons d'actualisation par utilisateur sur votre serveur backend.
Nous vous recommandons de suivre l'approche décrite ici plutôt que les techniques décrites dans l'ancien guide OAuth 2.0 pour les applications Web côté client.
Configuration
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 est effectuée dans le gestionnaire onload de la bibliothèque cliente.
Initialiser un client de jetons
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 de 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 à:
- choisir son compte ;
- se connecter au compte Google s'il n'est pas déjà connecté ;
- accordez le consentement pour que votre application Web accède à chaque champ d'application demandé.
Un geste de l'utilisateur déclenche le flux de jetons: <button onclick="client.requestAccessToken();">Authorize me</button>
Google renvoie ensuite un TokenResponse contenant un jeton d'accès et une liste des champs d'application 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, auquel cas votre fonction de rappel ne sera pas appelée.
Gérer le consentement
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, le moment et la manière de gérer le consentement de l'utilisateur, et plus encore.
L'autorisation incrémentielle est une méthodologie de conception de règles et d'applications utilisée pour demander l'accès aux ressources, à l'aide de champs d'application, uniquement si nécessaire plutôt que d'emblée et tout à la fois. Les utilisateurs peuvent approuver ou refuser le partage des ressources individuelles demandées par votre application. Il s'agit des autorisations précises.
Au cours de ce processus, Google demande le consentement de l'utilisateur, en listant 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 champs d'application approuvés par l'utilisateur. Votre application gère ensuite de manière sécurisée les différents résultats possibles avec des autorisations précises.
Il existe toutefois des exceptions. Les applications Google Workspace Enterprise avec une délégation d'autorité au niveau du domaine ou les applications marquées comme Approuvées contournent l'écran de consentement aux autorisations précises. Pour ces applications, les utilisateurs ne verront pas l'écran de consentement aux autorisations précises. Au lieu de cela, votre application recevra tous les champs d'application demandés ou aucun.
Pour en savoir plus, consultez Gérer les autorisations précises.
Autorisation incrémentielle
Pour les applications Web, les deux scénarios d'autorisation incrémentielle suivants illustrent l'utilisation des éléments suivants:
- Application Ajax monopage, souvent utilisant
XMLHttpRequestavec un accès dynamique aux ressources. - Les ressources de plusieurs pages Web sont séparées et gérées par page.
Ces deux scénarios sont présentés pour illustrer les considérations et les méthodologies de conception, mais ne sont pas destinés à fournir 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 portées individuelles au moment où elles sont nécessaires et uniquement lorsque cela est nécessaire. Dans cet exemple, les ressources ne sont demandées et visibles qu'après un geste de l'utilisateur qui développe une section de contenu réduite.
| Application Ajax |
|---|
Initialisez le client de jetons lors du chargement de la page:
const client = google.accounts.oauth2.initTokenClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
callback: "onTokenResponse",
});
Documents à lireAfficher les documents récents
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/documents.readonly'
})
);
Événements à venirAfficher les informations de l'agenda
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/calendar.readonly'
})
);
Carrousel de photosAfficher des photos
client.requestAccessToken(
overrideConfig = ({
scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
})
);
|
Chaque appel à requestAccessToken déclenche un moment d'autorisation de l'utilisateur. Votre application n'aura accès qu'aux ressources requises par la section qu'un utilisateur choisit d'étendre, limitant ainsi le partage de ressources en fonction du choix de l'utilisateur.
Plusieurs pages Web
Lorsque vous concevez pour une autorisation incrémentielle, plusieurs pages sont utilisées pour ne demander que le ou les champs d'application requis pour charger une page, ce qui 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 | ||||||||
|---|---|---|---|---|---|---|---|---|
|
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 les ressources utilisateur par champ d'application. Dans la pratique, des pages individuelles peuvent demander plusieurs champs d'application associés.
Autorisations précises
Les autorisations précises sont gérées de la même manière dans tous les scénarios. Une fois que requestAccessToken() a appelé votre fonction de rappel et qu'un jeton d'accès a été renvoyé, vérifiez que l'utilisateur a approuvé les champs d'application demandés à l'aide de hasGrantedAllScopes() ou 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 lors 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 sur plusieurs appels à initTokenClient() ou requestAccessToken(). Par défaut, le consentement de l'utilisateur n'est nécessaire que la première fois qu'il accède à votre site Web et demande un nouveau champ d'application, mais 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 l'OS ou le navigateur. Un nouveau jeton est d'abord obtenu 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'un appui 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 de CORS. Cela permet aux utilisateurs de se connecter, d'accorder leur consentement, à Google d'émettre un jeton d'accès et à votre site de travailler avec les données de l'utilisateur.
Dans cet exemple, affichez les événements d'agenda à venir de l'utilisateur connecté à 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.
Utiliser 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
De par leur conception, les jetons d'accès ont une durée de vie courte. Si le jeton d'accès expire avant la fin de la session de l'utilisateur, obtenez un nouveau jeton en appelant requestAccessToken() à partir d'un événement déclenché par l'utilisateur, tel qu'un appui sur un bouton.
Utiliser un jeton d'accès pour révoquer le consentement
Appelez la méthode google.accounts.oauth2.revoke pour 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 requis 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);
});