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

Découvrez comment appeler votre API à partir d’un appareil dont les entrées sont limitées, à 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

1. Demander le code de l’appareil (Flux d’appareil) : Demandez un code d’appareil que l’utilisateur peut utiliser pour autoriser l’appareil.
2. 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.
3. Demander des jetons) (Flux d’appareil) : Interrogez le point de terminaison du jeton pour demander un jeton.
4. Autoriser l’utilisateur (Flux du navigateur) : L’utilisateur autorise l’appareil, afin que l’appareil puisse recevoir des jetons.
5. Recevoir des jetons (Flux d’appareil) : Une fois que l’utilisateur a autorisé avec succès l’appareil, vous pouvez recevoir des jetons.
6. Appel à l’API (Flux d’appareil) : Utilisez le jeton d’accès récupéré pour appeler votre API.
7. 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

cURL

curl --request POST \
  --url 'https://{yourDomain}/oauth/device/code' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'client_id={yourClientId}' \
  --data 'scope={scope}' \
  --data 'audience={audience}'

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 audience,
• é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 :

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.

cURL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=urn:ietf:params:oauth:grant-type:device_code \
  --data 'device_code={yourDeviceCode}' \
  --data 'client_id={yourClientId}'

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 :

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

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 (SSO);
• Obtenir le consentement de l’utilisateur pour l’appareil, à moins qu’il n’ait été donné au préalable.

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

À 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é à interroger l’URL 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.

cURL

curl --request GET \
  --url https://myapi.com/api \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json'

​

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.

cURL

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data 'client_id={yourClientId}' \
  --data 'client_secret={yourClientSecret}' \
  --data 'refresh_token={yourRefreshToken}'

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.

​

En savoir plus

• Cadre d’applications Authorization OAuth 2.0
• Protocole OpenID Connect
• Jetons
• Journaux