Ce document explique comment implémenter l'autorisation OAuth 2.0 pour accéder aux API Google via des applications exécutées 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 fonctionnalité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 qu'elles ne peuvent pas conserver de secrets. Ils peuvent accéder aux API Google lorsque l'utilisateur est dans l'application ou lorsque celle-ci s'exécute en arrière-plan.
Autres solutions
Si vous développez une application pour une plate-forme telle qu'Android, iOS, macOS, Linux ou Windows (y compris la plate-forme Windows universelle) qui a accès au navigateur et aux fonctionnalités de saisie complètes, 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 base sur le profil utilisateur, consultez Se connecter sur des téléviseurs et des périphériques d'entrée limités.
Prérequis
Activer les API pour votre projet.
Toute application qui appelle des API Google doit les activer dans API Console.
Pour activer une API pour votre projet, procédez comme suit:
- Open the API Library dans Google API Console.
- If prompted, select a project, or create a new one.
- La vue API Library répertorie toutes les API disponibles, regroupées par famille de produits et par popularité. Si l'API que vous souhaitez activer ne figure pas dans la liste, utilisez la recherche pour la trouver 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 ces 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 d'entrée limités.
- Attribuez un nom à votre client OAuth 2.0, puis cliquez sur Créer.
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 habilitations auxquelles votre application devra être autorisée à accéder.
Consultez la liste des champs d'application autorisés pour les applications ou les appareils installés.
Obtenir des jetons d'accès OAuth 2.0
Même si votre application s'exécute sur un appareil dont les fonctionnalités d'entrée sont limitées, les utilisateurs doivent disposer d'un accès distinct à un appareil doté de fonctionnalités d'entrée plus riches pour effectuer ce flux d'autorisation. Le flux comprend les étapes suivantes:
- Votre application envoie au serveur d'autorisation de Google une requête qui identifie les niveaux d'accès auxquels votre application demandera l'autorisation d'accéder.
- Le serveur répond avec plusieurs informations utilisées aux étapes suivantes, telles qu'un code d'appareil et un code utilisateur.
- Vous affichez des informations que l'utilisateur peut saisir sur un appareil distinct pour autoriser votre application.
- Votre application commence à interroger le serveur d'autorisation de Google pour déterminer si l'utilisateur a autorisé votre application.
- L'utilisateur passe à 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 est également affiché à 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 dont votre application a besoin pour autoriser les requêtes au nom de l'utilisateur. (Si l'utilisateur a refusé l'accès à votre application, la réponse ne contient aucun jeton.)
L'image ci-dessous illustre ce processus:
![L'utilisateur se connecte sur un autre appareil doté d'un navigateur.](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/images/oauth2/device/flow.png?authuser=3&hl=fr)
Les sections suivantes décrivent ces étapes en détail. Compte tenu de la gamme de fonctionnalités et d'environnements d'exécution que peuvent comporter les appareils, les exemples présentés dans ce document utilisent l'utilitaire de ligne de commande curl
. Ces exemples devraient être faciles à transférer vers différents langages et environnements d'exécution.
Étape 1: Demandez les codes de l'appareil et de l'utilisateur
Au cours de cette étape, votre appareil envoie une requête HTTP POST au serveur d'autorisation de Google, à l'adresse https://oauth2.googleapis.com/device/code
, qui identifie votre application ainsi que les niveaux d'accès auxquels votre application souhaite accéder pour le compte de l'utilisateur.
Vous devez récupérer cette URL à partir du document de découverte à l'aide de la valeur de 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 trouverez cette valeur dans API Console Credentials page. |
scope |
Obligatoire
Liste de champs d'application délimités par un espace qui identifient les ressources auxquelles votre application peut accéder pour le compte de l'utilisateur. Ces valeurs déterminent l'écran de consentement que Google présente à l'utilisateur. Consultez la liste des niveaux d'accès autorisés pour les applications ou les appareils installé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 existe une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur. |
Exemples
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=email%20profile
Cet exemple montre une commande curl
permettant d'envoyer la même requête:
curl -d "client_id=client_id&scope=email%20profile" \ 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, la réponse est un objet JSON contenant les propriétés suivantes:
Propriétés | |
---|---|
device_code |
Valeur attribuée de manière unique par Google pour identifier l'appareil qui exécute l'application demandant une 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 exécutée sur un téléviseur. Dans ce cas, le device_code identifie le téléviseur.
Ce code permet à l'appareil exécutant l'application de déterminer de manière sécurisée si l'utilisateur a accordé ou refusé l'accès. |
expires_in |
Durée, en secondes, pendant laquelle device_code et user_code sont valides. Si, pendant ce temps, l'utilisateur ne termine pas le flux d'autorisation et que votre appareil n'interroge pas également l'appareil pour récupérer des informations sur sa décision, vous devrez peut-être redémarrer ce processus à partir de l'étape 1. |
interval |
Durée d'attente, en secondes, de l'appareil entre les requêtes d'interrogation. 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, consultez l'étape 3. |
user_code |
Valeur sensible à la casse qui identifie auprès de Google les champs d'application auxquels l'application demande l'accès. Votre interface utilisateur demandera à l'utilisateur de saisir cette valeur sur un autre appareil doté de fonctionnalités d'entrée plus riches. Google utilise ensuite cette valeur pour afficher l'ensemble de champs d'application approprié lorsqu'il invite l'utilisateur à accorder l'accès à votre application. |
verification_url |
URL à laquelle l'utilisateur doit accéder, sur un appareil distinct, pour saisir user_code et accorder ou refuser l'accès à votre application. Votre interface utilisateur affichera également cette valeur. |
L'extrait de code suivant montre 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 de dépassement de quota
Si vos requêtes de code d'appareil ont dépassé le quota associé à votre ID client, vous recevrez une réponse 403 contenant 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 requêtes.
Étape 3: Affichez le code utilisateur
Affichez les verification_url
et user_code
obtenus à l'étape 2. Les 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 et de saisir le user_code
.
Concevez votre interface utilisateur (UI) en tenant compte des règles suivantes:
user_code
user_code
doit être affiché dans un champ pouvant accepter 15 caractères de taille "W". En d'autres termes, si vous pouvez afficher correctement le codeWWWWWWWWWWWWWWW
, votre UI est valide. Nous vous recommandons d'utiliser cette valeur de chaîne lorsque vous testez l'affichage deuser_code
dans votre UI.- L'élément
user_code
est sensible à la casse et ne doit en aucun cas être modifié, par exemple en changeant la casse ou en insérant d'autres caractères de mise en forme.
verification_url
- L'espace où vous affichez
verification_url
doit être suffisamment large pour gérer une chaîne d'URL de 40 caractères. - Vous ne devez en aucun cas modifier le
verification_url
, sauf pour éventuellement supprimer le schéma d'affichage. Si vous prévoyez de supprimer le schéma (par exemple,https://
) de l'URL pour des raisons d'affichage, assurez-vous que votre application peut gérer à la fois les varianteshttp
ethttps
.
- L'espace où vous affichez
Étape 4: Interrogez le serveur d'autorisation de Google
Étant donné que l'utilisateur utilisera un appareil distinct pour accéder à verification_url
et accorder (ou refuser) 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. Pour cette raison, l'appareil à l'origine de la demande doit interroger le serveur d'autorisation de Google pour déterminer quand l'utilisateur a répondu à la requête.
L'appareil demandeur 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 jusqu'à ce que les champs device_code
et user_code
obtenus à l'
étape 2 aient 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
. Elle contient les paramètres suivants:
Paramètres | |
---|---|
client_id |
ID client de votre application. Vous trouverez cette valeur dans API Console Credentials page. |
client_secret |
Code secret du client pour le client_id fourni. Vous trouverez cette valeur dans API Console
Credentials page. |
device_code |
Valeur device_code renvoyée par le serveur d'autorisation à l'étape 2. |
grant_type |
Définissez cette valeur sur urn:ietf:params:oauth:grant-type:device_code . |
Exemples
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
permettant d'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" \ https://oauth2.googleapis.com/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 à l'élément verification_url
que vous avez affiché à l'étape 3:
![Connectez un appareil en saisissant un code](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/images/oauth2/device/user-code.png?authuser=3&hl=fr)
Après avoir saisi l'user_code
et, s'il n'est pas déjà connecté à Google, un écran de consentement semblable à celui présenté ci-dessous s'affiche:
![Exemple d'écran de consentement pour un client d'appareil](https://developers-dot-devsite-v2-prod.appspot.com/static/identity/protocols/images/oauth2/device/approval.png?authuser=3&hl=fr)
Étape 6: Gérer les réponses aux requêtes d'interrogation
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 d'autorisation), 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 envoyé par votre application pour autoriser une requête API Google. |
expires_in |
Durée de vie restante du jeton d'accès en secondes. |
refresh_token |
Un 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 |
Niveaux d'accès accordés par access_token , exprimés sous la forme d'une liste de chaînes sensibles à la casse et séparées par des espaces. |
token_type |
Type de jeton renvoyé. Pour le moment, 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, "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 sur une longue période, elle peut utiliser le jeton d'actualisation pour obtenir un nouveau jeton d'accès. 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 affiche le 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 renvoie 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" }
Sondages trop fréquents
Si l'appareil envoie des requêtes d'interrogation trop fréquemment, 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 s'il manque des paramètres requis dans la requête d'interrogation ou si sa valeur de paramètre est incorrecte. Ces requêtes ont généralement un code d'état de réponse HTTP 400
(Bad Request
) ou 401
(Unauthorized
). Ces erreurs sont les suivantes:
Erreur | HTTP Status Code | Description |
---|---|---|
admin_policy_enforced |
400 |
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 savoir comment un administrateur peut restreindre l'accès aux champs d'application 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 quelles applications tierces et internes ont accès aux données Google Workspace. |
invalid_client |
401 |
Client OAuth introuvable. Par exemple, cette erreur se produit si la valeur du paramètre Le type de client OAuth est incorrect. Assurez-vous que le type d'application pour l'ID client est défini sur Téléviseurs et périphériques d'entrée limités. |
invalid_grant |
400 |
La valeur du paramètre code n'est pas valide, a déjà été revendiquée ou ne peut pas être analysée. |
unsupported_grant_type |
400 |
La valeur du paramètre grant_type n'est pas valide. |
org_internal |
403 |
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. Confirmez la configuration du type d'utilisateur pour votre application OAuth. |
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 Bearer
d'en-tête HTTP Authorization
. Dans la mesure du possible, il est préférable d'utiliser l'en-tête HTTP, car les chaînes de requête ont tendance à être visibles dans les journaux du serveur. Dans la plupart des cas, vous pouvez utiliser une bibliothèque cliente pour configurer vos appels aux API Google (par exemple, lorsque vous appelez l'API Drive Files).
Vous pouvez tester toutes les API Google et consulter leurs champs d'application sur OAuth 2.0 Playground.
Exemples de requêtes HTTP GET
Un appel au point de terminaison
drive.files
(API Drive Files) à l'aide de l'en-tête HTTP Authorization: Bearer
peut se présenter comme suit. Notez que vous devez spécifier votre propre jeton d'accès:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Voici un appel à la même API pour l'utilisateur authentifié à l'aide du paramètre de chaîne de requête access_token
:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
Exemples curl
Vous pouvez tester ces commandes avec l'application de ligne de commande curl
. Voici un exemple utilisant l'option d'en-tête HTTP (recommandée):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Vous pouvez également utiliser l'option 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 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 HTTPS POST
au serveur d'autorisation de 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 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é 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 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 atteindre ces limites, auquel cas les jetons d'actualisation plus anciens cesseront de fonctionner.
Révoquer un jeton
Dans certains cas, un utilisateur peut vouloir 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 à un site ou une application de la page "Sites et applications tiers ayant accès à votre compte" pour en savoir plus.
Une application peut également révoquer l'accès qui lui est accordé par programmation. La révocation automatisée est importante lorsqu'un utilisateur se désabonne ou supprime une application, ou lorsque 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 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}
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, le jeton d'actualisation sera également révoqué.
Si la révocation est traitée correctement, 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.
Champs d'application autorisés
Le flux OAuth 2.0 pour les appareils n'est compatible qu'avec les champs d'application suivants:
OpenID Connect, Google Sign-In
email
openid
profile
API Drive
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.file
API YouTube
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.readonly