OAuth 2.0 pour les applications pour téléviseurs et périphériques à saisie limitée

?

Ce document explique comment mettre en œuvre l'autorisation OAuth 2.0 pour accéder aux API Google via des applications exécutées sur des appareils tels que les téléviseurs, les consoles de jeu et les imprimantes. Plus précisément, cette procédure est conçue pour les appareils qui n'ont pas accès à un navigateur ou dont les fonctionnalités d'entrée sont 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 considérons qu'elles ne peuvent pas garder les secrets. Il peut accéder aux API Google lorsque l'utilisateur est présent dans l'application ou lorsque celle-ci s'exécute 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 à des fonctionnalités de saisie complètes, utilisez le flux OAuth 2.0 pour les applications mobiles et de bureau. (Utilisez ce flux même si votre application est un outil de ligne de commande sans interface graphique.)

Si vous souhaitez uniquement connecter les utilisateurs à 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 les API Google doit les activer 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. L'API API Library répertorie toutes les API disponibles, regroupées par famille et par popularité. Si l'API que vous souhaitez activer n'apparaît pas dans la liste, utilisez la fonctionnalité de recherche pour la trouver ou cliquez sur Tout afficher dans la famille de produits à laquelle elle appartient.
  4. Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
  5. If prompted, enable billing.
  6. 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.

  1. Go to the Credentials page.
  2. Cliquez sur Créer des identifiants > ID client OAuth.
  3. Sélectionnez le type d'application Téléviseurs et périphériques d'entrée limités.
  4. Nommez 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 demander uniquement l'accès aux ressources dont elle a besoin. Elles permettent également aux utilisateurs de contrôler le niveau d'accès qu'ils accordent à 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 champs d'application pour lesquels votre application aura besoin d'une autorisation.

Consultez la liste des champs d'application autorisés pour les applications ou appareils installés.

Obtenir des jetons d'accès OAuth 2.0

Bien que votre application s'exécute sur un appareil disposant de capacités d'entrée 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 flux comprend les étapes suivantes:

  1. Votre application envoie au serveur d'autorisation de Google une requête identifiant les champs d'application auxquels elle demande l'autorisation d'accéder.
  2. Le serveur répond avec plusieurs informations utilisées lors des étapes suivantes, telles qu'un code d'appareil et un code utilisateur.
  3. Vous affichez les informations que l'utilisateur peut saisir sur un appareil distinct pour autoriser votre application.
  4. Votre application commence à interroger le serveur d'autorisation de Google pour déterminer si l'utilisateur a autorisé votre application.
  5. L'utilisateur passe sur un appareil doté de fonctionnalités d'entrée 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.
  6. La réponse suivante à votre requête 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 pas de jetons.)

L'image ci-dessous illustre ce processus:

L'utilisateur se connecte sur un autre appareil doté d'un navigateur

Les sections suivantes décrivent ces étapes en détail. Compte tenu de la gamme de fonctionnalités et d'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 être faciles à transférer vers différents langages et environnements d'exécution.

Étape 1: Demandez les codes d'appareil et d'utilisateur

Au cours de cette étape, votre appareil envoie au serveur d'autorisation de Google (https://oauth2.googleapis.com/device/code) une requête HTTP POST qui identifie votre application ainsi que les champs d'application d'accès auxquels elle souhaite accéder au nom 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 l' Credentials page API Console.

scope Obligatoire

Liste de champs d'application délimités par des espaces qui identifient les ressources auxquelles votre application pourrait accéder au nom de l'utilisateur. Ces valeurs informent l'écran de consentement que Google affiche à l'utilisateur. Consultez la liste des champs d'application autorisés pour les applications ou appareils installés.

Les champs d'application permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin. Elles permettent également aux utilisateurs de contrôler le niveau d'accès accordé à 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.

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, votre réponse est un objet JSON contenant les propriétés suivantes:

Propriétés
device_code Valeur que Google attribue de manière unique pour identifier l'appareil qui exécute l'application qui demande 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 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é l'accès.

expires_in Durée, en secondes, de validité des valeurs device_code et user_code. Dans ce cas, si l'utilisateur n'effectue pas le flux d'autorisation et que votre appareil n'interroge pas le système pour récupérer les informations sur sa décision, vous devrez peut-être recommencer le processus de l'étape 1.
interval Durée, en secondes, pendant laquelle votre appareil doit attendre entre deux requêtes 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, consultez l'étape 3.
user_code Valeur sensible à la casse qui identifie pour Google les champs d'application pour lesquels l'application demande l'accès. Votre interface utilisateur demandera à l'utilisateur de saisir cette valeur sur un appareil distinct doté de fonctionnalités d'entrée plus riches. Google utilise ensuite cette valeur pour afficher le bon ensemble de champs d'application 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 présente 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 dépassement du 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 sur l'utilisateur les informations verification_url et user_code obtenues à 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 proposez à l'utilisateur doit lui demander d'accéder à verification_url sur un autre appareil, puis de saisir user_code.

Concevez votre interface utilisateur en gardant à l'esprit les règles suivantes:

  • user_code
    • Le champ user_code doit être affiché dans un champ pouvant accepter 15 caractères de taille "W". En d'autres termes, si vous pouvez afficher le code WWWWWWWWWWWWWWW correctement, votre interface utilisateur est valide. Nous vous recommandons d'utiliser cette valeur de chaîne lorsque vous testez l'affichage de user_code dans votre interface utilisateur.
    • La user_code est sensible à la casse et ne doit pas être modifiée d'une quelconque manière, par exemple en changeant la casse ou en insérant d'autres caractères de mise en forme.
  • verification_url
    • L'espace dans lequel vous affichez verification_url doit être suffisamment large pour gérer une chaîne d'URL de 40 caractères.
    • Vous ne devez pas modifier le verification_url de quelque manière que ce soit, sauf si vous souhaitez supprimer le schéma pour l'affichage. Si vous prévoyez de supprimer du schéma de l'URL (par exemple, https://) pour des raisons d'affichage, assurez-vous que votre application peut gérer à la fois les variantes http et https.

Étape 4: Interrogez le serveur d'autorisation de Google

Étant donné que l'utilisateur utilise 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 à 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 de sondage contient les paramètres suivants:

Paramètres
client_id ID client de votre application. Vous trouverez cette valeur dans l' Credentials page API Console.
client_secret Code secret du client pour le client_id fourni. Vous trouverez cette valeur dans l' Credentials page API Console.
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.

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'verification_url que vous avez affiché à l'étape 3:

Connecter un appareil en saisissant un code

Après avoir saisi user_code et s'il n'est pas déjà connecté à Google, l'utilisateur voit un écran de consentement semblable à celui présenté ci-dessous:

Exemple d'écran de consentement pour un client d'appareil

Étape 6: Gérez 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 de consentement), la réponse contient un jeton d'accès et un jeton d'actualisation. Les 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 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 Les niveaux d'accès accordés par access_token sont exprimés sous la forme d'une liste de chaînes sensibles à la casse, séparées par un espace.
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 présente 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 en obtenir un nouveau. 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 la réponse HTTP 403 (Forbidden). Elle 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 trop souvent des requêtes d'interrogation, le serveur renvoie le code d'état de la 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 ou dans une valeur incorrecte pour la requête d'interrogation. 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 niveaux d'accès demandés en raison des règles de leur administrateur Google Workspace. Consultez l'article d'aide Administrateur Google Workspace Contrôler quelles applications tierces et internes ont accès aux données Google Workspace pour savoir comment un administrateur peut limiter l'accès aux habilitations tant que l'accès n'est pas explicitement accordé à votre ID client OAuth.
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.

Le type de client OAuth est incorrect. Assurez-vous que le type d'application pour l'ID client est défini sur TVs 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 figurant dans la requête fait partie d'un projet limitant l'accès aux comptes Google d'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 le ou les champs d'application 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 Authorization d'en-tête HTTP 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 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 essayer toutes les API Google et consulter leurs habilitations sur OAuth 2.0 Playground.

Exemples HTTP GET

Un appel vers le point de terminaison drive.files (API Drive Files) avec 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 (recommandé):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Vous pouvez également utiliser le 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 la page 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 de 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 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 générés 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 le 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 anciens jetons d'actualisation cesseront de fonctionner.

Révoquer un jeton

Dans certains cas, l'utilisateur peut révoquer l'accès accordé à une application. Il peut révoquer l'accès dans les paramètres du compte. Pour en savoir plus, consultez la section Supprimer l'accès au site ou à l'application des sites et applications tiers ayant accès à votre compte.

Une application peut également révoquer programmatiquement l'accès qui lui est attribué. La révocation programmatique est importante dans les cas où un utilisateur se désabonne, supprime une application ou a changé de manière significative les ressources API requises par une application. 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 programmatiquement un jeton, 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, il est é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.

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

  • 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