Appeler votre API au moyen du flux d’autorisation d’appareil

Découvrez comment appeler votre API depuis un appareil aux capacités d’entrée limitées au moyen du flux d’autorisation d’appareil.

Ce tutoriel vous aidera à appeler votre propre API depuis un appareil aux capacités de saisie limitées à 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 de mettre en œuvre facilement le flux d’autorisation d’appareil au moyen de :

• Authentication API : poursuivez votre lecture pour découvrir comment 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) pour vous assurer que le flux d’autorisation de l’appareil convient à votre implémentation.

• Enregistrez l’application dans Auth0.

  • Sélectionnez Native comme Application Type.
  • Au besoin, définissez Allowed Web Origins. 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 particulier dont l’architecture est soumise à CORS (p. ex., HTML5 + JS). La plupart des applications n’utiliseront pas ce paramètre.
  • Assurez-vous que l’option OIDC Conformant est activée. Ce paramètre se trouve dans l’Auth0 Dashboard, sous Applications > Application > Advanced Settings > OAuth.
  • Assurez-vous que les Grant Types de l’application incluent Device Code. Pour savoir comment faire, consultez Update Grant Types.
  • Si vous voulez que votre application puisse utiliser des jetons d’actualisation, assurez-vous que les Grant Types de l’application incluent Refresh Token. Pour savoir comment faire, consultez Update Grant Types. Pour en savoir plus sur les jetons d’actualisation, consultez Refresh Tokens.

• Configurez et activez au moins une connexion pour l’application : connexions de base de données, connexions sociales

• Enregistrez votre API dans Auth0

  • Si vous voulez que votre API reçoive des jetons d’actualisation pour 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 Refresh Tokens.

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

​

Étapes

1. Demander un code d’appareil (flux d’appareil) : Demandez un code d’appareil que l’utilisateur pourra 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 de jeton pour demander un jeton.
4. Autoriser l’utilisateur (flux de navigateur) : L’utilisateur autorise l’appareil afin que celui-ci puisse recevoir des jetons.
5. Recevoir des jetons (flux d’appareil) : Une fois que l’utilisateur a autorisé l’appareil, recevez les jetons.
6. Appeler l’API (flux d’appareil) : Utilisez le Jeton d’accès récupéré pour appeler votre API.
7. Actualiser les jetons (flux d’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 lancé l’application sur son appareil et veut autoriser celui-ci, vous devez obtenir un code d’appareil. Lorsque l’utilisateur ouvre sa session sur son appareil doté d’un navigateur, ce code est associé à cette session.

Pour obtenir le code d’appareil, votre application doit demander un code à l’URL du code d’appareil, en incluant l’ID client.

​

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

Paramètres du code d’appareil

Notez que, lorsque vous demandez un code d’appareil pour appeler 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 un Jeton d’accès uniquement pour récupérer des renseignements sur l’utilisateur authentifié, aucun paramètre 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 de l’application.
scope	Les scopes pour lesquels vous voulez 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 revendications personnalisées conformes à un format avec espace de noms, ou n’importe quels scopes pris en charge par l’API cible (p. 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 renseignements 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 paramètres de l’API). Notez que cette valeur doit être encodée dans l’URL.
audience	L’identificateur 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 les prérequis de ce tutoriel. Notez que cette valeur doit être encodée dans l’URL.

​

Réponse du code d’appareil

Si tout se passe bien, vous recevrez une réponse HTTP 200 avec un payload 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ède à verification_uri dans le navigateur de son appareil, ce code est associé à sa session.
• user_code contient le code à saisir à l’adresse 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 Paramètres du locataire.

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 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’adresse verification_uri sur son ordinateur portable ou son téléphone intelligent et d’entrer le user_code :

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

Si vous créez une 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 à scruter l’URL du jeton pour demander un Jeton d’accès. À l’aide de l’intervalle de scrutation (interval) extrait à l’étape précédente, vous devrez envoyer une requête POST à l’URL du jeton avec le device_code.

Pour éviter les erreurs dues à la latence réseau, commencez à compter chaque intervalle après avoir reçu la réponse à la requête de scrutation précédente.

​

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

Paramètres de la requête de jeton

Nom du paramètre	Description
grant_type	Définissez cette valeur à “urn:ietf:params:oauth:grant-type:device_code”. Il s’agit d’un type d’octroi d’extension (tel que défini à la section 4.5 de la RFC6749). Notez que cette valeur doit être encodée 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 trouverez cette valeur dans les paramètres de l’application.

​

Réponses liées au jeton

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

Autorisation en attente

Vous verrez cette erreur en attendant que l’utilisateur passe à l’action. Continuez la scrutation à l’aide de l’intervalle suggéré récupéré à l’étape précédente de ce tutoriel.

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

Ralentissez

Vous effectuez la scrutation trop rapidement. 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 scrutation.

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 relancer le flux.

L’erreur expired_token n’est renvoyée qu’une seule fois ; par la suite, invalid_grant est renvoyée. Votre appareil doit arrêter la scrutation.

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’autorisation a rejeté la transaction
• une Rule configurée a refusé l’accès (Pour en savoir plus, consultez Auth0 Rules.)

​

Autoriser l’utilisateur

L’utilisateur balayera soit le code QR, soit ouvrira la page d’activation et saisira le code d’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 :

• L’authentification de l’utilisateur;
• La redirection de l’utilisateur vers un fournisseur d’identité pour gérer l’authentification;
• La vérification de sessions d’SSO actives;
• L’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 obtenu, l’invite de confirmation s’affichera :

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

​

Recevoir les jetons

Pendant que l’utilisateur s’authentifie et autorise l’appareil, l’application sur l’appareil a continué d’interroger l’URL du 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 un payload contenant 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 les ID Tokens et Valider les jetons d’accès.

Les jetons d’accès servent à appeler l’endpoint /userinfo de l’Auth0 Authentication API 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 le scope openid. Si vous appelez votre propre API, la première chose à faire pour celle-ci sera de vérifier le jeton d’accès.

ID Tokens contiennent des informations sur l’utilisateur qu’il faut décoder et extraire. (Pour en savoir plus sur les ID Tokens, consultez ID Tokens.) Le id_token ne sera présent dans la réponse que si vous avez inclus le scope openid.

Jetons d’actualisation servent à obtenir un nouveau jeton d’accès ou un ID Token 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 le scope offline_access et activé Allow Offline Access pour votre API dans l’Auth0 Dashboard.

Les jetons d’actualisation doivent être stockés de façon sécurisée, puisqu’ils permettent à un utilisateur de rester authentifié pratiquement indéfiniment.

​

Appelez votre API

Pour appeler votre API, l’application doit transmettre le Jeton d’accès obtenu sous forme de Bearer Token dans l’en-tête Authorization de la 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 le scope offline_access lorsque vous avez lancé la demande d’authentification au moyen 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’a besoin d’un nouveau Jeton d’accès qu’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 applique des limites de débit qui réduiront le nombre de requêtes vers le point de terminaison pouvant être exécutées avec le même jeton depuis la même adresse IP.

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

​

Exemple de requête POST avec un jeton d’actualisation à l’URL du 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	L’ID client de votre application. Vous trouverez cette valeur dans les paramètres de l’application.
client_secret	Le Secret client 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 transmis, 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 au format URL.

​

Réponse du jeton d’actualisation

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

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

Avant d’enregistrer vos jetons, validez-les. Pour savoir comment faire, consultez Valider les ID tokens et Valider les jetons d’accès.

​

Exemples 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, 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 d’implémentation

• Bac à sable du flux d’autorisation d’appareil
• AppleTV (Swift): Application simple qui montre comment utiliser Auth0 avec le flux d’autorisation d’appareil sur une Apple TV.
• CLI (Node.js): Exemple d’implémentation d’une CLI qui utilise le flux d’autorisation d’appareil au lieu du 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

Les journaux du locataire sont généré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 d’appareil contre jeton d’accès
sede	Échange réussi	Code d’appareil contre jeton d’accès

​

Limitations

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

• Prendre en charge l’indication du nom du serveur (SNI) lorsque des Domaines personnalisés sont utilisés
• Avoir un type d’application Auth0 défini sur Native
• Avoir la méthode d’authentification du point de terminaison de jeton définie sur None
• Être conformes à OIDC
• Ne pas être créés au moyen de l’Enregistrement dynamique des applications

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

• Les connexions sociales utilisant des clés de développeur Auth0, à moins que vous n’utilisiez l’expérience Universal Login
• L’accès 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 en charge l’intégralité du brouillon 15, sauf pour les applications confidentielles. 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
• Logs