OAuth 2.0 pour les applications TV et appareils à saisie limitée

Ce document explique comment implémenter l'autorisation d'accès OAuth 2.0 via des applications exécutées sur des appareils tels que des téléviseurs, des consoles de jeu 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 fonctionnalités de saisie 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 à des appareils individuels, on suppose qu'elles ne peuvent pas garder de secrets. Elles peuvent accéder aux API Google lorsque l'utilisateur présentes 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), ayant accès au navigateur et à toutes les entrées utilisez le flux OAuth 2.0 pour appareils mobiles et les applications de bureau. Vous devez utiliser ce flux même si votre application est une sans interface graphique.)

Si vous souhaitez uniquement connecter les utilisateurs avec leur compte Google et utiliser Jeton d'ID JWT permettant d'obtenir des informations de base sur le profil utilisateur consultez la section Connexion sur les téléviseurs et les 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 :

1. Open the API Library dans le Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library répertorie toutes les API disponibles, regroupées par famille de produits 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 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 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 champs d'application permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le nombre d'accès qu'ils accordent à votre application. Par conséquent, il peut exister 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 auxquelles votre application a besoin d'une autorisation d'accès.

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

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 aux fonctionnalités de saisie plus riches pour effectuer ce flux d'autorisation. Le flux se compose des étapes suivantes :

1. Votre application envoie une requête au serveur d'autorisation de Google qui identifie les champs d'application auxquels votre application demandera l'autorisation d'accéder.
2. Le serveur répond avec plusieurs informations utilisées dans les étapes suivantes, comme un code de l'appareil et un code utilisateur.
3. Vous affichez des 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 à un appareil avec des 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. La peut alors accorder (ou refuser) l'accès à votre application.
6. La réponse suivante à votre demande d'interrogation contient les jetons que votre application doit autoriser. des 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 des capacités et de l'environnement d'exécution que peuvent comporter les appareils, les exemples présentés dans ce document utilisent l'curl de ligne de commande. Ces exemples doivent être faciles à transférer dans différents langages et environnements d'exécution.

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

À cette étape, votre appareil envoie une requête POST HTTP au serveur d'autorisation de Google, à l'adresse https://oauth2.googleapis.com/device/code, qui identifie votre application ainsi que les portées d'accès auxquelles 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 la requête HTTP suivante paramètres:

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érer 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 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 de dépassement de quota

Si vos requêtes de code d'appareil ont dépassé le quota associé à votre ID client, vous devrez recevez 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 afin de 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 présentez à l'utilisateur doit lui demander d'accéder au verification_url sur un appareil distinct et saisissez le user_code.

Concevez votre interface utilisateur en tenant compte des règles suivantes:

• user_code
  • L'élément user_code doit être affiché dans un champ pouvant gérer 15 "W". taille [size] caractères. 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.
  • La valeur user_code est sensible à la casse et ne doit pas être modifiée de quelque manière que ce soit, par exemple en modifiant la casse ou en insérant d'autres caractères de mise en forme.
• verification_url
  • L'espace dans lequel vous affichez le 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 verification_url, sauf pour supprimer éventuellement le schéma à afficher. Si vous envisagez de supprimer le schéma (par exemple, https://) dans l'URL pour des raisons d'affichage, assurez-vous que votre application à la fois http et https.

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

Étant donné que l'utilisateur utilisera un appareil distinct pour accéder à verification_url et d'accorder (ou de 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 requête 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 device_code et user_code obtenu en de l'étape 2 ont expiré. La valeur interval renvoyée à l'étape 2 indique la quantité de le temps d'attente, exprimé en secondes, entre les requêtes.

L'URL du point de terminaison à interroger est https://oauth2.googleapis.com/token. La demande d'interrogation contient les paramètres suivants:

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

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

É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'un des éléments suivants : réponses:

Accès autorisé

Si l'utilisateur a autorisé l'accès à l'appareil (en cliquant sur Allow sur l'écran d'autorisation), alors 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 dans 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 sur une longue période il peut utiliser le jeton d'actualisation pour obtenir un nouvel accès à partir d'un 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 une réponse 403. Code d'état de la réponse HTTP (Forbidden). La réponse contient les éléments suivants : erreur:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Autres erreurs

Le serveur d'autorisation renvoie également des erreurs s'il manque des éléments obligatoires dans la demande d'interrogation. ou contient une valeur de paramètre incorrecte. Ces requêtes ont généralement un code d'état de réponse HTTP 400 (Bad Request) ou 401 (Unauthorized). Voici quelques-unes de ces 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 vers pour le compte d'un service compte utilisateur si 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 adressée à l'API en incluant une requête access_token ou une valeur Bearer d'en-tête HTTP Authorization. Lorsque c'est 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 Drive Files).

Vous pouvez essayer toutes les API Google et consulter leurs champs d'application à la OAuth 2.0 Playground.

Exemples de requêtes HTTP GET

Un appel à la fonction <ph type="x-smartling-placeholder"></ph> drive.files (API Drive Files) via le protocole 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 de access_token. paramètre de chaîne de requête:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

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é):

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

Vous pouvez également utiliser l'option de 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. Toi peut actualiser un jeton d'accès sans demander l'autorisation à l'utilisateur (y compris lorsqu'il est absente) 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 POST HTTPS au serveur d'autorisation (https://oauth2.googleapis.com/token) de Google, 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 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 qui seront é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 rencontrer 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 à la page Paramètres de compte. Pour en savoir plus, consultez la section Supprimer l'accès d'une application ou d'un site du document d'aide "Applications et sites tiers ayant accès à votre compte".

Une application peut également révoquer de manière programmatique l'accès qui lui a été accordé. La révocation par programmation est importante lorsqu'un utilisateur se désabonne, supprime 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 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 le 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 par 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 :