Ce document explique comment mettre en œuvre l'autorisation OAuth 2.0 pour accéder aux API Google via des applications s'exécutant sur des appareils tels que des téléviseurs, des consoles de jeu et des imprimantes. Plus précisément, ce flux est conçu pour les appareils qui n'ont pas accès à un navigateur ou qui ont des capacités de saisie limitées.
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 TV peut utiliser OAuth 2.0 pour obtenir l'autorisation de sélectionner un fichier stocké sur Google Drive.
Étant donné que les applications qui utilisent ce flux sont distribuées sur des appareils individuels, nous partons du principe que les applications ne peuvent pas garder de secrets. Ils peuvent accéder aux API Google lorsque l'utilisateur est présent dans l'application ou en arrière-plan.
Alternatives
Si vous développez une application pour une plate-forme comme Android, iOS, macOS, Linux ou Windows (y compris la plate-forme Windows universelle), qui a accès au navigateur et à l'ensemble des fonctionnalités d'entrée, utilisez le flux OAuth 2.0 pour les applications mobiles et de bureau. (Vous devez utiliser ce flux même si votre application est un outil de ligne de commande sans interface graphique.)
Si vous souhaitez uniquement connecter les utilisateurs avec leur compte Google et utiliser le jeton d'ID JWT pour obtenir des informations de profil utilisateur de base, consultez la page Se connecter sur des téléviseurs et des appareils de saisie limités.
Prerequisites
Activer les API pour votre projet.
Toute application qui appelle les API Google doit activer ces API dans le API Console.
Pour activer une API pour votre projet:
- Open the API Library dans Google API Console.
- If prompted, select a project, or create a new one.
- API Library répertorie toutes les API disponibles, regroupées par famille de produits et classées en fonction de leur popularité. Si l'API que vous souhaitez activer n'est pas visible dans la liste, recherchez-la ou cliquez sur Tout afficher dans la famille de produits à laquelle elle appartient.
- Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
- If prompted, enable billing.
- 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 sur le serveur OAuth 2.0 de Google. Les étapes suivantes expliquent comment créer des identifiants pour votre projet. Vos applications peuvent ensuite utiliser les identifiants pour accéder aux API que vous avez activées pour ce projet.
- Go to the Credentials page.
- Cliquez sur Créer des identifiants > ID client OAuth.
- Sélectionnez le type d'application Téléviseurs et périphériques à saisie limitée.
- Nommez votre client OAuth 2.0, puis cliquez sur Create (Créer).
Identifier les niveaux d'accès
Les champs d'application permettent à votre application de demander l'accès aux ressources dont elle a besoin tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils peuvent accorder à votre application. Par conséquent, 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 à mettre en œuvre l'autorisation OAuth 2.0, nous vous recommandons d'identifier les niveaux d'accès requis pour votre application.
Consultez la liste Niveaux d'accès autorisés pour connaître les applications et les appareils installés.
Obtenir des jetons d'accès OAuth 2.0
Même si votre application s'exécute sur un appareil aux fonctionnalités de saisie limitées, les utilisateurs doivent disposer d'un accès distinct à un appareil doté de fonctionnalités d'entrée plus riches pour terminer ce flux d'autorisation. Le parcours comprend les étapes suivantes:
- Votre application envoie une requête au serveur d'autorisation de Google, qui identifie les champs d'application auxquels elle demandera l'autorisation d'accéder.
- Le serveur répond avec plusieurs informations utilisées lors des étapes suivantes, telles qu'un code d'appareil et un code utilisateur.
- Affichez les informations que l'utilisateur peut saisir sur un appareil distinct pour autoriser votre application.
- Votre application commence à interroger le serveur d'autorisation de Google afin de déterminer si l'utilisateur a autorisé votre application.
- L'utilisateur accède à un appareil doté de fonctionnalités de saisie plus riches, lance un navigateur Web, accède à l'URL affichée à l'étape 3 et saisit un code qui s'affiche également à l'étape 3. L'utilisateur peut alors accorder (ou refuser) l'accès à votre application.
- La réponse suivante à votre demande d'interrogation contient les jetons d'autorisation requis par votre application pour le compte de l'utilisateur. (Si l'utilisateur a refusé l'accès à votre application, la réponse ne contient pas de jetons.)
L'image ci-dessous illustre le processus:
Les sections suivantes expliquent cette procédure en détail. Compte tenu de la variété des fonctionnalités et des environnements d'exécution dont peuvent disposer les appareils, les exemples présentés dans ce document utilisent l'utilitaire de ligne de commande curl. Ces exemples doivent pouvoir être facilement transférés vers différents langages et environnements d'exécution.
Étape 1: Demandez des codes d'appareil et d'utilisateur
Dans cette étape, votre appareil envoie une requête HTTP POST au serveur d'autorisation de Google, à l'adresse https://oauth2.googleapis.com/device/code, pour identifier votre application, ainsi que les niveaux d'accès auxquels votre application souhaite accéder au nom de l'utilisateur.
Vous devez la récupérer à partir du document de découverte à l'aide de la valeur des métadonnées device_authorization_endpoint. Incluez les paramètres de requête HTTP suivants:
| Paramètres | |
|---|---|
client_id |
Obligatoire
ID client de votre application. Vous pouvez trouver cette valeur dans le API ConsoleCredentials page. |
scope |
Obligatoire
Liste de champs d'application délimitée par des espaces qui identifient les ressources auxquelles votre application peut accéder au nom de l'utilisateur. Ces valeurs indiquent l'écran de consentement que Google affiche à l'utilisateur. Consultez la liste Niveaux d'accès autorisés pour les applications ou les appareils installés. Les champs d'application permettent à votre application de demander l'accès aux ressources dont elle a besoin tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils peuvent accorder à 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. |
Examples
L'extrait de code suivant présente un exemple de requête:
POST /device/code HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=client_id&scope=
Cet exemple montre une commande curl pour envoyer la même requête:
curl -d "client_id=client_id&scope=" \
https://oauth2.googleapis.com/device/code
Étape 2: Gérez la réponse du serveur d'autorisation
Le serveur d'autorisation renvoie l'une des réponses suivantes:
Réponse de réussite
Si la requête est valide, votre réponse est un objet JSON contenant les propriétés suivantes:
| Properties | |
|---|---|
device_code |
Valeur attribuée de manière unique par Google pour identifier l'appareil qui exécute l'application demandant l'autorisation. L'utilisateur autorisera cet appareil à partir d'un autre appareil doté de fonctionnalités d'entrée plus riches. Par exemple, un utilisateur peut utiliser un ordinateur portable ou un téléphone mobile pour autoriser une application s'exécutant sur un téléviseur. Dans ce cas, device_code identifie le téléviseur.
Ce code permet à l'appareil qui exécute l'application de déterminer de manière sécurisée si l'utilisateur a accordé ou refusé un accès. |
expires_in |
Durée, en secondes, de validité des valeurs device_code et user_code. Dans ce cas, si l'utilisateur n'a pas terminé le parcours d'autorisation et que votre appareil n'effectue pas non plus de sondage pour récupérer les informations sur la décision de l'utilisateur, vous devrez peut-être recommencer le processus à l'étape 1. |
interval |
Durée, en secondes, pendant laquelle votre appareil doit attendre entre deux demandes de sondage. Par exemple, si la valeur est 5, votre appareil doit envoyer une requête d'interrogation au serveur d'autorisation de Google toutes les cinq secondes. Pour en savoir plus, reportez-vous à l'étape 3. |
user_code |
Valeur sensible à la casse qui identifie à Google les champs d'application auxquels l'application demande l'accès. Votre interface utilisateur indiquera à l'utilisateur de saisir cette valeur sur un appareil distinct doté de fonctionnalités de saisie plus riches. Google utilise ensuite cette valeur pour afficher l'ensemble de champs d'application approprié lorsque l'utilisateur invite l'utilisateur à accorder l'accès à votre application. |
verification_url |
URL à laquelle l'utilisateur doit accéder, sur un appareil distinct, pour saisir la propriété user_code et accorder ou refuser l'accès à votre application. Elle s'affichera également dans votre interface utilisateur. |
L'extrait de code suivant illustre un exemple de réponse:
{
"device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code": "GQVQ-JKEC",
"verification_url": "https://www.google.com/device",
"expires_in": 1800,
"interval": 5
}
Réponse au quota dépassé
Si les requêtes de code d'appareil dépassent le quota associé à votre ID client, vous recevrez une réponse 403, avec l'erreur suivante:
{
"error_code": "rate_limit_exceeded"
}
Dans ce cas, utilisez une stratégie d'intervalle entre les tentatives pour réduire le taux de demandes.
Étape 3: Affichez le code utilisateur
Affichez à l'utilisateur le verification_url et le user_code obtenus à l'étape 2. Ces deux valeurs peuvent contenir n'importe quel caractère imprimable du jeu de caractères US-ASCII. Le contenu que vous présentez à l'utilisateur doit lui demander d'accéder à verification_url sur un appareil distinct, puis de saisir user_code.
Concevez votre interface utilisateur en tenant compte des règles suivantes:
user_code- Le
user_codedoit être affiché dans un champ pouvant accepter 15 caractères. En d'autres termes, si vous pouvez afficher correctement le codeWWWWWWWWWWWWWWW, votre interface utilisateur est valide. Nous vous recommandons d'utiliser cette valeur de chaîne lorsque vous testez l'affichage deuser_codedans votre interface utilisateur. - L'élément
user_codeest sensible à la casse et ne doit pas être modifié, que ce soit en modifiant la casse ou en insérant d'autres caractères de mise en forme.
- Le
verification_url- L'espace dans lequel vous affichez
verification_urldoit être suffisamment large pour gérer une chaîne d'URL de 40 caractères. - Vous ne devez pas modifier le
verification_urlde quelque manière que ce soit, sauf pour supprimer le schéma d'affichage. Si vous prévoyez d'exclure le schéma (https://, par exemple) de l'URL pour des raisons d'affichage, assurez-vous que votre application peut gérer à la fois les varianteshttpethttps.
- L'espace dans lequel vous affichez
Étape 4: Sondez le serveur d'autorisation de Google
Étant donné que l'utilisateur utilisera un appareil distinct pour accéder à la propriété verification_url et accordera (ou refusera) l'accès, l'appareil à l'origine de la demande n'est pas automatiquement averti lorsque l'utilisateur répond à la demande d'accès. C'est pourquoi l'appareil à l'origine de la demande doit interroger le serveur d'autorisation de Google afin de déterminer si l'utilisateur a répondu à la demande.
L'appareil à l'origine de la demande doit continuer à envoyer des requêtes d'interrogation jusqu'à ce qu'il reçoive une réponse indiquant que l'utilisateur a répondu à la demande d'accès ou que les device_code et user_code obtenus à l'étape 2 ont expiré. Le interval renvoyé à l'étape 2 spécifie la durée d'attente, en secondes, entre les requêtes.
L'URL du point de terminaison à interroger est https://oauth2.googleapis.com/token. La requête d'interrogation contient les paramètres suivants:
| Paramètres | |
|---|---|
client_id |
ID client de votre application. Vous pouvez trouver cette valeur dans le API ConsoleCredentials page. |
client_secret |
Code secret du client pour le client_id fourni. Vous pouvez trouver cette valeur dans le API ConsoleCredentials page. |
device_code |
Le device_code renvoyé par le serveur d'autorisation à l'étape 2. |
grant_type |
Définissez cette valeur sur urn:ietf:params:oauth:grant-type:device_code. |
Examples
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=client_id& client_secret=client_secret& device_code=device_code& grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
Cet exemple montre une commande curl pour envoyer la même requête:
curl -d "client_id=client_id&client_secret=client_secret& \
device_code=device_code& \
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
-H "Content-Type: application/x-www-form-urlencoded" \
/token
Étape 5: L'utilisateur répond à la demande d'accès
L'image suivante montre une page semblable à celle que les utilisateurs voient lorsqu'ils accèdent à la verification_url à l'étape 3 :
Une fois que vous avez saisi user_code et que vous n'êtes pas déjà connecté à Google, l'utilisateur voit un écran de consentement comme celui présenté ci-dessous:
Étape 6: Gérez les réponses aux demandes de sondages
Le serveur d'autorisation de Google répond à chaque requête d'interrogation avec l'une des réponses suivantes:
Accès autorisé
Si l'utilisateur a accordé l'accès à l'appareil (en cliquant sur Allow sur l'écran de consentement), la réponse contient un jeton d'accès et un jeton d'actualisation. Ces jetons permettent à votre appareil d'accéder aux API Google au nom de l'utilisateur. (La propriété scope de la réponse détermine les API auxquelles l'appareil peut accéder.)
Dans ce cas, la réponse de l'API contient les champs suivants:
| Champs | |
|---|---|
access_token |
Jeton que votre application envoie pour autoriser une requête API Google. |
expires_in |
Durée de vie restante du jeton d'accès, en secondes. |
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 appareils. |
scope |
Champs d'application d'accès accordés par access_token, exprimés sous forme de liste sensible à la casse. |
token_type |
Type de jeton renvoyé. Pour l'instant, la valeur de ce champ est toujours définie sur Bearer. |
L'extrait de code suivant illustre un exemple de réponse:
{
"access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
"expires_in": 3920,
"scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
"token_type": "Bearer",
"refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}
Les jetons d'accès ont une durée de vie limitée. Si votre application a besoin d'accéder à une API pendant une longue période, elle peut utiliser le jeton d'actualisation pour obtenir un nouveau jeton. Si votre application a besoin de ce type d'accès, elle doit stocker le jeton d'actualisation pour une utilisation ultérieure.
Accès refusé
Si l'utilisateur refuse d'accorder l'accès à l'appareil, la réponse du serveur possède un code d'état de réponse HTTP 403 (Forbidden). La réponse contient l'erreur suivante:
{
"error": "access_denied",
"error_description": "Forbidden"
}
Autorisation en attente
Si l'utilisateur n'a pas encore terminé le flux d'autorisation, le serveur affiche un code d'état de réponse HTTP 428 (Precondition Required). La réponse contient l'erreur suivante:
{
"error": "authorization_pending",
"error_description": "Precondition Required"
}
Sondage trop fréquent
Si l'appareil envoie trop souvent des requêtes de sondage, le serveur renvoie un code d'état de réponse HTTP 403 (Forbidden). La réponse contient l'erreur suivante:
{
"error": "slow_down",
"error_description": "Forbidden"
}
Autres erreurs
Le serveur d'autorisation renvoie également des erreurs si des paramètres obligatoires sont manquants dans la requête d'interrogation ou si leur valeur est incorrecte. Ces requêtes ont généralement un code d'état de réponse HTTP 400 (Bad Request) ou 401 (Unauthorized). Voici quelques exemples d'erreurs:
| Erreur | HTTP Status Code | Description |
|---|---|---|
invalid_client |
401 |
Le client OAuth est introuvable. Par exemple, cette erreur se produit si la valeur du paramètre client_id n'est pas valide. |
invalid_grant |
400 |
La valeur du paramètre code n'est pas valide. |
unsupported_grant_type |
400 |
La valeur du paramètre grant_type n'est pas valide. |
Appeler des API Google
Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour appeler des API Google au nom d'un compte utilisateur donné, si le ou les niveaux d'accès requis par l'API vous 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, il est préférable d'utiliser l'en-tête HTTP, car les chaînes de requête sont généralement 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 essayer toutes les API Google et en consulter la portée sur OAuth 2.0 Playground.
Exemples de requêtes HTTP GET
Un appel vers le 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 vers 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
Exemples curl
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 (méthode recommandée):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Vous pouvez également sélectionner l'option du 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 d'autorisation à l'utilisateur (y compris lorsque l'utilisateur n'est pas présent) si vous avez demandé l'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 POSTau serveur d'autorisation Google (https://oauth2.googleapis.com/token) qui inclut les paramètres suivants:
| Champs | |
|---|---|
client_id |
ID client obtenu à partir de API Console. |
client_secret |
Code secret du client obtenu à partir de API Console. |
grant_type |
Comme indiqué dans la spécification OAuth 2.0, la valeur de ce champ doit être définie sur refresh_token. |
refresh_token |
Jeton d'actualisation renvoyé par l'échange du code d'autorisation. |
L'extrait de code suivant présente un exemple de requête:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& client_secret=your_client_secret& refresh_token=refresh_token& grant_type=refresh_token
Tant que l'utilisateur n'a pas révoqué l'accès accordé à l'application, le serveur de jetons renvoie un objet JSON contenant un nouveau jeton. 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 émis sera limité : une limite par combinaison client/utilisateur et une autre par utilisateur pour tous les clients. Nous vous recommandons d'enregistrer les jetons d'actualisation dans un espace de stockage à long terme et de les utiliser tant qu'ils restent valides. Si votre application demande trop de jetons d'actualisation, elle peut atteindre ces limites. Dans ce cas, les anciens jetons d'actualisation ne fonctionnent plus.
Révoquer un jeton
Dans certains cas, l'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 aux sites et aux applications depuis le site et les applications tiers ayant accès à votre compte.
Il est également possible pour une application de révoquer par programmation 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 les ressources d'API requises par une application ont changé de manière significative. En d'autres termes, une partie du processus de suppression peut inclure une requête API pour garantir la suppression des autorisations précédemment accordées à l'application.
Pour révoquer automatiquement un jeton, votre application envoie une requête à https://oauth2.googleapis.com/revoke et inclut ce jeton en tant que paramètre:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}
Le jeton peut être un jeton d'accès ou un jeton d'actualisation. Si le jeton est un jeton d'accès et qu'il possède un jeton d'actualisation correspondant, il est également révoqué.
Si la révocation a été traitée correctement, le code d'état HTTP de la réponse est 200. En cas d'erreurs, un code d'état HTTP 400 est renvoyé avec un code d'erreur.
Champs d'application autorisés
Le parcours OAuth 2.0 pour les appareils n'est compatible qu'avec les champs d'application suivants:
OpenID Connect, Google Sign-In
emailopenidprofile
API Drive
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
API YouTube
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly