OAuth 2.0 pour mobiles et applications de bureau

Ce document explique comment les applications installées sur des appareils tels que des téléphones, des tablettes et des ordinateurs 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 des données spécifiques 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 leurs Google Drive.

Les applications installées sont distribuées sur des appareils individuels, et on suppose qu'elles ne peuvent pas garder de secrets. Ils peuvent accéder aux API Google lorsque l'utilisateur est dans l'application ou lorsque celle-ci 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 installées doivent ouvrir le navigateur du système et fournir un URI de redirection locale pour gérer les réponses du serveur d'autorisation de Google.

Alternatives

Pour les applications mobiles, vous pouvez utiliser Google Sign-In pour Android ou iOS. Les bibliothèques clientes Google Sign-In gèrent l'authentification et l'autorisation des utilisateurs. Elles peuvent être plus simples à mettre en œuvre que le protocole de niveau inférieur décrit ici.

Pour les applications exécutées sur des appareils non compatibles avec un navigateur système ou dont les fonctionnalités d'entrée sont 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 périphériques d'entrée limités.

Bibliothèques et exemples

Nous vous recommandons les bibliothèques et exemples suivants pour vous aider à implémenter le flux OAuth 2.0 décrit dans ce document:

Conditions préalables

Activer les API pour votre projet.

Toute application qui appelle des API Google doit les activer dans API Console.

Pour activer une API pour votre projet:

  1. Open the API Library dans Google API Console.
  2. If prompted, select a project, or create a new one.
  3. La liste API Library 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.
  4. Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

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 identifient l'application sur le 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.

  1. Go to the Credentials page.
  2. Cliquez sur Créer des identifiants > ID client OAuth.
  3. Les sections ci-dessous décrivent les types de clients et les méthodes de redirection compatibles avec le serveur d'autorisation de Google. Choisissez le type de client recommandé pour votre application, attribuez un nom à votre client OAuth et définissez les autres champs du formulaire selon vos besoins.
Android
  1. Sélectionnez le type d'application Android.
  2. Saisissez un nom pour le client OAuth. Ce nom est affiché dans le fichier Credentials page de votre projet pour identifier le client.
  3. Saisissez le nom du package de votre application Android. Cette valeur est définie dans l' attribut package de l'élément <manifest> dans le fichier manifeste de votre application.
  4. Saisissez l'empreinte du certificat de signature SHA-1 de la distribution de l'application.
    • Si votre application utilise la signature d'application Google Play, copiez l'empreinte SHA-1 depuis la page de signature d'application de la Play Console.
    • Si vous gérez votre propre keystore et vos propres clés de signature, utilisez l'utilitaire keytool inclus avec Java pour imprimer les informations de certificat dans un format lisible. Copiez la valeur SHA1 dans la section Certificate fingerprints du résultat de keytool. Pour en savoir plus, consultez la page Authentifier votre client dans la documentation des API Google pour Android.
  5. (Facultatif) Validez la propriété de votre application Android.
  6. Cliquez sur Créer.
iOS
  1. Sélectionnez le type d'application iOS.
  2. Saisissez un nom pour le client OAuth. Ce nom est affiché dans le fichier Credentials page de votre projet pour identifier le client.
  3. Saisissez l'identifiant du bundle pour votre application. L'ID du bundle est la valeur de la clé CFBundleIdentifier dans le fichier de ressources de la liste des propriétés d'information de votre application (info.plist). Cette valeur est le plus souvent affichée dans le volet "Général" ou dans le volet "Signature et fonctionnalités" de l'éditeur de projet Xcode. L'ID du bundle est également affiché dans la section "Informations générales" de la page "Informations sur l'application" sur le site App Store Connect d'Apple.
  4. (Facultatif)

    Si votre application est publiée sur l'App Store d'Apple, saisissez son ID App Store. L'ID sur l'App Store est une chaîne numérique incluse dans chaque URL sur l'App Store d'Apple.

    1. Ouvrez l'application App Store d'Apple sur votre appareil iOS ou iPadOS.
    2. Recherchez votre application.
    3. Sélectionnez le bouton "Partager" (carré et flèche vers le haut).
    4. Sélectionnez Copier le lien.
    5. Collez le lien dans un éditeur de texte. L'ID App Store correspond à la dernière partie de l'URL.

      Exemple : https://apps.apple.com/app/google/id284815942

  5. (Facultatif)

    Saisissez votre ID d'équipe. Pour en savoir plus, consultez la section Localiser votre ID d'équipe dans la documentation du compte de développeur Apple.

  6. Cliquez sur Créer.
Objectif ultra grand angle
  1. Sélectionnez le type d'application Universal Windows Platform.
  2. Saisissez un nom pour le client OAuth. Ce nom est affiché dans le fichier Credentials page de votre projet pour identifier le client.
  3. Saisissez l'ID Microsoft Store à 12 caractères de votre application. Vous trouverez cette valeur dans le Centre des partenaires Microsoft sur la page Identité de l'application de la section "Gestion des applications".
  4. Cliquez sur Créer.

Pour les applications UWP, le schéma d'URI personnalisé ne peut pas comporter plus de 39 caractères.

Schéma d'URI personnalisé (Android, iOS, UWP)

Les schémas d'URI personnalisés sont une forme de liens profonds qui utilisent un schéma défini sur mesure pour ouvrir votre application.

Alternative à l'utilisation de schémas d'URI personnalisés sur Android

Utilisez le SDK Google Sign-In pour Android, qui fournit la réponse OAuth 2.0 directement à votre application, éliminant le besoin d'un URI de redirection.

Migrer vers le SDK Google Sign-In pour Android

Si vous utilisez actuellement un schéma personnalisé pour votre intégration OAuth sur Android, vous devez effectuer les actions ci-dessous pour migrer entièrement vers le SDK Google Sign-In pour Android recommandé:

  1. Mettez à jour votre code pour utiliser le SDK Google Sign-In.
  2. Désactiver la prise en charge des schémas personnalisés dans la console Google APIs.

Suivez les étapes ci-dessous pour migrer vers le SDK Google Sign-In pour Android:

  1. Mettez à jour votre code pour utiliser le SDK Android Google Sign-In :
    1. Examinez votre code pour identifier l'endroit où vous envoyez une requête au serveur OAuth 2.0 de Google. Si vous utilisez un schéma personnalisé, votre requête se présentera comme suit :
        https://accounts.google.com/o/oauth2/v2/auth?
        scope=<SCOPES>&
        response_type=code&
        &state=<STATE>&
        redirect_uri=com.example.app:/oauth2redirect&
        client_id=<CLIENT_ID>
        
      com.example.app:/oauth2redirect est l'URI de redirection du schéma personnalisé de l'exemple ci-dessus. Consultez la définition du paramètre redirect_uri pour en savoir plus sur le format de la valeur du schéma d'URI personnalisé.
    2. Notez les paramètres de requête scope et client_id dont vous aurez besoin pour configurer le SDK Google Sign-In.
    3. Suivez les instructions Commencer à intégrer Google Sign-In à votre application Android pour configurer le SDK. Vous pouvez ignorer l'étape Obtenir l'ID client OAuth 2.0 de votre serveur backend, car vous réutilisez la valeur client_id récupérée à l'étape précédente.
    4. Suivez les instructions pour activer l'accès à l'API côté serveur. Voici les étapes à suivre :
      1. Utilisez la méthode getServerAuthCode afin de récupérer un code d'autorisation pour les champs d'application pour lesquels vous demandez une autorisation.
      2. Envoyez le code d'autorisation au backend de votre application pour l'échanger contre un jeton d'accès et d'actualisation.
      3. Utilisez le jeton d'accès récupéré pour appeler les API Google au nom de l'utilisateur.
  2. Désactivez la prise en charge des schémas personnalisés dans la console Google APIs :
    1. Accédez à la liste des identifiants OAuth 2.0, puis sélectionnez votre client Android.
    2. Accédez à la section Paramètres avancés, décochez la case Activer le schéma d'URI personnalisé, puis cliquez sur Enregistrer pour désactiver la compatibilité avec les schémas d'URI personnalisés.
Activation du schéma d'URI personnalisé...
Si l'alternative recommandée ne fonctionne pas, vous pouvez activer les schémas d'URI personnalisés pour votre client Android en suivant les instructions ci-dessous :
  1. Accédez à la liste des identifiants OAuth 2.0, puis sélectionnez votre client Android.
  2. Accédez à la section Paramètres avancés, cochez la case Activer le schéma d'URI personnalisé, puis cliquez sur Enregistrer pour activer la compatibilité avec les schémas d'URI personnalisés.
Alternative à l'utilisation de schémas d'URI personnalisés dans les applications Chrome

Utilisez l'API Chrome Identity, qui fournit la réponse OAuth 2.0 directement à votre application, éliminant le besoin d'un URI de redirection.

Valider la propriété de l'application (Android, Chrome)

Vous pouvez valider la propriété de votre application afin de réduire le risque d'usurpation d'identité.

Android

Pour terminer la procédure de validation, vous pouvez utiliser votre compte de développeur Google Play si vous en avez un et si votre application est enregistrée dans la Google Play Console. Pour que la validation aboutisse, les conditions suivantes doivent être remplies:

  • Vous devez disposer d'une application enregistrée dans la Google Play Console avec le même nom de package et la même empreinte de certificat de signature SHA-1 que le client OAuth Android pour lequel vous effectuez la validation.
  • Vous devez disposer des droits d'administrateur pour l'application dans la Google Play Console. En savoir plus sur la gestion des accès dans la Google Play Console

Dans la section Verify App Ownership (Valider la propriété de l'application) du client Android, cliquez sur le bouton Verify Ownership (Valider la propriété) pour terminer le processus de validation.

Si la validation réussit, une notification s'affiche pour confirmer que la procédure de validation a réussi. Sinon, une invite d'erreur s'affiche.

Pour résoudre un problème de validation ayant échoué, procédez comme suit:

  • Assurez-vous que l'application que vous validez est enregistrée dans la Google Play Console.
  • Assurez-vous de disposer des droits d'administration pour l'application dans la Google Play Console.
Chrome

Pour effectuer la procédure de validation, vous devez utiliser votre compte de développeur Chrome Web Store. Les conditions suivantes doivent être remplies pour que la validation soit réussie:

  • L'élément enregistré dans le tableau de bord du développeur du Chrome Web Store doit être associé au même ID d'élément que le client OAuth de l'extension Chrome pour lequel vous effectuez la validation.
  • Vous devez être éditeur de l'article 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 Verify App Ownership (Valider la propriété de l'application) du client d'extension Chrome, cliquez sur le bouton Verify Ownership (Valider la propriété) pour terminer la procédure de validation.

Remarque:Après avoir accordé l'accès à votre compte, veuillez patienter quelques minutes avant de terminer la procédure de validation.

Si la validation réussit, une notification s'affiche pour confirmer que la procédure de validation a réussi. Sinon, une invite d'erreur s'affiche.

Pour résoudre un problème de validation ayant échoué, procédez comme suit:

  • Assurez-vous qu'il existe un élément enregistré dans le tableau de bord du développeur du 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 que vous êtes un éditeur de l'application, c'est-à-dire que vous devez être l'éditeur individuel 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 qu'elle est synchronisée dans le tableau de bord du développeur du Chrome Web Store. En savoir plus sur la synchronisation de votre liste de membres d'éditeur

Adresse IP de rebouclage (macOS, Linux, ordinateur Windows)

Pour recevoir le code d'autorisation à l'aide de cette URL, votre application doit écouter le serveur Web local. Cela 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, elle doit afficher une page HTML pour demander à l'utilisateur de fermer le navigateur et de revenir à votre application pour plus de facilité d'utilisation.

Utilisation recommandée Applications de bureau macOS, Linux et Windows (mais pas la plate-forme Windows universelle)
Valeurs des formulaires Définissez le type d'application sur Application de bureau.

Copier-coller manuel

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. Ainsi, il peut 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 aura besoin d'une autorisation d'accès.

Le document Champs d'application des 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 afin d'obtenir le consentement d'un utilisateur pour effectuer une requête API en son nom. Votre application doit obtenir cette autorisation pour pouvoir exécuter une requête API Google nécessitant l'autorisation de l'utilisateur.

Étape 1: Générez un vérificateur de code et un défi

Google accepte le protocole PKCE (clé de vérification pour l'échange de code) afin de renforcer la sécurité du flux de l'application installée. Un vérificateur de code unique est créé pour chaque requête 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 l'outil de vérification du 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.

L'outil de vérification du code doit avoir suffisamment d'entropie pour qu'il soit difficile de deviner la valeur.

Créer le défi de code

Deux méthodes de création de défi de code sont acceptées.

Méthodes de génération des défis de code
S256 (recommandé) Le défi de code est le hachage SHA256 de l'outil de vérification du code, encodé en Base64URL (sans marge intérieure).
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
standard Le défi de code a la même valeur que l'outil de vérification de code généré ci-dessus.
code_challenge = code_verifier

É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. Cette valeur se trouve dans API Console Credentials page.

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 fonction 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é dans le Credentials page API Consolede votre client. Si cette valeur ne correspond à aucun URI autorisé, une erreur redirect_uri_mismatch est générée.

Le tableau ci-dessous indique la valeur de paramètre redirect_uri appropriée pour chaque méthode:

redirect_uri valeurs
Schéma d'URI personnalisé com.example.app:redirect_uri_path

ou

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app est la notation DNS inverse d'un domaine que vous contrôlez. Le schéma personnalisé doit contenir un point pour être valide.
  • com.googleusercontent.apps.123 est la notation DNS inversée de l'ID client.
  • redirect_uri_path est un composant de chemin facultatif, tel que /oauth2redirect. Notez que le chemin d'accès doit commencer par une seule barre oblique, ce qui diffère des URL HTTP standards.
Adresse IP de rebouclage http://127.0.0.1:port ou http://[::1]:port

Interrogez votre plate-forme pour obtenir l'adresse IP de bouclage appropriée et démarrez un écouteur HTTP sur un port disponible aléatoire. Remplacez port par le numéro de port réel que votre application écoute.

Notez que la compatibilité avec l'option de redirection de l'adresse IP de rebouclage sur les applications mobiles est OBSOLÈTE.

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 code pour les applications installées.

scope Obligatoire

Liste de champs d'application séparés par des espaces qui identifient les ressources auxquelles votre application peut accéder pour le compte de l'utilisateur. Ces valeurs déterminent l'écran de consentement que Google présente à 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. Ainsi, il existe une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur.

code_challenge Recommandé

Spécifie une valeur code_verifier encodée qui sera utilisée comme question d'authentification côté serveur lors de l'échange du code d'autorisation. Pour en savoir plus, consultez la section Créer un défi de code ci-dessus.

code_challenge_method Recommandé

Spécifie la méthode utilisée pour encoder un élément code_verifier qui sera utilisé lors de l'échange du code d'autorisation. Ce paramètre doit être utilisé avec le paramètre code_challenge décrit ci-dessus. La valeur par défaut de code_challenge_method est plain si elle n'est pas présente dans la requête incluant un code_challenge. Les seules valeurs acceptées pour ce paramètre sont S256 ou plain.

state Recommandé

Spécifie toute valeur de chaîne utilisée par votre application pour maintenir l'état entre votre requête d'autorisation et la réponse du serveur d'autorisation. Une fois que l'utilisateur a accepté ou refusé la demande d'accès de votre application, le serveur renvoie la valeur exacte que vous envoyez en tant que paire name=value dans l'identifiant de fragment d'URL (#) de redirect_uri.

Vous pouvez utiliser ce paramètre à différentes fins, par exemple pour rediriger l'utilisateur vers la bonne ressource dans votre application, envoyer des nonces et limiter la falsification de requête intersite. Étant donné que votre redirect_uri peut être devinée, l'utilisation d'une valeur state peut vous permettre de vous assurer qu'une connexion entrante est le résultat d'une requête d'authentification. Si vous générez une chaîne aléatoire ou encodez le hachage d'un cookie ou d'une autre valeur qui capture l'état du client, vous pouvez valider la réponse pour vous assurer que la requête et la réponse proviennent du même navigateur, ce qui vous protège contre les attaques telles que la falsification de requêtes intersites. Consultez la documentation d'OpenID Connect pour obtenir un exemple de création et de confirmation d'un jeton state.

login_hint Optional

Si votre application sait quel utilisateur tente de s'authentifier, elle peut utiliser ce paramètre pour fournir une indication au serveur d'authentification Google. Le serveur utilise cet indice pour simplifier le flux de connexion en préremplissant le champ d'adresse e-mail dans le formulaire de connexion ou en sélectionnant la session de connexion multicompte appropriée.

Définissez la valeur du paramètre sur une adresse e-mail ou un identifiant sub, qui équivaut à l'ID Google de l'utilisateur.

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 faciliter la lecture.

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 rebouclage

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 invite l'utilisateur à donner son consentement

Au cours de 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 des services d'API Google auxquels elle demande l'autorisation d'accéder, à l'aide des identifiants d'autorisation de l'utilisateur, ainsi qu'un résumé des champs d'application d'accès à accorder. Celui-ci peut alors accepter d'accorder l'accès à un ou plusieurs champs d'application demandés par votre application ou refuser la requête.

Votre application n'a rien à faire à ce stade, car elle attend la réponse du serveur OAuth 2.0 de Google indiquant si un accès a été accordé. Cette réponse est expliquée à l'étape suivante.

Erreurs

Les requêtes adressées au point de terminaison d'autorisation OAuth 2.0 de Google peuvent afficher des messages d'erreur destinés aux utilisateurs au lieu des flux d'authentification et d'autorisation attendus. Vous trouverez ci-dessous la liste des codes d'erreur courants et des solutions suggérées.

admin_policy_enforced

Le compte Google ne peut pas autoriser un ou plusieurs des champs d'application demandés en raison des règles de son administrateur Google Workspace. Consultez l'article d'aide pour les administrateurs Google Workspace Contrôler quelles applications tierces et internes ont accès aux données Google Workspace pour savoir comment un administrateur peut restreindre l'accès à tous les champs d'application ou à des champs d'application sensibles et restreints tant que l'accès n'a pas été explicitement accordé à votre ID client OAuth.

disallowed_useragent

Le point de terminaison de l'autorisation est affiché dans un user-agent intégré non autorisé par les règles OAuth 2.0 de Google.

Android

Les développeurs Android peuvent rencontrer ce message d'erreur lorsqu'ils ouvrent des requêtes d'autorisation dans android.webkit.WebView. Nous recommandons aux développeurs d'utiliser plutôt des bibliothèques Android telles que Google Sign-In pour Android ou AppAuth pour Android d'OpenID Foundation.

Les développeurs Web peuvent rencontrer cette erreur lorsqu'une application Android 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 les liens généraux à s'ouvrir dans le gestionnaire de liens par défaut du système d'exploitation, qui inclut à la fois les gestionnaires Android App Links ou l'application de navigateur par défaut. La bibliothèque d'onglets personnalisés Android est également une option compatible.

iOS

Les développeurs iOS et macOS peuvent rencontrer cette erreur lorsqu'ils ouvrent des requêtes d'autorisation dans WKWebView. Nous recommandons aux développeurs d'utiliser plutôt 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 les liens généraux à s'ouvrir dans le gestionnaire de liens par défaut du système d'exploitation, qui inclut à la fois les gestionnaires de liens universels ou 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".

invalid_grant

Si vous utilisez un vérificateur de code et un défi, le paramètre code_callenge n'est pas valide ou est manquant. Assurez-vous que le paramètre code_challenge est correctement défini.

Lors de l'actualisation d'un jeton d'accès, celui-ci peut avoir expiré ou avoir été invalidé. Authentifiez à nouveau l'utilisateur et demandez-lui 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 les paramètres appropriés dans votre requête. Sinon, le compte utilisateur a peut-être été supprimé ou désactivé.

redirect_uri_mismatch

Le redirect_uri transmis dans la requête d'autorisation ne correspond à aucun URI de redirection autorisé pour l'ID client OAuth. Examinez les URI de redirection autorisés dans le Google API Console Credentials page.

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 accepté. Consultez le guide de migration pour mettre à jour votre intégration.

invalid_request

Un problème est survenu avec votre demande. Plusieurs raisons peuvent expliquer ce problème:

  • Le format de la requête n'a pas été correct.
  • Il manque des paramètres obligatoires dans la requête
  • 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é est utilisé pour l'URI de redirection. Si le message d'erreur Le schéma d'URI personnalisé n'est pas compatible avec les applications Chrome ou Le schéma d'URI personnalisé n'est pas activé pour votre client Android s'affiche, cela signifie que vous utilisez un schéma d'URI personnalisé qui n'est pas compatible avec les applications Chrome et qui est désactivé par défaut sur Android. En savoir plus sur les alternatives avec les schémas d'URI personnalisés

É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 requête.

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 API Console Credentials page.
client_secret Code secret du client obtenu à partir de API Console Credentials page.
code Code d'autorisation renvoyé par la requête initiale.
code_verifier L'outil de vérification du 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 L'un des URI de redirection répertoriés pour votre projet dans le fichier API Console Credentials page pour le client_id donné.

L'extrait de code suivant présente un exemple de requête:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

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 envoyé par votre application pour autoriser une requête 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. Cette valeur est un jeton Web JSON (JWT, JSON Web Token) contenant 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. Notez que les jetons d'actualisation sont toujours renvoyés pour les applications installées.
scope Champs d'application accordés par access_token, exprimés sous la forme d'une liste de chaînes sensibles à la casse et séparées par des espaces.
token_type Type de jeton affiché. Pour le moment, la valeur de ce champ est toujours définie sur Bearer.

L'extrait de code suivant montre un exemple de réponse:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Appeler les 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é, à condition que le ou les champs d'application requis par l'API aient é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 Bearer de l'en-tête HTTP Authorization. Dans la mesure du possible, il est préférable d'utiliser l'en-tête HTTP, car les chaînes de requête ont tendance à être visibles dans les journaux du 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 essayer toutes les API Google et consulter leur champ d'application sur OAuth 2.0 Playground.

Exemples 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 vers 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

Exemples curl

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 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 en son absence) 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:

Champs
client_id ID client obtenu à partir de API Console.
client_secret Code secret du client obtenu à partir de API Console. (Le client_secret ne s'applique pas aux requêtes de clients enregistrés en tant qu'applications Android, iOS ou Chrome.)
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.

L'extrait de code suivant présente un exemple de requête:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Tant que l'utilisateur n'a pas révoqué l'accès accordé à l'application, le serveur de jetons renvoie un objet JSON contenant un nouveau jeton d'accès. L'extrait de code suivant montre un exemple de réponse:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Notez que le nombre de jetons d'actualisation qui seront é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 jetons d'actualisation plus anciens cesseront de fonctionner.

Révoquer un jeton

Dans certains cas, un utilisateur peut souhaiter révoquer l'accès accordé à une application. L'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 à un site ou une application de la page "Applications et sites tiers ayant accès à votre compte" pour en savoir plus.

Une application peut également révoquer l'accès qui lui est accordé par programmation. La révocation programmatique est importante lorsqu'un utilisateur se désabonne ou supprime une application, ou lorsqu'elle a modifié les ressources d'API requises par une application. En d'autres termes, une partie du processus de suppression peut inclure une requête API pour garantir la suppression des autorisations précédemment accordées à l'application.

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 est associé à un jeton d'actualisation, le jeton d'actualisation est é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é avec un code d'erreur.

Documentation complémentaire

La pratique actuelle de l'IETF (OAuth 2.0 pour les applications natives) établit un grand nombre des bonnes pratiques décrites ici.