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 des données spécifiques avec une application tout en préservant la confidentialité de leurs noms d'utilisateur, mots de passe et autres informations. Par exemple, une application peut utiliser OAuth 2.0 pour obtenir l'autorisation de mettre en ligne des vidéos sur la chaîne YouTube d'un utilisateur.

Les applications installées sont distribuées sur des appareils individuels et nous partons du principe que ces applications ne peuvent pas conserver de secrets. Ils peuvent accéder aux API Google lorsque l'utilisateur utilise l'application ou lorsque celle-ci s'exécute en arrière-plan.

Ce flux d'autorisation est semblable à celui utilisé pour les applications de serveur Web. La principale différence est que les applications installées doivent ouvrir le navigateur système et fournir un URI de redirection locale pour gérer les réponses du serveur d'autorisation de Google.

Alternatives

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

Pour les applications exécutées sur des appareils qui ne sont pas compatibles avec un navigateur système ou dont les capacités de saisie sont limitées, tels que les téléviseurs, les consoles de jeu, les appareils photo ou les imprimantes, consultez OAuth 2.0 pour les téléviseurs et les appareils ou Se connecter sur des téléviseurs et des périphériques d'entrée limités.

Bibliothèques et exemples

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

• Bibliothèque AppAuth pour Android
• Bibliothèque AppAuth pour iOS
• OAuth pour les applications: exemples Windows

Conditions préalables

Activer les API pour votre projet.

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

Pour activer une API pour votre projet:

1. Open the API Library dans Google API Console.
2. If prompted, select a project, or create a new one.
3. Accédez à la page Bibliothèque pour rechercher et activer l'API YouTube Data. 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 ces identifiants pour accéder aux API que vous avez activées pour ce projet.

1. Go to the Credentials page.
2. Cliquez sur Créer des identifiants > ID client OAuth.
3. Les sections ci-dessous décrivent les types de clients et les méthodes de redirection compatibles avec le serveur d'autorisation de Google. Choisissez le type de client recommandé pour votre application, attribuez un nom à votre client OAuth, puis 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 ne demander l'accès qu'aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils accordent à votre application. Ainsi, il peut y avoir une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur.

Avant de commencer à implémenter l'autorisation OAuth 2.0, nous vous recommandons d'identifier les champs d'application 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:

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

Étape 1: Générer un outil de vérification du code et un test

Google accepte le protocole Proof Key for Code Exchange (PKCE) afin de renforcer la sécurité du flux de l'application installée. Un outil de vérification de code unique est créé pour chaque requête d'autorisation, et sa valeur transformée, appelée "code_challenge", est envoyée au serveur d'autorisation pour obtenir le code d'autorisation.

Créer l'outil de vérification du code

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

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

Créer le défi de code

Il existe deux méthodes pour créer le défi de code.

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

code_challenge = code_verifier

Étape 2: Envoyez 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 response_type et client_id obligatoires, ainsi que le paramètre facultatif state. Chaque URL contient des sauts de ligne et des espaces pour faciliter la lecture.

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

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

Au cours de cette étape, l'utilisateur décide d'accorder ou non l'accès demandé à votre application. À ce stade, Google affiche une fenêtre de consentement indiquant le nom de votre application et les services d'API Google auxquels il demande l'autorisation d'accéder à l'aide des identifiants de l'utilisateur, ainsi qu'un résumé des champs d'application d'accès à accorder. L'utilisateur peut ensuite accepter d'accorder l'accès à un ou plusieurs champs d'application demandés par votre application, ou refuser la requête.

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

Étape 4: Gérer la réponse du serveur OAuth 2.0

La manière dont votre application reçoit la réponse d'autorisation dépend du schéma d'URI de redirection qu'elle utilise. Quel que soit le schéma, la réponse contiendra un code d'autorisation (code) ou une erreur (error). Par exemple, error=access_denied indique que l'utilisateur a refusé la requête.

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

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

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

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 :

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

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

Appeler des API Google

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour appeler une API Google au nom d'un compte utilisateur donné si les champs d'application d'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête adressée à l'API en incluant un paramètre de requête access_token ou une valeur 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 Data).

Notez que l'API YouTube Data n'accepte les comptes de service que pour les propriétaires de contenu YouTube qui possèdent et gèrent plusieurs chaînes YouTube, comme des maisons de disques et des studios de cinéma.

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

Exemples de requête 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. Si vous avez demandé un accès hors connexion aux champs d'application associés au jeton, vous pouvez actualiser un jeton d'accès sans demander l'autorisation de l'utilisateur (y compris en son absence).

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 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 présente un exemple de réponse:

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

Notez que le nombre de jetons d'actualisation qui seront émis est limité : une limite par combinaison client/utilisateur et une autre par utilisateur pour tous les clients. Nous vous conseillons d'enregistrer les jetons d'actualisation dans un espace de stockage à long terme et de continuer à les utiliser tant qu'ils restent valides. Si votre application demande trop de jetons d'actualisation, elle peut dépasser 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 dans les paramètres du compte. Pour en savoir plus, consultez la section Supprimer l'accès à un site ou une application de la documentation d'assistance "Applications et sites tiers ayant accès à votre compte".

Une application peut également révoquer de manière programmatique l'accès qui lui est accordé. La révocation programmatique est importante dans les cas où un utilisateur se désabonne, supprime une application ou si les ressources d'API requises par une application ont changé de manière significative. En d'autres termes, une partie du processus de suppression peut inclure une requête API pour s'assurer que les autorisations précédemment accordées à l'application sont supprimées.

Pour révoquer un jeton de manière automatisée, votre application envoie une requête à https://oauth2.googleapis.com/revoke et inclut le jeton en tant que paramètre:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

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, il sera également révoqué.

Si la révocation a bien été traitée, le code d'état HTTP de la réponse est 200. Pour les conditions d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

Documentation complémentaire

Le guide OAuth 2.0 for Native Apps (Bonnes pratiques actuelles de l'IETF) définit un grand nombre des bonnes pratiques décrites sur cette page.