OAuth 2.0 pour les applications TV et périphériques à saisie limitée

Ce document explique comment implémenter l'autorisation OAuth 2.0 pour accéder à l'API YouTube Data 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 dont les capacités de saisie sont limitées.

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 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 à des appareils individuels, il est supposé 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 lorsque celle-ci s'exécute en arrière-plan.

Alternatives

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 à des fonctionnalités d'entrée 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 un jeton d'identité JWT pour obtenir des informations de profil utilisateur de base, consultez Se connecter sur les téléviseurs et les appareils à saisie 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. Sélectionnez le type d'application TV et périphériques à entrée limitée.
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, 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 :

Consultez la liste des scopes 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 aux capacités d'entrée limitées, les utilisateurs doivent disposer d'un accès distinct à un appareil doté de capacités d'entrée plus riches pour effectuer ce flux d'autorisation. Le processus comprend les étapes suivantes :

1. Votre application envoie une requête au serveur d'autorisation de Google qui identifie les niveaux d'accès pour lesquels votre application demandera l'autorisation d'accès.
2. Le serveur répond avec plusieurs informations utilisées dans les étapes suivantes, telles qu'un code d'appareil et un code utilisateur.
3. Vous affichez les informations que l'utilisateur peut saisir sur un autre appareil 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 de saisie plus riches, lance un navigateur Web, accède à l'URL affichée à l'étape 3 et saisit un code é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 :

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 les appareils peuvent disposer, les exemples présentés dans ce document utilisent l'utilitaire de ligne de commande curl. Ces exemples doivent être faciles à porter sur différents langages et environnements d'exécution.

Étape 1 : Demandez les codes de l'appareil et de l'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, qui identifie votre application ainsi que les niveaux d'accès auxquels votre application 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 :

Exemples

L'extrait de code suivant montre 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=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

Cet exemple montre une commande curl permettant d'envoyer la même requête :

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Étape 2 : Traitez 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 demande est valide, votre réponse sera un objet JSON contenant les propriétés suivantes :

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 "Quota dépassé"

Si vos demandes 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'interruption 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 à l'utilisateur. Les deux valeurs peuvent contenir n'importe quel caractère imprimable du jeu de caractères US-ASCII. Le contenu que vous affichez à l'utilisateur doit lui indiquer d'accéder à verification_url sur un autre appareil et de saisir user_code.

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

• user_code
  • Le user_code doit être affiché dans un champ pouvant contenir 15 caractères de taille "W". En d'autres termes, si vous pouvez afficher correctement le code WWWWWWWWWWWWWWW, votre UI est valide. Nous vous recommandons d'utiliser cette valeur de chaîne lorsque vous testez la façon dont user_code s'affiche dans votre UI.
  • Le 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 contenir une chaîne d'URL de 40 caractères.
  • Vous ne devez en aucun cas modifier le verification_url, sauf pour supprimer éventuellement le schéma à des fins d'affichage. Si vous prévoyez de supprimer le schéma (par exemple, https://) de l'URL pour l'affichage, assurez-vous que votre application peut gérer les variantes http et https.

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

Étant donné que l'utilisateur utilisera un autre appareil pour accéder à verification_url et accorder (ou refuser) l'accès, l'appareil demandeur n'est pas automatiquement averti lorsque l'utilisateur répond à la demande d'accès. C'est pourquoi l'appareil demandeur doit interroger le serveur d'autorisation de Google pour déterminer quand l'utilisateur a répondu à la demande.

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 device_code et user_code obtenus à l' étape 2 aient expiré. Le interval renvoyé à l'étape 2 spécifie le délai 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 :

Exemples

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

Après avoir saisi user_code et, si ce n'est pas déjà fait, s'être connecté à Google, l'utilisateur voit un écran de consentement comme celui ci-dessous :

Étape 6 : Traiter les réponses aux demandes 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 pour le compte 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 :

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 pendant 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 comporte 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 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"
}

Interrogation trop fréquente

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 si la requête d'interrogation ne contient pas les paramètres requis ou si la valeur d'un 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). Voici quelques exemples d'erreurs :

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.

Niveaux d'accès autorisés

Le flux OAuth 2.0 pour les appareils n'est compatible qu'avec les champs d'application suivants :

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.