Appeler une API à l’aide du flux d’autorisation d’appareil

Ce tutoriel vous aidera à appeler votre propre API à partir d’un appareil à entrée limitée en utilisant le flux d’autorisation d’appareil. Pour savoir comment fonctionne le flux et pourquoi vous devriez l’utiliser, consultez Flux d’autorisation d’appareil.

Auth0 permet à votre application d’implémenter facilement le flux d’autorisation d’appareil en utilisant :

Authentication API : Poursuivez la lecture pour savoir comment appeler votre API directement. Pour une expérience interactive, veuillez consulter Terrain de jeu du flux d’appareil.

Prérequis

Avant de commencer ce tutoriel :

Vérifiez les limitations (ci-dessous) pour vous assurer que le flux d’autorisation d’appareil convient à votre mise en œuvre.
Register the Application with Auth0 (Enregistrez l’application avec Auth0).
- Sélectionnez un Application Type (Type d’application)****Native (Natif).
- Si nécessaire, définissez Origines Web autorisées. Vous pouvez ainsi autoriser localhost comme origine lors du développement local, ou pour définir une origine autorisée pour un logiciel TV spécifique avec une architecture soumise à CORS (par exemple, HTML5 + JS). La plupart des applications n’utiliseront pas ce paramètre.
- Assurez-vous que l’option OIDC Conformant (Conforme à l’OIDC) est activée. Ce paramètre se trouve dans Dashboard sous Applications > Application > Advanced Settings (Paramètres avancés) > OAuth.
- Assurez-vous que les Grant Types (Types d’autorisation) de l’application comprennent le Device Code (Code de l’appareil). Pour en savoir plus, lisez Mettre à jour les types d’autorisation.
- Si vous souhaitez que votre application puisse utiliser des jetons d’actualisation, assurez-vous que les Types d’autorisation de l’application comprennent le Jeton d’actualisation. Pour en savoir plus, lisez Mettre à jour les types d’autorisation. Pour en savoir plus sur les jetons d’actualisation, lisez Jetons d’actualisation.
Configurez et activez au moins une connexion pour l’application : Database connections (Connexions aux bases de données), Social connections (Connexions sociales)
Enregistrez votre application avec Auth0
- Si vous souhaitez que votre API reçoive des jetons d’actualisation afin d’obtenir de nouveaux jetons lorsque les précédents expirent, activez Autoriser l’accès hors ligne. Pour en savoir plus sur les jetons d’actualisation, consultez Jetons d’actualisation.
Configure Device User Code Settings (Configurez les paramètres du code utilisateur de l’appareil) pour définir le jeu de caractères, le format et la longueur de votre code utilisateur généré de manière aléatoire.

Étapes

Demander le code de l’appareil (Flux d’appareil) : Demandez un code d’appareil que l’utilisateur peut utiliser pour autoriser l’appareil.
Demander l’activation de l’appareil (Flux d’appareil) : Demandez à l’utilisateur d’autoriser l’appareil à l’aide de son ordinateur portable ou de son téléphone intelligent.
Demander des jetons) (Flux d’appareil) : Interrogez le point de terminaison du jeton pour demander un jeton.
Autoriser l’utilisateur (Flux du navigateur) : L’utilisateur autorise l’appareil, afin que l’appareil puisse recevoir des jetons.
Recevoir des jetons (Flux d’appareil) : Une fois que l’utilisateur a autorisé avec succès l’appareil, vous pouvez recevoir des jetons.
Appel à l’API (Flux d’appareil) : Utilisez le jeton d’accès récupéré pour appeler votre API.
Jetons d’actualisation (Flux d’appareil) : Utilisez un jeton d’actualisation pour demander de nouveaux jetons lorsque les anciens expirent.

Facultatif : Découvrez des cas d’utilisation. Facultatif : Dépanner.

Recevoir le code de l’appareil

Une fois que l’utilisateur a démarré l’application de son appareil et souhaite autoriser l’appareil, vous devrez obtenir un code d’appareil. Lorsque l’utilisateur démarre sa session sur son appareil basé sur un navigateur, ce code sera lié à cette session. Pour obtenir le code de l’appareil, votre application doit demander un code à partir de l’URLdu code d’appareil, notamment l’ID client.

Exemple POST vers l’URL de code d’appareil

Paramètres du code d’appareil

Veuillez noter que lors de la demande d’un code d’appareil pour appeler une API personnalisée, vous devez procéder ainsi :

inclure un paramètre ,
éventuellement inclure des permissions supplémentaires prises en charge par l’API cible.

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

Nom du paramètre	Description
`client_id`	L’ID client de votre application. Vous pouvez trouver cette valeur dans vos Paramètres d’application.
`scope`	Les permissions pour lesquels vous souhaitez demander une autorisation. Ceux-ci doivent être séparés par un espace. Vous pouvez demander n’importe laquelle des permissions OIDC standard concernant les utilisateurs, telles que `profile` et `email`, des demandes personnalisées conformes à un format d’espace de noms, ou n’importe quelle permission prise en charge par l’API cible (par exemple, `read:contacts`. Incluez `openid` pour obtenir un jeton d’ID ou pour pouvoir utiliser le point de terminaison /userinfo pour récupérer les informations de profil de l’utilisateur. Incluez `offline_access` pour obtenir un jeton d’actualisation (assurez-vous que le champ Autoriser l’accès hors ligne est activé dans les Paramètres de l’API). Notez que cela doit être codé par URL.
`audience`	L’identifiant unique de l’API à laquelle votre application souhaite accéder. Utilisez la valeur Identifier dans l’onglet Paramètres pour l’API que vous avez créée dans le cadre des prérequis de ce tutoriel. Notez que cela doit être codé par URL.

Réponse du code de l’appareil

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec une charge utile contenant les valeurs device_code, user_code, verification_uri, 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èdera à verification_uri sur son appareil basé sur un navigateur, ce code sera lié à sa session.
code_utilisateur contient le code qui doit être saisi dans verification_uri pour autoriser l’appareil.
verification_uri contient l’URL que l’utilisateur doit visiter pour autoriser l’appareil.
verification_uri_complete contient l’intégralité de l’URL que l’utilisateur doit visiter pour autoriser l’appareil. Cela permet à votre application d’intégrer le user_code dans l’URL, si vous le souhaitez.
expires_in indique la durée de vie (en secondes) des codes device_code et user_code.
interval indique l’intervalle (en secondes) auquel l’application doit interroger l’URL de 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é de manière aléatoire dans vos paramètres du locataire.Pour empêcher les attaques en force brute, nous imposons les limites suivantes au user_code :Longueur minimale :

Lettres BASE20 : 8 caractères
Nombres : 9 caractères

Longueur maximale :

20 caractères (tirets et espaces inclus, qui peuvent être ajoutés comme séparateurs pour une meilleure lisibilité)

Délai d’expiration :

15 minutes

Demande d’activation de l’appareil

Une fois que vous avez reçu un device_code et un user_code vous devez demander à l’utilisateur d’accéder à verification_uri sur son ordinateur portable ou téléphone intelligent et saisir le user_code :

Auth0 Flows Device Authorization Request, sample page showing two activation methods, user_code and QR code

Le device_code n’est pas destiné directement à l’utilisateur et ne doit pas être affiché pendant l’interaction afin de ne pas créer de confusion chez l’utilisateur.

Lorsque vous créez une interface de ligne de commande, vous pouvez ignorer cette étape et ouvrir directement le navigateur avec verification_uri_complete.

Demander des jetons

Pendant que vous attendez que l’utilisateur active l’appareil, commencez à interroger l’URL de jeton pour demander un jeton d’accès. En utilisant l’intervalle d’interrogation (interval) extrait de l’étape précédente, vous devrez POST sur l’URL de jeton en l’envoyant avec le device_code. Pour éviter des erreurs dues à la latence du réseau, vous devez commencer à compter chaque intervalle après la réception de la réponse de la dernière demande d’interrogation.

Exemple de demande POST de jeton vers l’URL de jeton.

Paramètres de demande de jeton

Nom du paramètre	Description
`grant_type`	Définir cette option sur « urn:ietf:params:oauth:grant-type:device_code ». Il s’agit d’un type de subvention d’extension (tel que défini par la section 4.5 de RFC6749). Notez que cela doit être encodé en URL.
`device_code`	Le `device_code` récupéré à l’étape précédente de ce tutoriel.
`client_id`	L’ID client de votre application. Vous pouvez également trouver cette valeur dans les Paramètres de l’application.

Réponses des jetons

Il est possible de recevoir plusieurs réponses HTTP 4xx différentes pendant que vous attendez que l’utilisateur autorise l’appareil :

Autorisation en attente

Vous verrez cette erreur pendant que vous attendez que l’utilisateur agisse. Poursuivez l’interrogation en utilisant interval suggéré dans l’étape précédente de ce tutoriel.

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

Ralentissement

L’interrogation est trop rapide. Ralentissez et utilisez l’intervalle suggéré dans l’étape précédente de ce tutoriel. Pour éviter de recevoir cette erreur en raison de la latence du réseau, vous devez commencer à compter chaque intervalle après la réception de la réponse de la dernière demande d’interrogation.

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

Jeton expiré

L’utilisateur n’a pas autorisé l’appareil assez rapidement, par conséquent le device_code a expiré. Votre application doit avertir l’utilisateur que le flux a expiré et l’inviter à le réinitialiser.

L’erreurexpired_token sera renvoyée exactement une fois. Après cela, invalid_grant sera retourné. Votre appareil doit cesser de faire des requêtes répétées.

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

Accès refusé

Enfin, si l’accès 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’autorisations a refusé la transaction,
une règle configurée a refusé l’accès (pour en savoir plus, veuillez consulter Règles d’Auth0.)

Autoriser l’utilisateur

L’utilisateur peut soit balayer le code QR, soit ouvrir la page d’activation et saisir le code d’utilisateur :

Auth0 Flows Device Authorization prompt directing the user to enter the code displayed on their device

Une page de confirmation s’affiche pour que l’utilisateur confirme qu’il s’agit du bon appareil :

Auth0 Flows Device Authorization sample confirmation prompt directing the user to confirm the code

L’utilisateur terminera la transaction en se connectant. Cette étape peut comprendre un ou plusieurs des procédés suivant :

Authentifier l’utilisateur;
Rediriger l’utilisateur vers un fournisseur d’identité pour gérer l’authentification;
Vérification des sessions actives d’authentification unique ();
Obtenir le consentement de l’utilisateur pour l’appareil, à moins qu’il n’ait été donné au préalable.

Auth0 Flows Device Authorization User authorization prompt directing the user to log in with email and password or with Google or another identity

Une fois l’authentification et le consentement obtenus, la demande de confirmation s’affiche :

Flows - Device Authorization - Congratulations notification for user

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

Recevoir les jetons

Pendant que l’utilisateur authentifiait et autorisait l’appareil, l’application de l’appareil a continué à inte](/docs/images/RL de jeton pour demander un jeton d’accès. Une fois que l’utilisateur a autorisé l’appareil avec succès, vous recevrez une réponse HTTP 200 avec une charge utile contenant les valeurs suivantes access_token, refresh_token (en option), id_token (en option), 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 en savoir plus, lisez Valider les jetons d’ID et Valider les jetons d’accès.

Les jetons d’accès sont utilisés pour appeler le point de terminaison /userinfo de Auth0 Authentication API ou d’une autre API. Pour en savoir plus sur les jetons d’accès, veuillez consulter Jetons d’accès. Vous pourrez utiliser le jeton d’accès pour appeler /userinfo uniquement si vous avez inclus la permission openid. Si vous appelez votre propre API, la première chose que votre API devra faire est vérifier le jeton d’accès. Les jetons d’ID contiennent des informations de l’utilisateur qui doivent être décodées et extraites. (Pour en savoir plus sur les jetons d’ID, veuillez consulter la section correspondante) Le id_token ne sera présent dans la réponse que si vous avez inclus la permission openid Les jetons d’actualisation sont utilisés pour obtenir un nouveau jeton d’accès ou un nouveau jeton d’ID après l’expiration du jeton 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 permission offline_access et activé Autoriser l’accès hors ligne pour votre API dans Dashboard.

Les jetons d’actualisation doivent être stockés en toute sécurité car ils permettent aux utilisateurs de rester authentifiés pratiquement indéfiniment.

Appeler votre API

Pour appeler votre API, l’application doit transmettre le jeton d’accès récupéré en tant que jeton du porteur dans l’en-tête d’autorisation 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 complété ce qui suit :

configuré votre API pour autoriser l’accès hors ligne
inclus la permission offline_access lorsque vous avez lancé la demande d’authentification via le authorize endpoint (point de terminaison d’autorisation)

Vous pouvez utiliser le jeton d’actualisation pour obtenir un nouveau jeton d’accès. Généralement, un utilisateur aura besoin d’un nouveau jeton d’accès uniquement après l’expiration du précédent ou lorsqu’il accède à une nouvelle ressource pour la première fois. Il est déconseillé d’appeler le point de terminaison pour obtenir un nouveau jeton d’accès à chaque fois que vous appelez une API, et Auth0 impose des limites anti-attaques qui réduiront la quantité de requêtes au point de terminaison pouvant être exécutées en utilisant le même jeton depuis la même adresse IP. Pour actualiser votre jeton, effectuez une requête POST au point de terminaison /oauth/token dans l’Authentication API, à l’aide de grant_type=refresh_token.

Exemple de jeton d’actualisation POST vers l’URL de jeton.

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

Nom du paramètre	Description
`grant_type`	Définissez sur « refresh_token ».
`client_id`	L’ID client de votre application. Vous pouvez trouver cette valeur dans [Paramètres de l’application] (https://manage.auth0.com/#/Applications/{yourClientId}/settings).
`client_secret`	Le secret client de votre application. Vous pouvez trouver cette valeur dans [Paramètres de l’application] (https://manage.auth0.com/#/Applications/{yourClientSecret}/settings).
`refresh_token`	Le jeton d’actualisation à utiliser.
`scope`	(Facultatif) Une liste délimitée par des espaces des autorisations de permissions requises. Si elles ne sont pas envoyées, les permissions d’origine seront utilisées; sinon, vous pouvez demander un ensemble réduit de permissions. Veuillez noter que cela doit être codé URL.

Réponse du jeton d’actualisation

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec une charge utile contenant un nouveau access_token, id_token (en option), durée de vie du jeton en secondes (expires_in), valeurs de 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 en savoir plus, lisez Valider les jetons d’ID et Valider les jetons d’accès.

Exemples de cas d’utilisation

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

Vous pouvez utiliser des règles pour détecter si la transaction en cours utilise le flux d’autorisation d’appareil. (Pour en savoir plus sur les règles, lisez l’article Règles d’Auth0). Pour cela, 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

Terrain de jeu du flux de l’appareil
AppleTV (Swift) : application simple qui montre comment Auth0 peut être utilisé avec le flux d’autorisation d’appareil AppleTV.
Interface de ligne de commande (Node.js) : exemple de mise en œuvre d’une interface de ligne de commande qui utilise le flux d’autorisation d’un appareil au lieu du flux du code d’autorisation. La principale différence est que votre interface de ligne de commande n’a pas besoin d’héberger un serveur Web et d’écouter sur un port.

Dépanner

Les journaux de locataires sont créés pour toutes les interactions qui ont lieu et peuvent être utilisés pour résoudre les problèmes. Pour en savoir plus, lisez Logs (Journaux).

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 du code de l’appareil contre le jeton d’accès
`sede`	Réussite de l’échange	Code de l’appareil pour le jeton d’accès

Limites

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

Prendre en charge Support Server Name Indication (SNI) (Indication du nom du serveur) lorsque des Custom Domains (Domaines personnalisés) sont utilisés
Avoir une Auth0 Application Type (Type d’application Auth0)Native (Natif)
Avoir la Token Endpoint Authentication Method (Méthode d’authentification du point de terminaison du jeton) définie sur None (Aucune)
Être OIDC-conformant (conforme à l’OIDC)
Ne pas être créée au moyen de Dynamic Client Registration (Enregistrement dynamique des clients)

En outre, le flux d’autorisation d’appareil ne permet pas :

Les Social Connections (Connexions sociales) qui utilisent les Auth0 developer keys (Clés de développeur Auth0), sauf si vous utilisez la Universal Login experience (Expérience de connexion universelle).
Les paramètres de la chaîne de requête doivent être accessibles à partir d’une page de connexion ou de règles hébergées.
Association de comptes d’utilisateur

Nous prenons en charge l’intégralité du Draft 15, à l’exception des clients confidentiels. Pour en savoir plus, veuillez consulter OAuth 2.0 Device Authorization Grant Draft 15 sur ietf.org.

Intégration à Auth0

Notions de base

Configurer Auth0

Planification et conception

Auth0 AI

Appeler une API à l’aide du flux d’autorisation d’appareil

Prérequis

Étapes

Recevoir le code de l’appareil

Exemple POST vers l’URL de code d’appareil

Paramètres du code d’appareil

Réponse du code de l’appareil

Demande d’activation de l’appareil

Demander des jetons

Exemple de demande POST de jeton vers l’URL de jeton.

Paramètres de demande de jeton

Réponses des jetons

Autorisation en attente

Ralentissement

Jeton expiré

Accès refusé

Autoriser l’utilisateur

Recevoir les jetons

Appeler votre API

Jetons d’actualisation

Exemple de jeton d’actualisation POST vers l’URL de jeton.

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

Réponse du jeton d’actualisation

Exemples de cas d’utilisation

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

Exemples de mises en œuvre

Dépanner

Codes d’erreur

Limites

En savoir plus

Intégration à Auth0

Notions de base

Configurer Auth0

Planification et conception

Auth0 AI

​Prérequis

​Étapes

​Recevoir le code de l’appareil

​Exemple POST vers l’URL de code d’appareil

Paramètres du code d’appareil

​Réponse du code de l’appareil

​Demande d’activation de l’appareil

​Demander des jetons

​Exemple de demande POST de jeton vers l’URL de jeton.

Paramètres de demande de jeton

​Réponses des jetons

Autorisation en attente

Ralentissement

Jeton expiré

Accès refusé

​Autoriser l’utilisateur

​Recevoir les jetons

​Appeler votre API

​Jetons d’actualisation

​Exemple de jeton d’actualisation POST vers l’URL de jeton.

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

​Réponse du jeton d’actualisation

​Exemples de cas d’utilisation

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

​Exemples de mises en œuvre

​Dépanner

​Codes d’erreur

​Limites

​En savoir plus

Prérequis

Étapes

Recevoir le code de l’appareil

Exemple POST vers l’URL de code d’appareil

Réponse du code de l’appareil

Demande d’activation de l’appareil

Demander des jetons

Exemple de demande POST de jeton vers l’URL de jeton.

Réponses des jetons

Autoriser l’utilisateur

Recevoir les jetons

Appeler votre API

Jetons d’actualisation

Exemple de jeton d’actualisation POST vers l’URL de jeton.

Réponse du jeton d’actualisation

Exemples de cas d’utilisation

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

Exemples de mises en œuvre

Dépanner

Codes d’erreur

Limites

En savoir plus