Google s'engage à promouvoir l'équité raciale pour les communautés noires. Regardez comment.

OAuth 2.0 pour les applications de télévision et de périphérique à entrée 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 des téléviseurs, des consoles de jeux et des imprimantes. Plus spécifiquement, ce flux est conçu pour les périphériques qui n'ont pas accès à un navigateur ou qui ont des capacités d'entrée 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 pourrait 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, on suppose que les applications ne peuvent pas garder de secrets. Ils peuvent accéder aux API Google lorsque l'utilisateur est présent sur l'application ou lorsque l'application s'exécute en arrière-plan.

Des alternatives

Si vous écrivez 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 capacité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.)

Conditions préalables

Activez 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:

  1. Open the API Library dans le Google API Console.
  2. If prompted, select a project, or create a new one.
  3. Le 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'est pas visible dans la liste, utilisez la recherche pour la trouver ou cliquez sur Afficher tout 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 informations d'identification d'autorisation

Toute application qui utilise OAuth 2.0 pour accéder aux API Google doit disposer d'informations d'identification d'autorisation qui identifient l'application sur le serveur OAuth 2.0 de Google. Les étapes suivantes expliquent comment créer des informations d'identification pour votre projet. Vos applications peuvent ensuite utiliser les informations d'identification 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 informations d'identification> ID client OAuth .
  3. Sélectionnez le type d'application Téléviseurs et Périphériques à entrée limitée .
  4. Nommez votre client OAuth 2.0 et cliquez sur Créer .

Identifier les étendues d'accès

Les étendues permettent à votre application de ne demander l'accès qu'aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler la quantité d'accès qu'ils accordent à votre application. Ainsi, il peut y avoir une relation inverse entre le nombre de portées demandées 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 étendues auxquelles votre application aura besoin d'une autorisation pour accéder.

Consultez la liste des étendues autorisées pour les applications ou les appareils installés.

Obtention de jetons d'accès OAuth 2.0

Même si votre application s'exécute sur un appareil avec des capacités d'entrée limitées, les utilisateurs doivent avoir un accès séparé à un appareil avec des capacités d'entrée plus riches pour terminer ce flux d'autorisation. Le flux comporte les étapes suivantes:

  1. Votre application envoie une demande 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, telles qu'un code de périphérique et un code d'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 bascule vers un appareil doté de capacités de saisie plus riches, lance un navigateur Web, accède à l'URL affichée à l'étape 3 et entre 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 demande d'interrogation contient les jetons dont votre application a besoin pour autoriser les demandes 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 appareil distinct doté d'un navigateur

Les sections suivantes expliquent ces étapes en détail. Compte tenu de la gamme de capacités et d'environnements d'exécution que les périphériques peuvent avoir, les exemples présentés dans ce document utilisent l'utilitaire de ligne de commande curl . Ces exemples doivent être faciles à porter dans différents langages et environnements d'exécution.

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

Dans cette étape, votre appareil envoie une requête HTTP POST au serveur d'autorisation de Google, à l' https://oauth2.googleapis.com/device/code , qui identifie votre application ainsi que les portées d'accès auxquelles votre application souhaite accéder sur le site de l'utilisateur. au nom de. Vous devez récupérer cette URL à partir du document Discovery à 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

L'ID client de votre application. Vous pouvez trouver cette valeur dans le API Console Credentials page.

scope Obligatoire

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

Les étendues permettent à votre application de ne demander l'accès qu'aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler la quantité d'accès qu'ils accordent à votre application. Ainsi, il existe une relation inverse entre le nombre de portées demandées et la probabilité d'obtenir le consentement de l'utilisateur.

Exemples

L'extrait de code suivant montre un exemple de demande:

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 pour 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 renverra l'une des réponses suivantes:

Réponse réussie

Si la demande est valide, votre réponse sera un objet JSON contenant les propriétés suivantes:

Propriétés
device_code Une valeur que Google attribue de manière unique pour identifier l'appareil qui exécute l'application demandant l'autorisation. L'utilisateur autorisera cet appareil à partir d'un autre appareil doté de capacités d'entrée plus riches. Par exemple, un utilisateur peut utiliser un ordinateur portable ou un téléphone portable pour autoriser une application s'exécutant 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 en toute sécurité si l'utilisateur a accordé ou refusé l'accès.

expires_in Durée, en secondes, device_code laquelle le device_code et le user_code sont valides. Si, pendant ce temps, l'utilisateur ne termine pas le processus d'autorisation et que votre appareil n'interroge pas également pour récupérer des informations sur la décision de l'utilisateur, vous devrez peut-être redémarrer ce processus à partir de l'étape 1.
interval La durée, en secondes, pendant laquelle votre appareil doit attendre entre les demandes d'interrogation. Par exemple, si la valeur est 5 , votre appareil doit envoyer une demande d'interrogation au serveur d'autorisation de Google toutes les cinq secondes. Voir l' étape 3 pour plus de détails.
user_code Valeur sensible à la casse qui identifie à Google les champs d'application auxquels l'application demande l'accès. Votre interface utilisateur demandera à l'utilisateur de saisir cette valeur sur un appareil distinct avec des capacités d'entrée plus riches. Google utilise ensuite la valeur pour afficher l'ensemble correct de portées lorsqu'il invite l'utilisateur à accorder l'accès à votre application.
verification_url URL vers laquelle l'utilisateur doit accéder, sur un appareil distinct, pour entrer le 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 au dépassement du quota

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 demandes.

Étape 3: afficher le code utilisateur

Affichez l' user_code verification_url et le 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 de naviguer vers l' user_code 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
    • Le user_code doit être affiché dans un champ pouvant gérer 15 caractères de taille «W». En d'autres termes, si vous pouvez afficher le code WWWWWWWWWWWWWWW correctement, votre interface utilisateur est valide et nous vous recommandons d'utiliser cette valeur de chaîne lors du test de la façon dont le user_code s'affiche dans votre interface utilisateur.
    • 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 formatage.
  • verification_url
    • L'espace dans lequel vous affichez l'URL de verification_url doit être suffisamment large pour gérer une chaîne URL de 40 caractères.
    • Vous ne devez en aucun cas modifier l’ verification_url de verification_url , sauf pour supprimer éventuellement 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 variantes http et https .

Étape 4: Sondez 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 demandeur n'est pas automatiquement averti lorsque l'utilisateur répond à la demande d'accès. Pour cette raison, l'appareil demandeur doit interroger le serveur d'autorisation de Google pour déterminer quand l'utilisateur a répondu à la demande.

Le dispositif demandeur doit continuer à envoyer des demandes 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 le device_code et user_code obtenus à l' étape 2 aient expiré. L' interval renvoyé à l'étape 2 spécifie la durée, en secondes, à attendre entre les demandes.

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 L'ID client de votre application. Vous pouvez trouver cette valeur dans le API Console Credentials page.
client_secret Le secret client pour le client_id fourni. Vous pouvez trouver cette valeur dans le API Console Credentials 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 .

Exemples

L'extrait de code suivant montre un exemple de demande:

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 similaire à ce que les utilisateurs voient lorsqu'ils accèdent à l' verification_url que vous avez affichée à l' étape 3 :

Connectez un appareil en entrant un code

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

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

Étape 6: gérer les réponses aux demandes d'interrogation

Le serveur d'autorisation de Google répond à chaque demande 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 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:

Des champs
access_token Jeton que votre application envoie pour autoriser une demande d'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 portées d'accès accordées par access_token exprimées sous la forme d'une liste de chaînes délimitées par des espaces et sensibles à la casse.
token_type Le type de jeton renvoyé. À ce stade, 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 au périphérique, la réponse du serveur a 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 (condition Precondition Required ). La réponse contient l'erreur suivante:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Sondage trop fréquemment

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 demande d'interrogation ne contient aucun paramètre requis ou a une valeur de paramètre incorrecte. Ces demandes ont généralement un code d'état de réponse HTTP 400 ( Bad Request ) ou 401 ( Unauthorized ). Ces erreurs incluent:

Erreur Code d'état HTTP La 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 de code n'est pas valide.
unsupported_grant_type 400 La valeur du paramètre grant_type n'est pas valide.

Appeler les API Google

Une fois que votre application a obtenu un jeton d'accès, vous pouvez utiliser le jeton pour passer des appels à une API Google au nom d'un compte utilisateur donné si la ou les étendues d'accès requises par l'API ont été accordées. Pour ce faire, incluez le jeton d'accès dans une requête à l'API en incluant un paramètre de requête access_token ou une valeur de Bearer tête HTTP d' 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, lors de l' appel de l'API Drive Files ).

Vous pouvez essayer toutes les API Google et voir leurs portées sur le terrain de jeu OAuth 2.0 .

Exemples HTTP GET

Un appel au drive.files terminaison drive.files (l'API Drive Files) à 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 /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 de 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 (de préférence):

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

Ou, alternativement, 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 périodiquement et deviennent des informations d'identification non valides pour une demande d'API associée. Vous pouvez actualiser un jeton d'accès sans demander l'autorisation à l'utilisateur (y compris lorsque l'utilisateur n'est pas présent) si vous avez demandé un accès hors connexion aux étendues associées au jeton.

Pour actualiser un jeton d'accès, votre application envoie une POST HTTPS POST au serveur d'autorisation de Google ( https://oauth2.googleapis.com/token ) qui inclut les paramètres suivants:

Des champs
client_id L'ID client obtenu à partir du API Console.
client_secret Le secret client obtenu à partir du 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 Le jeton d'actualisation renvoyé par l'échange de code d'autorisation.

L'extrait de code suivant montre un exemple de demande:

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 qui contient 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 qu'il existe des limites sur le 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 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 donné à une application. Un utilisateur peut révoquer l'accès en visitant les paramètres du compte . Pour plus d'informations, reportez-vous à la section Supprimer l'accès au site ou aux applications des sites et applications tiers ayant accès au document d'assistance de votre compte .

Il est également possible pour une application de révoquer par programme l'accès qui lui est donné. La révocation par programme est importante dans les cas où un utilisateur se désabonne, supprime une application ou les ressources API requises par une application ont considérablement changé. En d'autres termes, une partie du processus de suppression peut inclure une demande d'API pour s'assurer que les autorisations précédemment accordées à l'application sont supprimées.

Pour révoquer un jeton par programme, 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 a un jeton d'actualisation correspondant, le jeton d'actualisation 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 . Pour les conditions d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

Portées autorisées

Le flux OAuth 2.0 pour les appareils est pris en charge uniquement pour les étendues suivantes:

OpenID Connect , connexion à Google

  • 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