Faire une requête à votre API au moyen du flux d’autorisation d’appareil

Découvrez comment faire une requête à votre API à partir d’un appareil à capacité de saisie limitée au moyen du flux d’autorisation d’appareil.

Ce tutoriel vous aidera à appeler votre propre API à partir d’un appareil à saisie limitée à l’aide du flux d’autorisation d’appareil. Si vous voulez comprendre comment ce flux fonctionne et pourquoi vous devriez l’utiliser, consultez flux d’autorisation d’appareil.

Auth0 permet à votre application d’implémenter facilement le Device Authorization flow à l’aide de ce qui suit :

• Authentication API : poursuivez votre lecture pour apprendre à appeler notre API directement. Pour une expérience interactive, consultez Device Flow Playground.

​

Prérequis

Avant de commencer ce tutoriel :

• Vérifiez les limites (ci-dessous) afin de vous assurer que le Device Authorization Flow convient à votre mise en œuvre.

• Enregistrez l’application auprès d’Auth0.

  • Sélectionnez Native comme Type d’application.
  • Au besoin, définissez les Origines Web autorisées. Vous pouvez l’utiliser pour autoriser localhost comme origine en développement local, ou pour définir une origine autorisée pour un logiciel de téléviseur précis dont l’architecture est soumise à CORS (p. ex., HTML5 + JS). La plupart des applications n’utiliseront pas ce paramètre.
  • Assurez-vous que la bascule OIDC Conformant est activée. Ce paramètre se trouve dans le Dashboard, sous Applications > Application > Advanced Settings > OAuth.
  • Assurez-vous que les Types d’octroi de l’application comprennent Device Code. Pour savoir comment faire, consultez Mettre à jour les type d’octroi.
  • Si vous voulez que votre application puisse utiliser des jetons d’actualisation, assurez-vous que ses Types d’octroi comprennent jeton d’actualisation. Pour savoir comment faire, consultez Mettre à jour les type d’octroi. Pour en savoir plus sur les jetons d’actualisation, consultez jetons d’actualisation.

• Configurez et activez au moins une connection pour l’application : Database connections, Social connections

• Enregistrez votre API auprès d’Auth0

  • Si vous voulez que votre API reçoive des jetons d’actualisation afin de pouvoir obtenir de nouveaux jetons lorsque les précédents expirent, activez Allow Offline Access. Pour en savoir plus sur les jetons d’actualisation, consultez jetons d’actualisation.

• Configurez les paramètres du user code de l’appareil pour définir le jeu de caractères, le format et la longueur de votre user code généré aléatoirement.

​

Étapes

1. Demander un code d’appareil (flux de l’appareil) : Demandez un code d’appareil que l’utilisateur pourra utiliser pour autoriser l’appareil.
2. Demander l’activation de l’appareil (flux de l’appareil) : Demandez à l’utilisateur d’autoriser l’appareil à l’aide de son ordinateur portable ou de son téléphone intelligent.
3. Demander des jetons (flux de l’appareil) : Interrogez le point de terminaison des jetons pour demander un jeton.
4. Autoriser l’utilisateur (flux du navigateur) : L’utilisateur autorise l’appareil afin que celui-ci puisse recevoir des jetons.
5. Recevoir des jetons (flux de l’appareil) : Une fois que l’utilisateur a autorisé l’appareil avec succès, recevez les jetons.
6. Appeler l’API (flux de l’appareil) : Utilisez le jeton d’accès récupéré pour appeler votre API.
7. Actualiser les jetons (flux de l’appareil) : Utilisez un jeton d’actualisation pour demander de nouveaux jetons lorsque les jetons existants expirent.

Facultatif : Explorer des exemples de cas d’utilisation.

Facultatif : Dépannage.

​

Demander un code d’appareil

Une fois que l’utilisateur a démarré son application de l’appareil et souhaite autoriser l’appareil, vous devrez obtenir un code d’appareil. Lorsque l’utilisateur ouvre sa session sur son appareil avec navigateur, ce code sera associé à cette session.

Pour obtenir le code d’appareil, votre application doit faire une requête à l’URL du code d’appareil, en incluant le Client ID.

​

Exemple de requête POST à l’URL du code d’appareil

Paramètres du code d’appareil

Notez que lorsque vous demandez un code d’appareil pour effectuer une requête à une API personnalisée, vous :

• devez inclure un paramètre audience
• pouvez inclure des scopes supplémentaires pris en charge par l’API cible

Si votre application veut seulement un jeton d’accès pour récupérer des informations sur l’utilisateur authentifié, aucun paramètre audience n’est requis.

Nom du paramètre	Description
client_id	Le Client ID de votre application. Vous trouverez cette valeur dans les paramètres de l’application.
scope	Les scopes pour lesquels vous souhaitez demander une autorisation. Ils doivent être séparés par un espace. Vous pouvez demander n’importe lequel des scopes OIDC standard concernant les utilisateurs, comme profile et email, des custom claims conformes à un format namespaced, ou tout scope pris en charge par l’API cible (par ex. : read:contacts). Incluez openid pour obtenir un ID Token ou pour pouvoir utiliser le point de terminaison /userinfo afin de récupérer les informations de profil de l’utilisateur. Incluez offline_access pour obtenir un jeton d’actualisation (assurez-vous que le champ Allow Offline Access est activé dans les API Settings). Notez que cette valeur doit être encodée dans l’URL.
audience	L’identifiant unique de l’API à laquelle votre application veut accéder. Utilisez la valeur Identifier dans l’onglet Settings de l’API que vous avez créée dans le cadre des prérequis de ce tutoriel. Notez que cette valeur doit être encodée dans l’URL.

​

Réponse de code d’appareil

Si tout se passe bien, vous recevrez une réponse HTTP 200 dont la charge utile contient device_code, user_code, verification_uri ainsi que les valeurs expires_in, interval et verification_uri_complete :

{
  "device_code": "Ag_EE...ko1p",
  "user_code": "QTZL-MCBW",
  "verification_uri": "https://accounts.acmetest.org/activate",
  "verification_uri_complete": "https://accounts.acmetest.org/activate?user_code=QTZL-MCBW",
  "expires_in": 900,
  "interval": 5
}

• device_code est le code unique de l’appareil. Lorsque l’utilisateur accède à verification_uri depuis son navigateur sur l’appareil, ce code est associé à sa session.
• user_code contient le code qui doit être saisi à verification_uri pour autoriser l’appareil.
• verification_uri contient l’URL que l’utilisateur doit ouvrir pour autoriser l’appareil.
• verification_uri_complete contient l’URL complète que l’utilisateur doit ouvrir pour autoriser l’appareil. Cela permet à votre application d’inclure le user_code dans l’URL, si vous le souhaitez.
• expires_in indique la durée de validité (en secondes) du device_code et du user_code.
• interval indique l’intervalle (en secondes) auquel l’application doit interroger l’URL du jeton pour demander un jeton.

Vous pouvez configurer le jeu de caractères, le format et la longueur de votre code utilisateur généré aléatoirement dans les paramètres de votre tenant.

Pour prévenir les attaques par force brute, nous appliquons les limites suivantes à user_code :

Longueur minimale :

• Lettres BASE20 : 8 caractères
• Chiffres : 9 caractères

Longueur maximale :

• 20 caractères (y compris les traits d’union et les espaces, qui peuvent être ajoutés comme séparateurs pour en faciliter la lecture)

Durée d’expiration :

• 15 minutes

​

Demander l’activation de l’appareil

Une fois que vous avez reçu un device_code et un user_code, vous devez demander à l’utilisateur de se rendre à l’verification_uri sur son ordinateur portable ou son téléphone, puis d’entrer le user_code :

Le device_code n’est pas destiné directement à l’utilisateur et ne devrait pas être affiché pendant l’interaction afin d’éviter toute confusion.

Si vous créez un CLI, vous pouvez ignorer cette étape et ouvrir immédiatement le navigateur avec verification_uri_complete.

​

Demander des jetons

Pendant que vous attendez que l’utilisateur active l’appareil, commencez à interroger périodiquement l’URL de jeton pour demander un jeton d’accès. En utilisant l’intervalle de polling extrait (interval) à l’étape précédente, vous devrez envoyer une requête POST à l’URL de jeton avec le device_code.

Pour éviter les erreurs dues à la latence du réseau, vous devriez commencer à compter chaque intervalle après avoir reçu la réponse à la dernière requête de polling.

​

Exemple de requête POST à l’URL du jeton

Paramètres de la demande de jeton

Nom du paramètre	Description
grant_type	Définissez cette valeur sur « urn:ietf:params:oauth:grant-type:device_code ». Il s’agit d’un type d’autorisation d’extension (tel que défini à la section 4.5 de la RFC6749). Notez que cette valeur doit être encodée dans l’URL.
device_code	Le device_code récupéré à l’étape précédente de ce tutoriel.
client_id	Le Client ID de votre application. Vous trouverez cette valeur dans les paramètres de l’application.

​

Réponses de jeton

Pendant que vous attendez que l’utilisateur autorise l’appareil, il se peut que vous receviez quelques réponses HTTP 4xx différentes :

Autorisation en attente

Vous verrez cette erreur en attendant que l’utilisateur passe à l’action. Continuez à interroger le point de terminaison selon l’intervalle suggéré obtenu à l’étape précédente de ce tutoriel.

HTTP/1.1 403 Forbidden
{
  "error": "authorization_pending",
  "error_description": "..."
}

Ralentissez

Vous effectuez des vérifications trop fréquemment. Ralentissez et utilisez l’intervalle suggéré obtenu à l’étape précédente de ce tutoriel. Pour éviter de recevoir cette erreur en raison de la latence du réseau, vous devriez commencer à compter chaque intervalle après avoir reçu la réponse à la dernière requête de vérification.

HTTP/1.1 429 Too Many Requests
{
  "error": "slow_down",
  "error_description": "..."
}

Jeton expiré

L’utilisateur n’a pas autorisé l’appareil assez rapidement, donc le device_code a expiré. Votre application doit informer l’utilisateur que le flux a expiré et lui demander de le relancer.

L’erreur expired_token ne sera renvoyée qu’une seule fois; par la suite, invalid_grant sera renvoyée. Votre appareil doit cesser d’interroger le point de terminaison.

HTTP/1.1 403 Bad Request
{ 
  "error": "expired_token",
  "error_description": "..."
}

Accès refusé

Enfin, si l’accès vous est refusé, vous recevrez :

HTTP/1.1 403 Forbidden
{
  "error": "access_denied",
  "error_description": "..."
}

Cela peut se produire pour diverses raisons, notamment :

• l’utilisateur a refusé d’autoriser l’appareil
• le serveur d’autorisation a refusé la transaction
• une règle configurée a refusé l’accès (Pour en savoir plus, consultez Auth0 Rules.)

​

Autoriser l’utilisateur

L’utilisateur balaiera le code QR ou ouvrira la page d’activation et saisira le code utilisateur :

Une page de confirmation s’affichera pour demander à l’utilisateur de confirmer qu’il s’agit du bon appareil :

L’utilisateur terminera la transaction en se connectant. Cette étape peut inclure un ou plusieurs des processus suivants :

• Authentification de l’utilisateur ;
• Redirection de l’utilisateur vers un fournisseur d’identité pour effectuer l’authentification ;
• Vérification des sessions SSO actives ;
• Obtention du consentement de l’utilisateur pour l’appareil, sauf si ce consentement a déjà été accordé.

Une fois l’authentification réussie et le consentement accordé, l’invite de confirmation s’affichera :

À ce stade, l’utilisateur s’est authentifié et l’appareil a été autorisé.

​

Recevoir des jetons

Pendant que l’utilisateur s’authentifie et autorise l’appareil, l’application de l’appareil continue d’interroger l’URL du jeton pour demander un jeton d’accès.

Une fois que l’utilisateur a bien autorisé l’appareil, vous recevrez une réponse HTTP 200 avec une charge utile contenant les valeurs access_token, refresh_token (facultatif), id_token (facultatif), token_type et expires_in :

{
  "access_token":"eyJz93a...k4laUWw",
  "refresh_token":"GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type":"Bearer",
  "expires_in":86400
}

Validez vos jetons avant de les enregistrer. Pour savoir comment faire, consultez valider le jeton d’identité et Valider les jetons d’accès.

Les jetons d’accès servent à appeler le point de terminaison /userinfo de l’API d’authentification Auth0 ou une autre API. (Pour en savoir plus sur les jetons d’accès, consultez Jetons d’accès.) Vous ne pourrez utiliser le jeton d’accès pour appeler /userinfo que si vous avez inclus la portée openid. Si vous appelez votre propre API, la première chose qu’elle devra faire sera de vérifier le jeton d’accès.

Jetons d’identité contiennent des renseignements sur l’utilisateur qui doivent être décodés et extraits. (Pour en savoir plus sur les jetons d’identité, consultez Jetons d’identité.) Le id_token ne sera présent dans la réponse que si vous avez inclus la portée openid.

Jetons d’actualisation servent à obtenir un nouveau jeton d’accès ou un nouveau jeton d’identité après l’expiration du précédent. (Pour en savoir plus sur les jetons d’actualisation, consultez Jetons d’actualisation.) Le refresh_token ne sera présent dans la réponse que si vous avez inclus la portée offline_access et activé Autoriser l’accès hors ligne pour votre API dans le Dashboard.

Les jetons d’actualisation doivent être stockés de façon sécuritaire, car ils permettent à un utilisateur de rester authentifié essentiellement indéfiniment.

​

Effectuer une requête à votre API

Pour effectuer une requête à votre API, l’application doit transmettre le jeton d’accès récupéré comme jeton Bearer dans l’en-tête Authorization de votre requête HTTP.

​

Jetons d’actualisation

Vous avez déjà reçu un jeton d’actualisation si vous avez suivi ce tutoriel et effectué les étapes suivantes :

• configuré votre API pour autoriser l’accès hors ligne
• inclus la portée offline_access lorsque vous avez lancé la requête d’authentification par l’intermédiaire du point de terminaison authorize

Vous pouvez utiliser le jeton d’actualisation pour obtenir un nouveau jeton d’accès. En général, un utilisateur n’aura besoin d’un nouveau jeton d’accès qu’après l’expiration du précédent ou lorsqu’il devra accéder à une nouvelle ressource pour la première fois. C’est une mauvaise pratique d’appeler le point de terminaison pour obtenir un nouveau jeton d’accès chaque fois que vous faites une requête à une API, et Auth0 applique des limites de débit qui restreindront le nombre de requêtes vers ce point de terminaison pouvant être exécutées avec le même jeton à partir de la même adresse IP.

Pour actualiser votre jeton, faites une requête POST au point de terminaison /oauth/token dans l’Authentication API, en utilisant grant_type=refresh_token.

​

Exemple de requête POST de jeton d’actualisation à l’URL de jeton

Paramètres de la requête de jeton d’actualisation

Nom du paramètre	Description
grant_type	Définissez cette valeur sur “refresh_token”.
client_id	Le Client ID de votre application. Vous trouverez cette valeur dans les Paramètres de l’application.
client_secret	Le Client Secret de votre application. Vous trouverez cette valeur dans les Paramètres de l’application.
refresh_token	Le jeton d’actualisation à utiliser.
scope	(Facultatif) Une liste de scopes demandés, séparés par des espaces. S’il n’est pas envoyé, les scopes d’origine seront utilisés; sinon, vous pouvez demander un ensemble réduit de scopes. Notez que cette valeur doit être encodée dans l’URL.

​

Réponse du jeton d’actualisation

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec une charge utile qui contient un nouvel access_token, un id_token (facultatif), la durée de validité du jeton en secondes (expires_in), les valeurs scope accordées et token_type :

{
  "access_token": "eyJ...MoQ",
  "expires_in": 86400,
  "scope": "openid offline_access",
  "id_token": "eyJ...0NE",
  "token_type": "Bearer"
}

Validez vos jetons avant de les enregistrer. Pour savoir comment faire, consultez Valider le jeton d’identité et Valider les jetons d’accès.

​

Exemples de scénarios d’utilisation

​

Détecter l’utilisation du flux d’autorisation d’appareil

Vous pouvez utiliser Rules pour détecter si la transaction en cours utilise le flux d’autorisation d’appareil. (Pour en savoir plus sur Rules, consultez Auth0 Rules.) Pour ce faire, vérifiez la propriété protocol de l’objet context :

function (user, context, callback) {
   if (context.protocol === 'oauth2-device-code') {
      ...
   }
 
   callback(null, user, context);
}

​

Exemples de mises en œuvre

• Device Authorization Playground
• AppleTV (Swift): Une application simple qui montre comment utiliser Auth0 avec le flux d’autorisation d’appareil sur une Apple TV.
• CLI (Node.js): Exemple de mise en œuvre d’un CLI qui utilise le flux d’autorisation d’appareil plutôt que le flux de code d’autorisation. La principale différence, c’est que votre CLI n’a pas besoin d’héberger un serveur Web ni d’écouter sur un port.

​

Dépannage

Des logs du tenant sont créés pour chaque interaction et peuvent servir au dépannage. Pour en savoir plus, consultez Logs.

​

Codes d’erreur

Code	Nom	Description
fdeaz	Échec de la demande d’autorisation de l’appareil
fdeac	Échec de l’activation de l’appareil
fdecc	L’utilisateur a annulé la confirmation de l’appareil
fede	Échec de l’échange	code de l’appareil pour jeton d’accès
sede	réussite de l’échange	code de l’appareil pour jeton d’accès

​

Limitations

Pour utiliser le flux d’autorisation d’appareil, les appareils doivent :

• Prendre en charge l’indication du nom de serveur (SNI) lorsque des domaines personnalisés sont utilisés
• Avoir un type d’application Auth0 Native
• Avoir la méthode d’authentification du Token Endpoint réglée sur None
• Être conformes à OIDC
• Ne pas avoir été créés au moyen de l’enregistrement dynamique des clients

De plus, le flux d’autorisation d’appareil ne permet pas :

• Les connexions sociales utilisant des clés de développeur Auth0, sauf si vous utilisez l’expérience Universal Login
• D’accéder aux paramètres de chaîne de requête à partir de la page de connexion hébergée, de Rules ou d’Actions
• La liaison de comptes d’utilisateur

Nous prenons entièrement en charge le Draft 15, sauf pour les clients confidentiels. Pour en savoir plus, consultez OAuth 2.0 Device Authorization Grant Draft 15 sur ietf.org.

​

En savoir plus

• Cadre d’autorisation OAuth 2.0
• Protocole OpenID Connect
• Jetons
• Journaux