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 d'importer des vidéos sur la chaîne YouTube d'un utilisateur.
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:
- Bibliothèque AppAuth for Android
- Bibliothèque AppAuth pour iOS
- OAuth pour les applications: exemples Windows
Prérequis
Activer les API pour votre projet.
Toute application qui appelle des API Google doit les activer dans .
Pour activer une API pour votre projet:
- dans le .
- Recherchez et activez l'API YouTube Data sur la page Library (Bibliothèque). Recherchez 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 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.
- Cliquez sur Créer des identifiants > ID client OAuth.
- 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
- Sélectionnez le type d'application Android.
- Saisissez un nom pour le client OAuth. Ce nom s'affiche dans la de votre projet pour identifier le client.
- 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. - 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 sectionCertificate fingerprints
de la sortie keytool. Pour en savoir plus, consultez la section Authentifier votre client dans la documentation des API Google pour Android.
- (Facultatif) Validez la propriété de votre application Android.
- Cliquez sur Créer.
iOS
- Sélectionnez le type d'application iOS.
- Saisissez un nom pour le client OAuth. Ce nom s'affiche dans la de votre projet pour identifier le client.
- 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.
- (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.
- Ouvrez l'application App Store d'Apple sur votre appareil iOS ou iPadOS.
- Recherchez votre application.
- Sélectionnez le bouton "Partager" (symbole en forme de carré et de flèche vers le haut).
- Sélectionnez Copier le lien.
- 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
- (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. - (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
- Cliquez sur Créer.
UWP
- Sélectionnez le type d'application Universal Windows Platform.
- Saisissez un nom pour le client OAuth. Ce nom s'affiche dans la de votre projet pour identifier le client.
- 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".
- 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.
La version 3 de l'API YouTube Data utilise les champs d'application suivants:
Niveaux d'accès | |
---|---|
https://www.googleapis.com/auth/youtube | Gérez votre compte YouTube. |
https://www.googleapis.com/auth/youtube.channel-memberships.creator | Consulter 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-ssl | Afficher, modifier et supprimer définitivement vos vidéos, notes, commentaires et sous-titres YouTube |
https://www.googleapis.com/auth/youtube.readonly | Consultez votre compte YouTube. |
https://www.googleapis.com/auth/youtube.upload | Gérez vos vidéos YouTube. |
https://www.googleapis.com/auth/youtubepartner | Affichez et gérez vos éléments et le contenu associé sur YouTube. |
https://www.googleapis.com/auth/youtubepartner-channel-audit | Affichez les informations privées sur votre chaîne YouTube pertinentes pendant le processus d'audit avec un partenaire YouTube. |
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.
|
plain | Le défi de code est identique à la valeur générée par le vérificateur de code ci-dessus.
|
Étape 2: Envoyer une requête au serveur OAuth 2.0 de Google
Pour obtenir l'autorisation de l'utilisateur, envoyez une requête au serveur d'autorisation de Google à l'adresse https://accounts.google.com/o/oauth2/v2/auth
. Ce point de terminaison gère la recherche de session active, authentifie l'utilisateur et obtient son consentement. Le point de terminaison n'est accessible que via SSL et refuse les connexions HTTP (non SSL).
Le serveur d'autorisation accepte les paramètres de chaîne de requête suivants pour les applications installées:
Paramètres | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Obligatoire
ID client de votre application. Vous pouvez trouver cette valeur dans le . |
||||||||||||||||
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
de votre client. Si cette valeur ne correspond pas à un URI autorisé, une erreur Le tableau ci-dessous indique la valeur de paramètre
|
||||||||||||||||
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 |
||||||||||||||||
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. La version 3 de l'API YouTube Data utilise les champs d'application suivants:
Le document Champs d'application des API OAuth 2.0 fournit la liste complète des champs d'application que vous pouvez utiliser pour accéder aux API Google. |
||||||||||||||||
code_challenge |
Recommandé
Spécifie un |
||||||||||||||||
code_challenge_method |
Recommandé
Spécifie la méthode utilisée pour encoder un |
||||||||||||||||
state |
Recommandé
Spécifie toute valeur de chaîne que votre application utilise pour maintenir l'état entre votre demande d'autorisation et la réponse du serveur d'autorisation.
Le serveur renvoie la valeur exacte que vous envoyez en tant que paire 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 |
||||||||||||||||
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 |
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 d'afficher le compte 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 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly& 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly& 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 .
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 . |
client_secret |
Code secret du client obtenu à partir de . |
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
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/youtube.force-ssl", "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 au jeton d'accès suivant indique que l'utilisateur a autorisé votre application à afficher, modifier et supprimer définitivement ses vidéos, notes, commentaires et sous-titres YouTube:
{ "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 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 YouTube Data).
Notez que l'API YouTube Data n'est compatible qu'avec les comptes de service des propriétaires de contenus YouTube qui possèdent et gèrent plusieurs chaînes YouTube, comme les maisons de disques et les studios de cinéma.
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
youtube.channels
(API YouTube Data) à 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/channels?part=snippet&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/channels?access_token=access_token&part=snippet&mine=true
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/youtube/v3/channels?part=snippet&mine=true
Vous pouvez également utiliser l'option de paramètre de chaîne de requête:
curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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 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 . |
client_secret |
Code secret du client obtenu auprès de .
(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", "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é:
- Mettez à jour votre code pour utiliser le SDK Google Sign-In.
- 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:
-
Mettez à jour votre code pour utiliser le SDK Android de Google Sign-In :
-
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ètreredirect_uri
. -
Notez les paramètres de requête
scope
etclient_id
dont vous avez besoin pour configurer le SDK Google Sign-In. -
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. -
Suivez les instructions de la section
Activer l'accès côté serveur aux API. Cela comprend les étapes suivantes :
-
Utilisez la méthode
getServerAuthCode
pour récupérer un code d'autorisation pour les champs d'application pour lesquels vous demandez l'autorisation. - Envoyez le code d'autorisation au backend de votre application pour l'échanger contre un jeton d'accès et d'actualisation.
- Utilisez le jeton d'accès récupéré pour appeler les API Google au nom de l'utilisateur.
-
Utilisez la méthode
-
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:
-
Désactivez la prise en charge du schéma personnalisé dans la console Google API :
- Accédez à la liste de vos identifiants OAuth 2.0 et sélectionnez votre client Android.
- 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 :- Accédez à la liste de vos identifiants OAuth 2.0, puis sélectionnez votre client Android.
- 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 (*).
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.
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 .