OAuth 2.0 pour les applications mobiles et 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 leur Google Drive.

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

Alternatives

Pour les applications mobiles, vous pouvez préférer utiliser la fonctionnalité de connexion Google 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 à implémenter que le protocole de niveau inférieur décrit ici.

Pour les applications exécutées sur des appareils qui ne prennent pas en charge de navigateur système ou qui disposent de fonctionnalités d'entrée limitées, comme les téléviseurs, les consoles de jeux, 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 d'utiliser 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:

  1. Open the API Library dans le Google API Console.
  2. If prompted, select a project, or create a new one.
  3. 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 fonctionnalité de 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 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.

  1. Go to the Credentials page.
  2. Cliquez sur Créer des identifiants > ID client OAuth.
  3. Les sections suivantes décrivent les types de clients 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 les besoins.
Android
  1. Sélectionnez le type d'application Android.
  2. Saisissez un nom pour le client OAuth. Ce nom s'affiche dans la 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 sur 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 du certificat dans un format lisible par l'homme. Copiez la valeur SHA1 dans la section Certificate fingerprints de la sortie 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 s'affiche dans la Credentials page de votre projet pour identifier le client.
  3. Saisissez l'identifiant de bundle de votre application. L'ID de bundle correspond à la valeur de la clé CFBundleIdentifier dans le fichier de ressources de la liste de propriétés d'informations (info.plist) de votre application. La valeur s'affiche généralement dans le volet "General" (Général) ou "Signing & Capabilities" (Signature et fonctionnalités) de l'éditeur de projet Xcode. L'ID de lot s'affiche également dans la section "Informations générales" de la page "Informations sur l'application" de l'application sur le site Web d'Apple App Store Connect.

    Vérifiez que vous utilisez le bon ID de bundle pour votre application, car vous ne pourrez pas le modifier si vous utilisez la fonctionnalité App Check.

  4. (Facultatif)

    Saisissez l'ID App Store de votre application si celle-ci est publiée sur l'App Store d'Apple. L'ID sur l'App Store 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 en forme de carré et de flèche vers le haut).
    4. Sélectionnez Copier le lien.
    5. Collez le lien dans un éditeur de texte. L'ID de l'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 Trouver votre ID d'équipe dans la documentation du compte de développeur Apple.

    Remarque:Le champ "ID de l'équipe" est obligatoire si vous activez App Check pour votre client.
  6. (Facultatif)

    Activez App Check pour votre application iOS. Lorsque vous activez App Check, le service App Attest d'Apple est utilisé pour vérifier que les requêtes OAuth 2.0 provenant de votre client OAuth sont authentiques et proviennent de votre application. Cela permet de réduire le risque d'usurpation d'identité d'application. En savoir plus sur l'activation d'App Check pour votre application iOS

  7. 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 s'affiche dans la 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 Microsoft Partner Center, sur la page Identité de l'application, dans la section "Gestion des applications".
  4. Cliquez sur Créer.

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

Identifier les niveaux d'accès

Les champs d'application permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le nombre d'accès qu'ils accordent à votre application. Par conséquent, il peut exister 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 pour lesquels 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 pour obtenir le consentement d'un utilisateur afin d'effectuer une requête API en son nom. Votre application doit disposer de 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 code de validation et un défi

Google est compatible avec le protocole Proof Key for Code Exchange (PKCE) pour renforcer la sécurité du flux d'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 le vérificateur de code

Un code_verifier est une chaîne aléatoire cryptographique à haute entropie qui utilise les caractères non réservés [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", avec une longueur minimale de 43 caractères et une longueur maximale de 128 caractères.

Le vérificateur de code doit avoir un degré d'entropie suffisant pour rendre la valeur impossible à deviner.

Créer le défi de programmation

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

Méthodes de génération de code challenge
S256 (recommandé) Le défi de code correspond au hachage SHA256 encodé en Base64URL (sans remplissage) du vérificateur de code.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain Le défi de code est identique à la valeur générée par le vérificateur de code 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 pouvez trouver cette valeur dans le 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 devrez 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é dans le API Console Credentials pagede votre client. Si cette valeur ne correspond pas à un URI autorisé, une erreur redirect_uri_mismatch s'affiche.

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 sous votre contrôle. Pour être valide, le schéma personnalisé doit contenir une période.
  • com.googleusercontent.apps.123 est la notation DNS inversée de l'ID client.
  • redirect_uri_path est un composant de chemin d'accès 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 sur lequel votre application écoute.

Notez que la prise en charge de l'option de redirection d'adresse IP de bouclage dans les applications mobiles est ABANDONNÉE.
response_type Obligatoire

Détermine si le point de terminaison OAuth 2.0 de Google renvoie un code d'autorisation.

Définissez la valeur du paramètre sur code pour les applications installées.
scope Obligatoire

Liste des 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 renseignent l'écran de consentement que Google affiche à l'utilisateur.

Les champs d'application permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le nombre d'accès qu'ils accordent à votre application. Par conséquent, 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 un code_verifier encodé qui sera utilisé comme défi côté serveur lors de l'échange du code d'autorisation. Pour en savoir plus, consultez la section Créer un défi de codage 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 de 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 par défaut plain si elle n'est pas présente dans la requête qui inclut 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 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 en tant que paire name=value dans l'identifiant de fragment d'URL (#) de l'redirect_uri une fois que l'utilisateur a accepté ou refusé la requête 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 dans votre application, envoyer des nonces et atténuer la falsification de requêtes intersites. Étant donné que votre redirect_uri peut être deviné, l'utilisation d'une valeur state peut 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 en outre 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 savoir 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 Google. Le serveur utilise l'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 multiconnexion appropriée.

Définissez la valeur du paramètre sur une adresse e-mail ou un identifiant sub, qui est équivalent à 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 response_type et client_id obligatoires, ainsi que le paramètre state facultatif. Chaque URL contient des sauts de ligne et des espaces pour une meilleure 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 loopback

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 à l'utilisateur 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 indiquant le nom de votre application et les services de l'API Google auxquels il demande l'autorisation d'accéder à l'aide des identifiants 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 requête.

À ce stade, votre application n'a rien à faire, 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 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 à des champs d'application sensibles et limités jusqu'à ce que l'accès soit explicitement accordé à votre ID client OAuth, consultez l'article d'aide pour les administrateurs Google Workspace Contrôler l'accès des applications tierces et internes 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.

Android

Les développeurs Android peuvent rencontrer ce message d'erreur lorsqu'ils ouvrent des requêtes d'autorisation dans android.webkit.WebView. Les développeurs doivent plutôt utiliser des bibliothèques Android telles que Google Sign-In pour Android ou AppAuth pour Android de l'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 de Android App Links et l'application de navigateur par défaut. La bibliothèque Android Custom Tabs 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. Les développeurs doivent plutôt utiliser des bibliothèques iOS telles que Google Sign-In pour iOS ou AppAuth pour iOS de l'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 Universal Links 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 dans une organisation Google Cloud spécifique. Pour en savoir plus sur cette option de configuration, consultez la section Type d'utilisateur dans l'article d'aide "Configurer votre écran de consentement OAuth".

invalid_grant

Si vous utilisez un outil de validation et de défi du code, le paramètre code_callenge est incorrect ou manquant. Assurez-vous que le paramètre code_challenge est correctement défini.

Lorsque vous actualisez un jeton d'accès, il est possible qu'il ait expiré ou qu'il ait été invalidé. Réauthentifiez l'utilisateur et demandez-lui son consentement pour obtenir de nouveaux jetons. Si cette 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

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

L'redirect_uri transmise peut être non valide pour le type de client.

Le paramètre redirect_uri peut faire référence au flux OAuth hors bande (OOB) qui a été abandonné et n'est plus pris en charge. Consultez le guide de migration pour mettre à jour votre intégration.

invalid_request

Votre demande ne correspond pas aux critères requis. Plusieurs raisons peuvent expliquer ce problème:

  • La requête n'était pas correctement formatée
  • Des paramètres obligatoires manquaient dans la requête.
  • La requête utilise une méthode d'autorisation non acceptée par 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 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 contient 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 auprès de la 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 Le vérificateur 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 listés pour votre projet dans la table 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 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. Notez que les jetons d'actualisation sont toujours renvoyés pour les applications installées.
scope Champs d'application d'accès accordés par access_token, exprimés sous la forme d'une liste de chaînes sensibles à la casse séparées par des espaces.
token_type Type de jeton renvoyé. À ce stade, 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 https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Étape 6: Vérifiez les autorisations accordées par les utilisateurs

Lorsque vous demandez plusieurs niveaux d'accès à la fois, les utilisateurs peuvent ne pas accorder tous les niveaux d'accès demandés par votre application. Votre application doit toujours vérifier les autorisations accordées par l'utilisateur et gérer tout refus d'autorisation en désactivant les fonctionnalités concernées. 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 d'accès accordés par le jeton d'accès, exprimés sous la forme d'une liste de chaînes sensibles à la casse, délimitées par des espaces.

Par exemple, l'exemple de réponse du 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 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 effectuer des appels à une API Google au nom d'un compte utilisateur donné si le ou les champs d'application de l'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête envoyée à l'API en incluant un paramètre de requête access_token ou une valeur Bearer d'en-tête HTTP Authorization. Lorsque c'est possible, l'en-tête HTTP est préférable, 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 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 drive.files (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 à 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 POST HTTPS au serveur d'autorisation (https://oauth2.googleapis.com/token) de Google, qui inclut les paramètres suivants:

Champs
client_id ID client obtenu auprès de API Console.
client_secret Code secret du client obtenu auprès de API Console. (client_secret ne s'applique pas aux requêtes des 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é à la suite de 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 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 rencontrer 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. 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'une application ou d'un site du document d'aide "Applications et sites tiers ayant accès à votre compte".

Une application peut également révoquer de manière programmatique l'accès qui lui a été accordé. La révocation programmatique est importante dans les cas où un utilisateur se désinscrit, supprime une application ou que 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 d'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 dispose d'un jeton d'actualisation correspondant, le jeton d'actualisation est également révoqué.

Si la révocation est traitée avec succès, 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.

Méthodes de redirection d'application

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 l'utilisateur 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 envoie la réponse OAuth 2.0 directement à votre application, ce qui élimine la nécessité d'un URI de redirection.

Migrer vers le SDK Google Sign-In pour Android

Si vous utilisez un schéma personnalisé pour votre intégration OAuth sur Android, vous devez effectuer les actions suivantes pour migrer complètement vers le SDK Google Sign-In pour Android recommandé:

  1. Mettez à jour votre code pour utiliser le SDK Google Sign-In.
  2. Désactivation de la prise en charge du schéma personnalisé dans la console Google APIs.

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

  1. Mettez à jour votre code pour utiliser le SDK Android de 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ésente 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. Pour en savoir plus sur le format de la valeur du schéma d'URI personnalisé, consultez la définition du paramètre redirect_uri.
    2. Notez les paramètres de requête scope et client_id dont vous avez besoin pour configurer le SDK Google Sign-In.
    3. Suivez les instructions de la section 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 allez réutiliser le client_id que vous avez récupéré à l'étape précédente.
    4. Suivez les instructions de la section Activer l'accès côté serveur aux API. Cela comprend les étapes suivantes :
      1. Utilisez la méthode getServerAuthCode pour récupérer un code d'autorisation pour les champs d'application pour lesquels vous demandez l'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 API :
    1. Accédez à la liste de vos 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 du schéma d'URI personnalisé.

Activer le schéma d'URI personnalisé

Si la solution recommandée ne fonctionne pas pour vous, 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 de vos 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 prise en charge du schéma d'URI personnalisé.

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 bouclage (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, pour une meilleure usabilité, elle doit répondre en affichant une page HTML qui demande à l'utilisateur de fermer le navigateur et de revenir à votre application.

Utilisation recommandée Applications de bureau macOS, Linux et Windows (mais pas de plate-forme Windows universelle)
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 (Android, Chrome)

Vous pouvez vérifier la propriété de votre application pour réduire le risque d'usurpation d'identité.

Android

Pour effectuer 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, vous devez respecter les conditions suivantes:

  • 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 Valider la propriété de l'application du client Android, cliquez sur le bouton Valider la propriété pour terminer le processus de validation.

Si la validation réussit, une notification s'affiche pour confirmer la réussite du processus de validation. Sinon, une invite d'erreur s'affiche.

Pour résoudre un problème de validation, essayez les solutions suivantes:

  • Assurez-vous que l'application que vous vérifiez est enregistrée dans la Google Play Console.
  • Assurez-vous de disposer des droits administrateur 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. Pour que la validation soit acceptée, vous devez respecter les conditions suivantes:

  • 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 laquelle 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 du Chrome Web Store

Dans la section Valider la propriété de l'application du client de l'extension Chrome, cliquez sur le bouton Valider la propriété pour terminer le processus de validation.

Remarque:Attendez 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 la réussite du processus de validation. Sinon, une invite d'erreur s'affiche.

Pour résoudre un problème 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 é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 du Chrome Web Store
  • Si vous venez de modifier votre liste d'éditeurs de groupe, vérifiez qu'elle 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

App Check (iOS uniquement)

La fonctionnalité App Check permet de protéger vos applications iOS contre une utilisation non autorisée en utilisant l'API App Attest d'Apple pour vérifier que les requêtes envoyées aux points de terminaison OAuth 2.0 de Google proviennent de vos applications authentiques. Cela permet de réduire le risque d'usurpation d'identité d'application.

Activer App Check pour votre client iOS

Les conditions suivantes doivent être remplies pour activer App Check pour votre client iOS :
  • Vous devez spécifier un ID d'équipe pour votre client iOS.
  • Vous ne devez pas utiliser de caractère générique dans votre ID de bundle, car il peut résoudre plusieurs applications. Cela signifie que l'ID de bundle ne doit pas inclure le symbole astérisque (*).
Pour activer App Check, activez le bouton bascule Protégez votre client OAuth des utilisations abusives avec Firebase App Check dans la vue de modification de votre client iOS.

Une fois App Check activé, vous commencerez à voir des métriques liées aux requêtes OAuth de votre client dans la vue de modification du client OAuth. Les requêtes provenant de sources non validées ne seront pas bloquées tant que vous n'aurez pas implémenté App Check. Les informations de la page de surveillance des métriques peuvent vous aider à déterminer quand commencer à appliquer les règles.

Vous pouvez rencontrer des erreurs liées à la fonctionnalité App Check lorsque vous l'activez pour votre application iOS. Pour résoudre ces erreurs, procédez comme suit:

  • Vérifiez que l'ID du bundle et l'ID de l'équipe que vous avez spécifiés sont valides.
  • Vérifiez que vous n'utilisez pas de caractère générique pour l'ID du bundle.

Appliquer la vérification des applications à votre client iOS

L'activation d'App Check pour votre application ne bloque pas automatiquement les requêtes non reconnues. Pour appliquer cette protection, accédez à la vue de modification de votre client iOS. Vous y trouverez les métriques App Check à droite de la page, sous la section Google Identity pour iOS. Les métriques incluent les informations suivantes :
  • Nombre de requêtes validées : requêtes associées à un jeton App Check valide. Une fois l'application App Check activée, seules les requêtes de cette catégorie aboutiront.
  • Nombre de requêtes non validées : requêtes client obsolètes : requêtes non associées à un jeton App Check. Ces requêtes peuvent provenir d'une ancienne version de votre application qui n'inclut pas d'implémentation App Check.
  • Nombre de requêtes non validées : requêtes d'origine inconnue : requêtes non associées à un jeton App Check qui ne semblent pas provenir de votre application.
  • Nombre de requêtes non validées : requêtes non valides : requêtes associées à un jeton App Check non valide, qui peuvent provenir d'un client non authentique tentant de se faire passer pour votre application, ou d'environnements d'émulation.
Consultez ces métriques pour comprendre l'impact de l'application de l'App Check sur vos utilisateurs.

Pour appliquer la vérification des applications, cliquez sur le bouton ENFORCE et confirmez votre choix. Une fois la validation appliquée, toutes les requêtes non validées de votre client seront refusées.

Remarque: Une fois l'application forcée activée, la prise en compte des modifications peut prendre jusqu'à 15 minutes.

Désactiver App Check pour votre client iOS

Si vous désactivez App Check pour votre application, la validation sera arrêtée et toutes les requêtes de votre client vers les points de terminaison Google OAuth 2.0, y compris les requêtes non validées, seront autorisées.

Pour désactiver App Check pour votre client iOS, accédez à la vue de modification du client iOS, puis cliquez sur le bouton UNENFORCE (NE PAS APPLIQUER) et confirmez votre choix.

Remarque: Une fois la vérification des applications désactivée, la prise en compte des modifications peut prendre jusqu'à 15 minutes.

Désactiver App Check pour votre client iOS

Si vous désactivez App Check pour votre application, toutes les fonctionnalités de surveillance et d'application seront arrêtées. Envisagez plutôt de désactiver App Check pour pouvoir continuer à surveiller les métriques de votre client.

Pour désactiver App Check pour votre client iOS, accédez à la vue de modification du client iOS, puis désactivez le bouton d'activation/de désactivation Protégez votre client OAuth des utilisations abusives avec Firebase App Check.

Remarque: Une fois la vérification des applications désactivée, la prise en compte des modifications peut prendre jusqu'à 15 minutes.

Documentation complémentaire

Les bonnes pratiques actuelles de l'IETF OAuth 2.0 pour les applications natives établissent bon nombre des bonnes pratiques décrites ici.

Implémenter la protection multicompte

Pour protéger les comptes de vos utilisateurs, vous devez également implémenter la protection multicompte à l'aide du service de protection multicompte de Google. Ce service vous permet de vous abonner à des notifications d'événements de sécurité qui fournissent des informations à votre application sur les modifications majeures apportées au compte utilisateur. Vous pouvez ensuite utiliser ces informations pour prendre des mesures en fonction de la façon 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 .