OAuth 2.0 pour les applications mobiles et de bureau

2

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 à l'API YouTube Data.

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 de récupérer les données YouTube d'une chaîne.

Les applications installées sont distribuées sur des appareils individuels et on part du principe qu'elles ne peuvent pas conserver 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 système et fournir un URI de redirection locale pour gérer les réponses du serveur d'autorisation de Google.

Autres solutions

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 les autorisations 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 capacités d'entrée sont limitées, tels que 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 à entrée limitée.

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:

Prérequis

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, procédez comme suit:

  1. Open the API Library dans Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Accédez à la page "Bibliothèque" pour trouver et activer l'API YouTube Data. Recherchez toutes les autres API que votre application utilisera et activez-les également.

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 ces 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, nommez 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 de package de votre application Android. Cette valeur est définie dans l' attribut package de l'élément <manifest> du 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 de 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 fourni 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 section 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 correspond à la valeur de la clé CFBundleIdentifier dans le fichier de ressources de la liste de propriétés d'informations de votre application (info.plist). Cette valeur s'affiche le plus souvent 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" de l'application sur le site App Store Connect d'Apple.
  4. (Facultatif)

    Si votre application est publiée dans l'App Store d'Apple, saisissez son ID dans l'App Store. L'ID sur l'App Store d'Apple est une chaîne numérique incluse dans chaque URL de 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" (symbole 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 est 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 Localiser votre ID d'équipe dans la documentation du compte de développeur Apple.

  6. Cliquez sur Créer.
UWP
  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 lien profond qui utilise un schéma défini par vos soins 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, sans avoir à utiliser 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 afin de migrer entièrement vers le SDK Google Sign-In recommandé pour Android:

  1. Mettez à jour votre code pour utiliser le SDK Google Sign-In.
  2. Désactivez la prise en charge du schéma personnalisé 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 afin d'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é dans 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 du serveur backend puisque vous réutilisez le code client_id récupéré à l'étape précédente.
    4. Suivez les instructions pour activer l'accès aux API côté serveur. Cela inclut les étapes suivantes :
      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 du schéma personnalisé dans la console Google APIs :
    1. Accédez à la liste Identifiants OAuth 2.0 et 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 prise en charge des schémas d'URI personnalisés.
Activation du schéma d'URI personnalisé...
Si la solution 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 Identifiants OAuth 2.0 et 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, sans avoir à utiliser un URI de redirection.

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

Vous pouvez valider la propriété de votre application pour 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 que votre application est enregistrée dans la Google Play Console. Pour que la validation réussisse, 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 de l'autorisation 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 qu'elle a abouti. Sinon, un message d'erreur s'affiche.

Pour résoudre un problème d'échec de la validation, procédez comme suit:

  • Assurez-vous que l'application à valider est enregistrée dans la Google Play Console.
  • Assurez-vous de disposer de l'autorisation Administrateur pour l'application dans la Google Play Console.
Chrome

Pour effectuer la procédure de validation, utilisez votre compte de développeur Chrome Web Store. Pour que la validation réussisse, les conditions suivantes doivent être remplies:

  • Dans le Tableau de bord du développeur Chrome Web Store, vous devez disposer d'un article enregistré avec le même ID d'article que le client OAuth de l'extension Chrome pour lequel vous effectuez la validation.
  • Vous devez être éditeur de l'article 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 de l'extension Chrome, cliquez sur le bouton Verify Ownership (Valider la propriété) pour terminer le processus de validation.

Remarque:Veuillez attendre quelques minutes avant de terminer le processus de validation après avoir accordé l'accès à votre compte.

Si la validation réussit, une notification s'affiche pour confirmer qu'elle a abouti. Sinon, un message d'erreur s'affiche.

Pour résoudre un problème d'échec de la validation, procédez comme suit:

  • Assurez-vous qu'il y a bien un article 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 l'éditeur de l'application. Autrement dit, 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 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 sur 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 demandant à 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 du formulaire Définissez le type d'application sur Application de bureau.

Copier-coller manuel

Identifier les niveaux d'accès

Les niveaux d'accès 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 habilitations auxquelles votre application devra être autorisée à accéder.

L'API YouTube Data v3 utilise les champs d'application suivants:

Niveaux d'accès
https://www.googleapis.com/auth/youtubeGérez votre compte YouTube.
https://www.googleapis.com/auth/youtube.channel-memberships.creatorConsulter la liste des membres actuellement actifs de votre chaîne, leur niveau actuel et leur date de souscription
https://www.googleapis.com/auth/youtube.force-sslAfficher, modifier et supprimer définitivement vos vidéos, notes, commentaires et sous-titres YouTube
https://www.googleapis.com/auth/youtube.readonlyConsultez votre compte YouTube.
https://www.googleapis.com/auth/youtube.uploadGérez vos vidéos YouTube.
https://www.googleapis.com/auth/youtubepartnerAffichez et gérez vos éléments et le contenu associé sur YouTube.
https://www.googleapis.com/auth/youtubepartner-channel-auditAffichez les informations privées sur votre chaîne YouTube pertinentes pendant le processus d'audit avec un partenaire YouTube.

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 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 possibles.

Méthodes de génération des défis de code
S256 (recommandé) Le défi de code consiste en un hachage SHA256 encodé en Base64URL (sans remplissage) de l'outil de vérification du code.
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 du 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. Vous trouverez cette valeur 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 aurez configuré 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é dans le fichier API Console Credentials pagede votre client. Si cette valeur ne correspond à aucun URI autorisé, une erreur redirect_uri_mismatch est renvoyé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 inversée d'un domaine que vous gérez. Le schéma personnalisé doit contenir un point pour être valide.
  • com.googleusercontent.apps.123 est la notation DNS inverse 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 est différent 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 de votre application.

Notez que la compatibilité de l'option de redirection des adresses IP de rebouclage dans 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 délimités par un espace 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 niveaux d'accès 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.

L'API YouTube Data v3 utilise les champs d'application suivants:

Niveaux d'accès
https://www.googleapis.com/auth/youtubeGérez votre compte YouTube.
https://www.googleapis.com/auth/youtube.channel-memberships.creatorConsulter la liste des membres actuellement actifs de votre chaîne, leur niveau actuel et leur date de souscription
https://www.googleapis.com/auth/youtube.force-sslAfficher, modifier et supprimer définitivement vos vidéos, notes, commentaires et sous-titres YouTube
https://www.googleapis.com/auth/youtube.readonlyConsultez votre compte YouTube.
https://www.googleapis.com/auth/youtube.uploadGérez vos vidéos YouTube.
https://www.googleapis.com/auth/youtubepartnerAffichez et gérez vos éléments et le contenu associé sur YouTube.
https://www.googleapis.com/auth/youtubepartner-channel-auditAffichez les informations privées sur votre chaîne YouTube pertinentes pendant le processus d'audit avec un partenaire YouTube.

Le document Champs d'application de l'API OAuth 2.0 fournit une liste complète des champs d'application que vous pouvez utiliser pour accéder aux API Google.

code_challenge Recommandé

Spécifie un code_verifier encodé qui sera utilisé 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 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 de code_challenge_method est définie par défaut sur 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. 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 une fois que l'utilisateur a accepté ou refusé la demande d'accès de votre application.

Vous pouvez utiliser ce paramètre à plusieurs fins, par exemple pour rediriger l'utilisateur vers la ressource appropriée de votre application, pour envoyer des nonces et pour atténuer la falsification de requête intersite. Étant donné que la valeur 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 OpenID Connect pour découvrir comment créer et confirmer un jeton state.

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 de 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.

Chaque URL demande l'accès à un champ d'application qui permet de récupérer les données YouTube de l'utilisateur.

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 state facultatif. 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 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

À 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 qui affiche le nom de votre application et des services d'API Google auxquels l'utilisateur demande l'autorisation d'accéder, à l'aide des identifiants d'autorisation de l'utilisateur, ainsi qu'un résumé des niveaux d'accès à accorder. L'utilisateur peut alors autoriser 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 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. 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 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 niveaux d'accès sensibles et restreints jusqu'à ce que l'accès soit explicitement accordé à votre ID client OAuth.

disallowed_useragent

Le point de terminaison d'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 lors de l'ouverture 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 la plate-forme 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 l'ouverture des liens généraux dans le gestionnaire de liens par défaut du système d'exploitation, ce 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 demandes 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 l'ouverture des liens généraux dans le gestionnaire de liens par défaut du système d'exploitation, ce 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, vérifiez que votre application a été correctement configurée, et que vous utilisez les jetons et paramètres corrects 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 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

Il y a eu un problème avec votre demande. Plusieurs raisons peuvent expliquer ce problème:

  • Le format de la requête n'a pas été correct.
  • Il manquait 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 vous voyez 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, 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 aux schémas d'URI personnalisés

Étape 4: Gérez 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 autorise 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 de code que vous avez créé à l'étape 1.
grant_type Comme indiqué 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 champ 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. La valeur est un jeton Web JSON (JWT, JSON Web Token) qui contient des informations d'identité signées numériquement sur l'utilisateur.
refresh_token Un 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 Niveaux d'accès 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 renvoyé. 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/youtube.force-ssl",
  "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 champs d'application 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 Bearer d'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 YouTube Live Streaming).

Notez que l'API YouTube Live Streaming n'est pas compatible avec le flux du compte de service. Étant donné qu'il n'existe aucun moyen d'associer un compte de service à un compte YouTube, les tentatives d'autorisation des requêtes avec ce flux génèrent une erreur NoLinkedYouTubeAccount.

Vous pouvez tester toutes les API Google et consulter leurs champs d'application sur OAuth 2.0 Playground.

Exemples de requêtes HTTP GET

Un appel au point de terminaison liveBroadcasts.list (l'API YouTube Live Streaming) à 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 /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true 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/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Exemples curl

Vous pouvez tester ces commandes avec l'application de ligne de commande curl. Voici un exemple utilisant l'option d'en-tête HTTP (recommandée):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Vous pouvez également utiliser l'option du paramètre de chaîne de requête:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

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 d'autorisation à 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:

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 provenant 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 du 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 é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 vouloir 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 à un site ou une application de la page "Sites et applications 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 automatisée est importante lorsqu'un utilisateur se désabonne ou supprime une application, ou lorsque les ressources d'API requises par une application ont changé de manière significative. 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 automatisée, 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}

Le jeton peut être un jeton d'accès ou 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. Pour les conditions d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

Documentation complémentaire

Les bonnes pratiques actuelles de l'IETF (OAuth 2.0 pour les applications natives) établissent bon nombre des bonnes pratiques présentées ici.