Ce document explique comment les applications de bureau (telles que les applications s'exécutant sous Windows, macOS ou Linux, ou les outils d'interface de ligne de commande (CLI)) utilisent les points de terminaison OAuth 2.0 de Google pour autoriser l'accès aux API Google.
OAuth 2.0 permet aux utilisateurs de partager certaines données avec une application tout en préservant la confidentialité de leurs noms d'utilisateur, mots de passe et autres informations. Par exemple, une application peut utiliser OAuth 2.0 pour obtenir l'autorisation des utilisateurs de stocker des fichiers dans leur Google Drive.
Les applications de bureau sont installées localement sur l'ordinateur d'un utilisateur (par exemple, un logiciel de bureau autonome, des outils de CLI pour les développeurs, des utilitaires de synchronisation en arrière-plan ou des scripts). Étant donné que ces applications sont distribuées sur des appareils individuels, on suppose qu'elles ne peuvent pas garder de secrets (ce sont des clients publics). Ils peuvent accéder aux API Google lorsque l'utilisateur interagit activement avec l'application ou lorsque l'application s'exécute en arrière-plan.
Ce flux d'autorisation est semblable à celui utilisé pour les applications de serveur Web. La principale différence est que les applications de bureau doivent ouvrir le navigateur du système et fournir un URI de redirection local (comme une adresse IP de bouclage) pour gérer les réponses du serveur d'autorisation de Google.
Bibliothèques et exemples
Nous vous recommandons d'utiliser les bibliothèques clientes des API Google pour votre langage de programmation (par exemple, Python, Java, Node.js, Go, .NET) lorsque vous implémentez OAuth 2.0 pour les applications de bureau. Les bibliothèques clientes gèrent l'autorisation des utilisateurs et la gestion des jetons, ce qui rend l'implémentation plus simple et moins sujette aux erreurs que l'utilisation directe des points de terminaison HTTP/REST de niveau inférieur.
Pour les applications mobiles, consultez les guides d'autorisation pour Android et iOS.
Pour les applications exécutées sur des appareils qui ne sont pas compatibles avec un navigateur système ou qui ont des capacités de saisie limitées, comme les téléviseurs, les consoles de jeu, les appareils photo ou les imprimantes, consultez OAuth 2.0 pour les téléviseurs et les appareils ou Connexion sur les téléviseurs et les appareils à saisie limitée.
Prérequis
Activer les API pour votre projet.
Toute application qui appelle des API Google doit activer ces API dans la console d'API.
Pour activer une API pour votre projet :
- Dans la console Google APIs, ouvrez la bibliothèque des API.
- Si vous y êtes invité, sélectionnez un projet ou créez-en un.
- La bibliothèque d'API répertorie toutes les API disponibles, regroupées par famille de produits et par popularité. Si l'API que vous souhaitez activer n'apparaît pas dans la liste, utilisez la recherche pour la trouver ou cliquez sur Tout afficher dans la famille de produits à laquelle elle appartient.
- Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
- Si vous y êtes invité, activez la facturation.
- Si vous y êtes invité, lisez et acceptez les conditions d'utilisation de l'API.
Créer des identifiants d'autorisation
Toute application qui utilise OAuth 2.0 pour accéder aux API Google doit disposer d'identifiants d'autorisation qui l'identifient auprès du serveur OAuth 2.0 de Google. Les étapes suivantes expliquent comment créer des identifiants pour votre projet. Vos applications peuvent ensuite utiliser les identifiants pour accéder aux API que vous avez activées pour ce projet.
- Accédez à la page Clients.
- Cliquez sur Créer un client.
- Sélectionnez le type d'application Application de bureau.
- Dans le champ Nom, saisissez un nom pour le client OAuth. Ce nom s'affiche sur la page "Clients" de votre projet pour identifier le client.
- Cliquez sur Créer.
Votre ID client et votre code secret du client sont générés et affichés dans la console Google Cloud. Les applications de bureau sont des clients publics et ne peuvent pas préserver la confidentialité des secrets. Utilisez toujours PKCE (clé de vérification pour l'échange de code) lorsque vous demandez des codes d'autorisation.
Identifier les niveaux d'accès
Les champs d'application permettent à votre application de ne demander l'accès qu'aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils accordent à votre application. Il peut donc y avoir une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur.
Avant de commencer à implémenter l'autorisation OAuth 2.0, nous vous recommandons d'identifier les champs d'application auxquels votre application devra être autorisée à accéder.
Le document Champs d'application de l'API OAuth 2.0 contient la liste complète des champs d'application que vous pouvez utiliser pour accéder aux API Google.
Obtenir des jetons d'accès OAuth 2.0
Les étapes suivantes montrent comment votre application interagit avec le serveur OAuth 2.0 de Google pour obtenir le consentement d'un utilisateur afin d'effectuer une requête API en son nom. Votre application doit obtenir ce consentement avant de pouvoir exécuter une requête d'API Google nécessitant l'autorisation de l'utilisateur.
Étape 1 : Générer un vérificateur de code et un code de vérification
Google est compatible avec le protocole Proof Key for Code Exchange (PKCE) pour sécuriser davantage le flux d'application installée. Un vérificateur de code unique est créé pour chaque demande d'autorisation, et sa valeur transformée, appelée "code_challenge", est envoyée au serveur d'autorisation pour obtenir le code d'autorisation.
Créer le vérificateur de code
Un code_verifier est une chaîne aléatoire cryptographique à entropie élevée utilisant les caractères non réservés [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", d'une longueur minimale de 43 caractères et d'une longueur maximale de 128 caractères.
Le code de validation doit avoir un degré d'entropie suffisant pour qu'il soit impossible de deviner la valeur.
Créer le code de vérification
Deux méthodes de création du code challenge sont acceptées.
| Méthodes de génération de code challenge | |
|---|---|
| S256 (recommandé) | Le code challenge est le hachage SHA256 encodé en Base64URL (sans marge intérieure) du code verifier.
|
| plain | Le code challenge est identique au code verifier généré ci-dessus.
|
Étape 2 : Envoyer une requête au serveur OAuth 2.0 de Google
Pour obtenir l'autorisation de l'utilisateur, envoyez une requête au serveur d'autorisation de Google à l'adresse https://accounts.google.com/o/oauth2/v2/auth. Ce point de terminaison gère la recherche de session active, authentifie l'utilisateur et obtient son consentement. Le point de terminaison n'est accessible que via SSL et refuse les connexions HTTP (non SSL).
Le serveur d'autorisation accepte les paramètres de chaîne de requête suivants pour les applications installées :
| Paramètres | |||||||
|---|---|---|---|---|---|---|---|
client_id |
Obligatoire
ID client de votre application. Vous trouverez cette valeur sur la page Clients de la console Cloud. |
||||||
redirect_uri |
Obligatoire
Détermine la manière dont le serveur d'autorisation de Google envoie une réponse à votre application. Plusieurs options de redirection sont disponibles pour les applications installées. Vous devez configurer vos identifiants d'autorisation en tenant compte d'une méthode de redirection particulière. La valeur doit correspondre exactement à l'un des URI de redirection autorisés pour le client OAuth 2.0, que vous avez configuré sur la page Clients de la console Cloud de votre client. Si cette valeur ne correspond pas à un URI autorisé, vous obtiendrez une erreur Le tableau indique la valeur de paramètre
|
||||||
response_type |
Obligatoire
Détermine si le point de terminaison Google OAuth 2.0 renvoie un code d'autorisation. Définissez la valeur du paramètre sur |
||||||
scope |
Obligatoire
Liste de champs d'application délimités par des espaces qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs sont utilisées pour l'écran de consentement que Google affiche à l'utilisateur. Les champs d'application permettent à votre application de ne demander l'accès qu'aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils accordent à votre application. Il existe donc une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement utilisateur. |
||||||
code_challenge |
Recommandé
Spécifie un |
||||||
code_challenge_method |
Recommandé
Spécifie la méthode utilisée pour encoder un |
||||||
state |
Recommandé
Spécifie toute valeur de chaîne que votre application utilise pour maintenir l'état entre votre demande d'autorisation et la réponse du serveur d'autorisation.
Le serveur renvoie la valeur exacte que vous envoyez sous forme de paire Vous pouvez utiliser ce paramètre à plusieurs fins, par exemple pour diriger l'utilisateur vers la ressource appropriée dans votre application, envoyer des codes d'usage unique et limiter les falsifications de requêtes intersites. Étant donné que votre |
||||||
login_hint |
Optional
Si votre application sait quel utilisateur tente de s'authentifier, elle peut utiliser ce paramètre pour fournir un indice au serveur d'authentification Google. Le serveur utilise l'indice pour simplifier le flux de connexion, soit en préremplissant le champ d'adresse e-mail dans le formulaire de connexion, soit en sélectionnant la session de connexion multiple appropriée. Définissez la valeur du paramètre sur une adresse e-mail ou un identifiant |
||||||
Exemples d'URL d'autorisation
Les onglets ci-dessous présentent des exemples d'URL d'autorisation pour les différentes options d'URI de redirection.
Les URL sont identiques, à l'exception de la valeur du paramètre redirect_uri. Les URL contiennent également les paramètres obligatoires response_type et client_id, ainsi que le paramètre facultatif state. Chaque URL contient des sauts de ligne et des espaces pour des raisons de lisibilité.
Schéma d'URI personnalisé
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=com.example.app%3A/oauth2redirect& client_id=client_id
Adresse IP de bouclage
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& response_type=code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken& redirect_uri=http%3A//127.0.0.1%3A9004& client_id=client_id
Étape 3 : Google demande le consentement de l'utilisateur
À cette étape, l'utilisateur décide d'accorder ou non l'accès demandé à votre application. À ce stade, Google affiche une fenêtre de consentement indiquant le nom de votre application et les services d'API Google auxquels elle demande l'accès avec les identifiants d'autorisation de l'utilisateur, ainsi qu'un récapitulatif des niveaux d'accès à accorder. L'utilisateur peut alors accepter d'accorder l'accès à un ou plusieurs champs d'application demandés par votre application, ou refuser la demande.
Votre application n'a rien à faire à ce stade, car elle attend la réponse du serveur OAuth 2.0 de Google indiquant si l'accès a été accordé. Cette réponse est expliquée à l'étape suivante.
Erreurs
Les requêtes envoyées au point de terminaison d'autorisation OAuth 2.0 de Google peuvent afficher des messages d'erreur visibles par l'utilisateur au lieu des flux d'authentification et d'autorisation attendus. Voici les codes d'erreur courants et les solutions suggérées :
admin_policy_enforced
Le compte Google ne peut pas autoriser un ou plusieurs champs d'application demandés en raison des règles de son administrateur Google Workspace. Pour en savoir plus sur la façon dont un administrateur peut restreindre l'accès à tous les champs d'application ou aux champs d'application sensibles et restreints jusqu'à ce que l'accès soit explicitement accordé à votre ID client OAuth, consultez l'article d'aide de l'administrateur Google Workspace Contrôler quelles applications tierces et internes ont accès aux données Google Workspace.
disallowed_useragent
Le point de terminaison d'autorisation s'affiche dans un user-agent intégré non autorisé par les Règles OAuth 2.0 de Google.
Les développeurs iOS et macOS peuvent rencontrer cette erreur lorsqu'ils ouvrent des demandes d'autorisation dans WKWebView.
Les développeurs doivent plutôt utiliser des bibliothèques iOS telles que Google Sign-In pour iOS ou AppAuth pour iOS d'OpenID Foundation.
Les développeurs Web peuvent rencontrer cette erreur lorsqu'une application iOS ou macOS ouvre un lien Web général dans un user-agent intégré et qu'un utilisateur accède au point de terminaison d'autorisation OAuth 2.0 de Google depuis votre site. Les développeurs doivent autoriser l'ouverture des liens généraux dans le gestionnaire de liens par défaut du système d'exploitation, qui inclut à la fois les gestionnaires de liens universels et l'application de navigateur par défaut. La bibliothèque SFSafariViewController est également une option compatible.
org_internal
L'ID client OAuth de la requête fait partie d'un projet limitant l'accès aux comptes Google d'une organisation Google Cloud spécifique. Pour en savoir plus sur cette option de configuration, consultez la section Type d'utilisateur de l'article d'aide "Configurer votre écran de consentement OAuth".
deleted_client
Le client OAuth utilisé pour effectuer la requête a été supprimé. La suppression peut être effectuée manuellement ou automatiquement dans le cas de clients inutilisés . Les clients supprimés peuvent être restaurés dans les 30 jours suivant la suppression. En savoir plus
invalid_grant
Si vous utilisez un code verifier et un code challenge, le paramètre code_callenge est non valide ou manquant. Assurez-vous que le paramètre code_challenge est correctement défini.
Lors de l'actualisation d'un jeton d'accès, il est possible que le jeton ait expiré ou ait été invalidé. Authentifiez à nouveau l'utilisateur et demandez son consentement pour obtenir de nouveaux jetons. Si l'erreur persiste, assurez-vous que votre application a été correctement configurée et que vous utilisez les jetons et paramètres appropriés dans votre requête. Sinon, le compte utilisateur a peut-être été supprimé ou désactivé.
redirect_uri_mismatch
L'redirect_uri transmis dans la demande d'autorisation ne correspond pas à un URI de redirection autorisé pour l'ID client OAuth. Vérifiez les URI de redirection autorisés sur la page Clients de la console Google Cloud.
Le redirect_uri transmis n'est peut-être pas valide pour le type de client.
Le paramètre redirect_uri peut faire référence au flux OAuth hors bande (OOB) qui est obsolète et n'est plus compatible. Consultez le guide de migration pour mettre à jour votre intégration.
invalid_request
Un problème est survenu avec la requête que vous avez effectuée. Plusieurs raisons peuvent expliquer ce problème :
- Le format de la requête est incorrect
- La requête ne contenait pas les paramètres requis
- La requête utilise une méthode d'autorisation non compatible avec Google. Vérifier que votre intégration OAuth utilise une méthode d'intégration recommandée
- Un schéma personnalisé non compatible a été utilisé pour l'URI de redirection. Si le message d'erreur Le schéma d'URI personnalisé n'est pas compatible avec les applications Android ou Chrome s'affiche, cliquez ici pour en savoir plus sur les alternatives au schéma d'URI personnalisé.
Étape 4 : Gérer la réponse du serveur OAuth 2.0
La manière dont votre application reçoit la réponse d'autorisation dépend du schéma d'URI de redirection qu'elle utilise. Quel que soit le schéma, la réponse contiendra un code d'autorisation (code) ou une erreur (error). Par exemple, error=access_denied indique que l'utilisateur a refusé la demande.
Si l'utilisateur accorde l'accès à votre application, vous pouvez échanger le code d'autorisation contre un jeton d'accès et un jeton d'actualisation, comme décrit à l'étape suivante.
Étape 5 : Échangez le code d'autorisation contre des jetons d'actualisation et d'accès
Pour échanger un code d'autorisation contre un jeton d'accès, appelez le point de terminaison https://oauth2.googleapis.com/token et définissez les paramètres suivants :
| Champs | |
|---|---|
client_id |
ID client obtenu à partir de la page Clients de la console Cloud. |
client_secret |
Optional
Code secret du client obtenu à partir de la page Clients de la console Cloud. |
code |
Code d'autorisation renvoyé par la requête initiale. |
code_verifier |
Le vérificateur de code que vous avez créé à l'étape 1. |
grant_type |
Comme défini dans la spécification OAuth 2.0, la valeur de ce champ doit être définie sur authorization_code. |
redirect_uri |
Un des URI de redirection listés pour votre projet sur la page Clients de la console Cloud pour le client_id donné. |
Bien que l'utilisation de DPoP soit facultative, elle est recommandée pour renforcer la sécurité. La sécurité de DPoP repose sur le fait que la clé privée est limitée à un seul appareil. Nous vous recommandons de la stocker de manière à ce qu'elle ne puisse pas être copiée hors de l'appareil, par exemple en utilisant des TPM, des enclaves sécurisées ou d'autres keystores intégrés au matériel. Pour utiliser DPoP, votre application doit générer un nouveau jeton JWT de preuve DPoP unique pour chaque requête envoyée au point de terminaison du jeton et l'ajouter en tant qu'en-tête de requête HTTP.
| En-tête | Obligatoire | Description |
|---|---|---|
DPoP |
Facultatif | Une preuve DPoP est un jeton JWT qui prouve la possession d'une clé privée. Il s'agit d'un en-tête, pas d'un paramètre. S'ils sont fournis, les jetons renvoyés sont liés à cette clé. Une nouvelle preuve unique doit être générée pour chaque requête et doit inclure les revendications htm (méthode HTTP) et htu (URI HTTP) correspondant à la requête. |
L'extrait de code suivant montre un exemple de requête :
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Créer une preuve DPoP
Les étapes suivantes montrent comment créer une preuve DPoP à l'aide d'OpenSSL à partir de la ligne de commande :
- Générez une paire de clés EC P-256 :
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Créez l'en-tête DPoP :
L'en-tête doit inclure les revendications
typ,algetjwk(clé publique). Les valeursxetysont les coordonnées encodées en Base64Url de votre clé publique EC. Encodez ce JSON au format Base64Url :{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Créez la charge utile DPoP :
La charge utile doit inclure
jti(un identifiant unique pour la requête),htm(méthode HTTP, par exemplePOST),htu(URI HTTP, par exemplehttps://oauth2.googleapis.com/token) etiat(heure d'émission). Si vous avez reçu un nonce du serveur dans un en-têteDPoP-Nonceen réponse à une requête précédente, vous devez inclure cette valeur de nonce dans une revendicationnonce. La revendication nonce est facultative pour les échanges de code d'autorisation et n'est utilisée que lorsque l'en-tête DPoP-Nonce a déjà été reçu. Encodez ce JSON au format Base64Url :{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }La valeur
jtidépend du type d'échange :- Pour les échanges de codes d'autorisation,
jtidoit être le hachage SHA256 encodé en Base64Url du code d'autorisation :"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - Pour les échanges de jetons d'actualisation,
jtidoit être un identifiant unique par requête :"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- Pour les échanges de codes d'autorisation,
- Signez la preuve :
Concaténez l'en-tête et la charge utile encodés avec un point (
.), puis signez le résultat avec votre clé privée à l'aide d'ES256. Notez que JWS nécessite que la signature soit au format brutR | Sconcaténé (64 octets pour P-256). Si vous utilisez directement OpenSSL, vous devez convertir la signature par défaut encodée au format ASN.1 DER dans ce format brut.
Un échange réussi est indiqué par une réponse 200 OK contenant les jetons. Si une preuve DPoP valide est utilisée lors de l'échange, le jeton d'actualisation renvoyé par Google sera lié à votre clé par DPoP, mais les jetons d'accès ne seront pas liés par DPoP. Les jetons d'accès conserveront le token_type de Bearer plutôt que DPoP.
De plus, Google renvoie un en-tête HTTP DPoP-Nonce dans la réponse.
Votre client doit mettre en cache ce nonce et l'inclure dans la revendication nonce de la preuve DPoP dans les requêtes ultérieures (par exemple, lors de l'échange d'un jeton d'actualisation contre un nouveau jeton d'accès ou lors de l'appel d'API protégées par DPoP). En utilisant ce nonce émis de manière anticipée, vous pouvez éviter un échec d'aller-retour supplémentaire (use_dpop_nonce) lors de votre prochaine requête.
Les preuves DPoP doivent être incluses pour les requêtes d'échange de jetons effectuées avec des jetons d'actualisation liés à DPoP.
Un échec d'échange se produit si l'en-tête DPoP est manquant alors qu'il est attendu, s'il n'est pas valide ou si la preuve utilise une clé différente de celle liée au jeton. Dans ce cas, le serveur renvoie une erreur 400 Bad Request.
Si la preuve DPoP comporte des revendications htm ou htu non concordantes, un iat expiré, un jti réutilisé ou une signature non valide, Google renvoie un code d'erreur invalid_dpop_proof.
Si un nonce DPoP est requis, par exemple lors d'un échange de jeton d'actualisation, et que la preuve DPoP ne contient pas de revendication nonce, ou si la valeur du nonce n'est pas acceptable pour le serveur (par exemple, elle a expiré, a déjà été utilisée ou est incorrecte), Google renvoie un code d'erreur use_dpop_nonce ainsi qu'un en-tête HTTP DPoP-Nonce contenant un nouveau nonce que vous pouvez utiliser dans une requête ultérieure.
D'autres échecs peuvent renvoyer invalid_grant.
Google répond à cette requête en renvoyant un objet JSON contenant un jeton d'accès de courte durée et un jeton d'actualisation.
La réponse contient les champs suivants :
| Champs | |
|---|---|
access_token |
Jeton que votre application envoie pour autoriser une requête d'API Google. |
expires_in |
Durée de vie restante du jeton d'accès, en secondes. |
id_token |
Remarque : Cette propriété n'est renvoyée que si votre requête inclut un champ d'application d'identité, tel que openid, profile ou email. La valeur est un jeton Web JSON (JWT) qui contient des informations d'identité signées numériquement sur l'utilisateur. |
refresh_token |
Jeton que vous pouvez utiliser pour obtenir un nouveau jeton d'accès. Les jetons d'actualisation sont valides jusqu'à ce que l'utilisateur révoque l'accès ou que le jeton d'actualisation expire. Si DPoP a été utilisé, le jeton d'actualisation est lié à la clé privée utilisée pour signer la preuve DPoP. Notez que les jetons d'actualisation sont toujours renvoyés pour les applications installées. |
refresh_token_expires_in |
Durée de vie restante du jeton d'actualisation, en secondes. Cette valeur n'est définie que lorsque l'utilisateur accorde un accès basé sur le temps. |
scope |
Niveaux d'accès accordés par le access_token, exprimés sous la forme d'une liste de chaînes sensibles à la casse et délimitées par des espaces. |
token_type |
Type de jeton renvoyé. Cette valeur est toujours Bearer, même lorsque DPoP est utilisé. |
L'extrait de code suivant montre un exemple d'en-têtes et de corps de réponse réussis lorsque DPoP est utilisé :
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"token_type": "Bearer",
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Étape 6 : Vérifiez les habilitations accordées par les utilisateurs
Lorsque vous demandez plusieurs autorisations (champs d'application), il est possible que les utilisateurs n'accordent pas à votre application l'accès à toutes ces autorisations. Votre application doit vérifier les champs d'application qui ont été réellement accordés et gérer correctement les situations où certaines autorisations sont refusées, généralement en désactivant les fonctionnalités qui dépendent de ces champs d'application refusés.
Il existe toutefois des exceptions. Les applications Google Workspace Enterprise avec délégation d'autorité au niveau du domaine ou les applications marquées comme Approuvées contournent l'écran de consentement des autorisations précises. Pour ces applications, les utilisateurs ne verront pas l'écran de consentement des autorisations précises. Votre application recevra tous les champs d'application demandés ou aucun.
Pour en savoir plus, consultez Gérer les autorisations précises.
Pour vérifier si l'utilisateur a accordé à votre application l'accès à un champ d'application particulier, examinez le champ scope dans la réponse du jeton d'accès. Champs d'application de l'accès accordé par le jeton access_token, exprimés sous la forme d'une liste de chaînes sensibles à la casse et délimitées par des espaces.
Par exemple, l'exemple de réponse de jeton d'accès suivant indique que l'utilisateur a accordé à votre application l'accès aux autorisations d'activité Drive en lecture seule et aux événements d'agenda :
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Appeler des API Google
Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour appeler une API Google au nom d'un compte utilisateur donné, si les niveaux d'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête adressée à l'API en incluant un paramètre de requête access_token ou une valeur d'en-tête HTTP Authorization Bearer. Dans la mesure du possible, l'en-tête HTTP est préférable, car les chaînes de requête ont tendance à être visibles dans les journaux de serveur. Dans la plupart des cas, vous pouvez utiliser une bibliothèque cliente pour configurer vos appels aux API Google (par exemple, lorsque vous appelez l'API Drive Files).
Vous pouvez tester toutes les API Google et afficher leurs champs d'application sur OAuth 2.0 Playground.
Exemples de requêtes HTTP GET
Un appel au point de terminaison
drive.files (l'API Drive Files) à l'aide de l'en-tête HTTP Authorization: Bearer peut se présenter comme suit. Notez que vous devez spécifier votre propre jeton d'accès :
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Voici un appel à la même API pour l'utilisateur authentifié à l'aide du paramètre de chaîne de requête access_token :
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
curl exemples
Vous pouvez tester ces commandes avec l'application de ligne de commande curl. Voici un exemple qui utilise l'option d'en-tête HTTP (recommandée) :
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Vous pouvez également utiliser l'option de paramètre de chaîne de requête :
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Actualiser un jeton d'accès
Les jetons d'accès expirent régulièrement et deviennent des identifiants non valides pour une requête API associée. Vous pouvez actualiser un jeton d'accès sans demander l'autorisation de l'utilisateur (y compris lorsqu'il n'est pas présent) si vous avez demandé un accès hors connexion aux champs d'application associés au jeton.
Pour actualiser un jeton d'accès, votre application envoie une requête HTTPS POST au serveur d'autorisation de Google (https://oauth2.googleapis.com/token) qui inclut les paramètres suivants dans le corps de la requête :
| Nom | Valeur |
|---|---|
client_id |
ID client obtenu à partir de la console APIs. |
client_secret |
Optional
Code secret du client obtenu à partir de la console APIs.
( |
grant_type |
Comme défini dans la spécification OAuth 2.0, la valeur de ce champ doit être définie sur refresh_token. |
refresh_token |
Jeton d'actualisation renvoyé par l'échange de code d'autorisation. |
Bien que l'utilisation de DPoP soit facultative, elle est recommandée pour renforcer la sécurité. Pour utiliser DPoP avec un jeton d'actualisation, votre application doit générer un nouveau jeton JWT de preuve DPoP unique pour chaque requête envoyée au point de terminaison du jeton. Cette preuve doit être signée avec la même clé privée que celle utilisée lors de l'échange initial du code d'autorisation. Votre application ajoute la preuve en tant qu'en-tête de requête HTTP.
| En-tête | Obligatoire | Description |
|---|---|---|
DPoP |
Facultatif | Une preuve DPoP est un jeton JWT qui prouve la possession d'une clé privée. Il s'agit d'un en-tête, pas d'un paramètre. S'ils sont fournis, les jetons renvoyés sont liés à cette clé. Une nouvelle preuve unique doit être générée pour chaque requête et doit inclure les revendications htm (méthode HTTP) et htu (URI HTTP) correspondant à la requête. |
L'extrait de code suivant montre un exemple de requête :
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Pour utiliser DPoP avec un jeton d'actualisation, vous devez générer un nouveau jeton JWT de preuve DPoP unique pour la requête. Consultez Créer une preuve DPoP pour obtenir des instructions détaillées sur la génération de la paire de clés et la création du jeton JWT.
Un échange réussi est indiqué par une réponse 200 OK contenant un nouveau jeton d'accès. Lorsque DPoP est utilisé, token_type est Bearer. Une réponse réussie confirme que la preuve DPoP du jeton d'actualisation a été acceptée. Google peut également renvoyer un nouvel en-tête HTTP DPoP-Nonce dans la réponse. S'il est renvoyé, votre client doit mettre en cache ce nonce et l'inclure dans la revendication nonce de la preuve DPoP dans les requêtes ultérieures.
Un échec d'échange se produit si l'en-tête DPoP est manquant, non valide ou utilise une clé incorrecte. Pour en savoir plus sur les codes d'erreur DPoP spécifiques et la gestion des nonces, consultez Échec de l'échange.
L'extrait de code suivant montre un exemple d'en-têtes et de corps de réponse réussis lorsque DPoP est utilisé :
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}Notez que le nombre de jetons d'actualisation émis est limité : une limite par combinaison client/utilisateur et une autre par utilisateur pour tous les clients. Vous devez enregistrer les jetons d'actualisation dans un espace de stockage à long terme et continuer à les utiliser tant qu'ils restent valides. Si votre application demande trop de jetons d'actualisation, elle peut atteindre ces limites, auquel cas les anciens jetons d'actualisation cesseront de fonctionner.
Révocation des jetons
Dans certains cas, un utilisateur peut souhaiter révoquer l'accès accordé à une application. Un utilisateur peut révoquer l'accès en accédant aux paramètres du compte. Pour en savoir plus, consultez la section Supprimer l'accès d'un site ou d'une application de l'article "Sites et applications tiers ayant accès à votre compte".
Une application peut également révoquer l'accès qui lui a été accordé de manière programmatique. La révocation programmatique est importante dans les cas où un utilisateur se désabonne, supprime une application ou lorsque les ressources d'API requises par une application ont considérablement changé. En d'autres termes, une partie du processus de suppression peut inclure une requête API pour s'assurer que les autorisations précédemment accordées à l'application sont supprimées.
Pour révoquer un jeton de manière programmatique, votre application envoie une requête à https://oauth2.googleapis.com/revoke et inclut le jeton en tant que paramètre :
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Il peut s'agir d'un jeton d'accès ou d'un jeton d'actualisation. Si le jeton est un jeton d'accès et qu'il possède un jeton d'actualisation correspondant, le jeton d'actualisation sera également révoqué.
Si la révocation est traitée correctement, le code d'état HTTP de la réponse est 200. En cas d'erreur, un code d'état HTTP 400 est renvoyé, ainsi qu'un code d'erreur.
Méthodes de redirection vers l'application
Schéma d'URI personnalisé
Les schémas d'URI personnalisés sont une forme de liens profonds qui utilisent un schéma personnalisé pour ouvrir votre application.
Alternative à l'utilisation de schémas d'URI personnalisés dans les applications Chrome
Utilisez l'API Chrome Identity, qui envoie la réponse OAuth 2.0 directement à votre application, ce qui élimine le besoin d'un URI de redirection.
Adresse IP de rebouclage (macOS, Linux, Windows)
Pour recevoir le code d'autorisation à l'aide de cette URL, votre application doit écouter sur le serveur Web local. C'est possible sur de nombreuses plates-formes, mais pas toutes. Toutefois, si votre plate-forme le permet, il s'agit du mécanisme recommandé pour obtenir le code d'autorisation.
Lorsque votre application reçoit la réponse d'autorisation, pour une meilleure facilité d'utilisation, elle doit répondre en affichant une page HTML qui invite l'utilisateur à fermer le navigateur et à revenir à votre application.
| Utilisation recommandée | Applications de bureau macOS, Linux et Windows |
| Valeurs du formulaire | Définissez le type d'application sur Application de bureau. |
Copier/Coller manuel (obsolète)
Protéger vos applications
Valider la propriété de l'application pour Chrome
Vous pouvez valider la propriété de votre application pour réduire le risque d'usurpation d'identité.
Pour terminer la procédure de validation, vous devez utiliser votre compte de développeur Chrome Web Store. Pour que la validation soit réussie, les conditions suivantes doivent être remplies :
- Vous devez disposer d'un élément enregistré dans le tableau de bord du développeur Chrome Web Store avec le même ID d'élément que le client OAuth de l'extension Chrome pour lequel vous effectuez la validation.
- Vous devez être l'éditeur de l'élément du Chrome Web Store. En savoir plus sur la gestion des accès dans le tableau de bord du développeur Chrome Web Store
Dans la section Valider la propriété de l'application du client d'extension Chrome, cliquez sur le bouton Valider la propriété pour terminer la procédure de validation.
Remarque : Attendez quelques minutes avant de terminer la procédure de validation après avoir accordé l'accès à votre compte.
Si la validation réussit, une notification s'affiche pour confirmer la réussite de la procédure. Sinon, un message d'erreur s'affiche.
Pour résoudre un échec de validation, essayez les solutions suivantes :
- Assurez-vous qu'un élément est enregistré dans le tableau de bord du développeur Chrome Web Store avec le même ID d'élément que le client OAuth de l'extension Chrome pour lequel vous effectuez la validation.
- Assurez-vous d'être un éditeur de l'application, c'est-à-dire que vous devez être l'éditeur individuel de l'application ou un membre de l'éditeur de groupe de l'application. En savoir plus sur la gestion des accès dans le tableau de bord du développeur Chrome Web Store.
- Si vous venez de mettre à jour votre liste d'éditeurs de groupe, vérifiez que la liste des membres de l'éditeur de groupe est synchronisée dans le tableau de bord du développeur Chrome Web Store. En savoir plus sur la synchronisation de votre liste de membres d'éditeur
Accès basé sur l'heure
L'accès basé sur la durée permet à un utilisateur d'accorder à votre application l'accès à ses données pendant une durée limitée pour effectuer une action. L'accès limité dans le temps est disponible dans certains produits Google lors du flux de consentement. Il permet aux utilisateurs d'accorder l'accès pour une durée limitée. Par exemple, l' API Data Portability permet de transférer des données une seule fois.
Lorsqu'un utilisateur accorde à votre application un accès limité dans le temps, le jeton d'actualisation expire après la durée spécifiée. Notez que les jetons d'actualisation peuvent être invalidés plus tôt dans certaines circonstances. Pour en savoir plus, consultez ces cas. Le champ refresh_token_expires_in renvoyé dans la réponse de l'échange de code d'autorisation représente le temps restant avant l'expiration du jeton d'actualisation dans de tels cas.
Documentation complémentaire
Le document OAuth 2.0 for Native Apps (OAuth 2.0 pour les applications natives) de l'IETF (Internet Engineering Task Force) établit un grand nombre des bonnes pratiques décrites ici.
Implémenter la protection multicompte
Pour protéger les comptes de vos utilisateurs, vous devez également mettre en œuvre la protection multicompte en utilisant le service de protection multicompte de Google. Ce service vous permet de vous abonner aux notifications d'événements liés à la sécurité qui fournissent à votre application des informations sur les modifications majeures apportées au compte utilisateur. Vous pouvez ensuite utiliser ces informations pour prendre des mesures en fonction de la manière dont vous décidez de répondre aux événements.
Voici quelques exemples de types d'événements envoyés à votre application par le service de protection multicompte de Google :
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Pour en savoir plus sur l'implémentation de la protection multicompte et obtenir la liste complète des événements disponibles, consultez la page Protéger les comptes utilisateur avec la protection multicompte .