OAuth 2.0 pour les applications mobiles et de bureau

Ce document explique comment les applications installées sur des appareils tels que les téléphones, les tablettes et les 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 certaines données avec une application tout en préservant la confidentialité de leurs noms d'utilisateur, mots de passe et autres informations. Par exemple, une application peut utiliser OAuth 2.0 pour obtenir l'autorisation de récupérer les données YouTube d'une chaîne.

Les applications installées sont distribuées sur des appareils individuels, et il est supposé que ces applications ne peuvent pas garder de secrets. Ils 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.

Bibliothèques et exemples

Pour les applications mobiles, nous vous recommandons d'utiliser la dernière version de la bibliothèque native Google Identity Services pour Android et de la bibliothèque native Google Sign-In pour iOS. Ces bibliothèques gèrent l'autorisation des utilisateurs et sont 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 un navigateur système ou qui ont des capacités d'entrée limitées, comme les téléviseurs, les consoles de jeux, les caméras 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.

Prérequis

Activer les API pour votre projet.

Toute application qui appelle des API Google doit activer ces API 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. Rechercher et activer l'API YouTube Data sur la page "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.

1. Go to the Credentials page.
2. Cliquez sur Créer un client.
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 vos besoins.

Identifier les niveaux d'accès

Les niveaux d'accès permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils accordent à votre application. Il peut donc exister une relation inverse entre le nombre de niveaux d'accès demandés et la probabilité d'obtenir le consentement de l'utilisateur.

Avant de commencer la mise en œuvre de 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.

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

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 d'API en son nom. Votre application doit obtenir ce consentement avant de pouvoir exécuter une requête d'API Google nécessitant l'autorisation de l'utilisateur.

Étape 1 : Générer un code de vérification et un challenge

Google est compatible avec le protocole Proof Key for Code Exchange (PKCE) pour sécuriser davantage le flux d'application installée. Un code de vérification unique est créé pour chaque demande d'autorisation. 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 utilisant 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 code de vérification doit avoir un degré d'entropie suffisant pour être impossible à deviner.

Créer le défi de programmation

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

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

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 sessions actives, 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 :

Exemples d'URL d'autorisation

Les onglets ci-dessous présentent des exemples d'URL d'autorisation pour les différentes options d'URI de redirection.

Les URL sont identiques, à l'exception de la valeur du paramètre redirect_uri. Les URL contiennent également les paramètres obligatoires response_type et client_id, ainsi que le paramètre facultatif state. Chaque URL contient des sauts de ligne et des espaces pour plus de lisibilité.

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

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 demande le consentement de l'utilisateur

Au cours de cette étape, l'utilisateur décide d'accorder ou non à votre application l'accès demandé. À cette étape, 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 demande.

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.

É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 demande.

Si l'utilisateur accorde l'accès à votre application, vous pouvez échanger le code d'autorisation contre un jeton d'accès et un jeton d'actualisation, comme décrit à l'étape suivante.

Étape 5 : Échangez le code d'autorisation contre des jetons d'actualisation et d'accès

Pour échanger un code d'autorisation contre un jeton d'accès, appelez le point de terminaison https://oauth2.googleapis.com/token et définissez les paramètres suivants :

L'extrait de code suivant montre un exemple de requête :

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

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 à courte durée de vie et un jeton d'actualisation.

La réponse contient les champs suivants :

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 https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

Lorsque vous demandez plusieurs autorisations (habilitations), il est possible que les utilisateurs n'accordent pas à votre application l'accès à toutes. Votre application doit vérifier les champs d'application qui ont été accordés et gérer correctement les situations où certaines autorisations sont refusées, généralement en désactivant les fonctionnalités qui dépendent de ces champs d'application refusés.

Il existe toutefois des exceptions. Les applications Google Workspace Enterprise avec délégation d'autorité au niveau du domaine ou les applications marquées comme fiables contournent l'écran de consentement pour les autorisations précises. Pour ces applications, les utilisateurs ne verront pas l'écran de consentement pour les autorisations précises. Votre application recevra tous les niveaux d'accès demandés ou aucun.

Pour en savoir plus, consultez Gérer les autorisations précises.

Pour vérifier si l'utilisateur a accordé à votre application l'accès à un champ particulier, examinez le champ scope dans la réponse du jeton d'accès. Champs d'application de l'accès accordé par le jeton d'accès, exprimés sous la forme d'une liste de chaînes sensibles à la casse et délimitées par des espaces.

Par exemple, l'exemple de réponse de jeton d'accès suivant indique que l'utilisateur a accordé à votre application l'accès aux autorisations d'activité Drive et d'événements Agenda en lecture seule :

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl 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 niveaux d'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête envoyée à l'API en incluant un paramètre de requête access_token ou une valeur d'en-tête HTTP Authorization Bearer. Dans la mesure du possible, l'en-tête HTTP est préférable, car les chaînes de requête ont tendance à être visibles dans les journaux 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 de compte de service. Étant donné qu'il n'est pas possible d'associer un compte de service à un compte YouTube, les tentatives d'autorisation de requêtes avec ce flux génèrent une erreur NoLinkedYouTubeAccount.

Vous pouvez tester toutes les API Google et afficher leurs habilitations sur la page OAuth 2.0 Playground.

Exemples de requêtes HTTP GET

Un appel au point de terminaison liveBroadcasts.list (API YouTube Live Streaming) à l'aide de l'en-tête HTTP Authorization: Bearer peut ressembler à ce qui 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

curl exemples

Vous pouvez tester ces commandes avec l'application en ligne de commande curl. Voici un exemple qui utilise l'option d'en-tête HTTP (méthode 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 de 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 l'autorisation à l'utilisateur (y compris en son absence) si vous avez demandé un accès hors connexion aux champs d'application associés au jeton.

Pour actualiser un jeton d'accès, votre application envoie une requête HTTPS POST au serveur d'autorisation de Google (https://oauth2.googleapis.com/token) qui inclut les paramètres suivants :

L'extrait de code suivant montre un exemple de requête :

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

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 qu'il existe des limites au nombre de jetons d'actualisation qui seront émis : une limite par combinaison client/utilisateur et une autre par utilisateur pour tous les clients. Vous devez enregistrer les jetons d'actualisation dans un stockage à long terme et continuer à les utiliser tant qu'ils restent valides. Si votre application demande trop de jetons d'actualisation, elle risque d'atteindre ces limites, auquel cas les jetons d'actualisation plus anciens cesseront de fonctionner.

Révoquer un jeton

Dans certains cas, un utilisateur peut souhaiter révoquer l'accès accordé à une application. Un utilisateur peut révoquer l'accès en accédant aux paramètres de son compte. Pour en savoir plus, consultez la section Supprimer l'accès d'un site ou d'une application du document d'aide Applications et sites tiers ayant accès à votre compte.

Il est également possible pour une application de 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ésabonne, supprime une application ou lorsque les ressources d'API requises par une application ont considérablement changé. En d'autres termes, une partie du processus de suppression peut inclure une requête 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 possède un jeton d'actualisation correspondant, ce dernier sera également révoqué.

Si la révocation est traitée avec succès, le code d'état HTTP de la réponse est 200. En cas d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

Méthodes de redirection d'application

Protéger vos applications

Accès basé sur l'heure

L'accès limité dans le temps permet à un utilisateur d'accorder à votre application l'accès à ses données pour une durée limitée afin d'effectuer une action. L'accès limité dans le temps est disponible dans certains produits Google pendant le processus de consentement. Il permet aux utilisateurs d'accorder l'accès pour une durée limitée. L' API Data Portability, par exemple, permet un transfert unique de données.

Lorsqu'un utilisateur accorde à votre application un accès limité dans le temps, le jeton d'actualisation expire après la durée spécifiée. Notez que les jetons d'actualisation peuvent être invalidés plus tôt dans certaines circonstances. Pour en savoir plus, consultez ces cas. Dans ce cas, le champ refresh_token_expires_in renvoyé dans la réponse d'échange du code d'autorisation représente le temps restant avant l'expiration du jeton d'actualisation.

Documentation complémentaire

La bonne pratique actuelle de l'IETF OAuth 2.0 pour les applications natives établit de nombreuses bonnes pratiques documentées ici.