Migrer vers les points de terminaison de la Management API avec des jetons d’accès

Décrit la dépréciation de l’utilisation des ID tokens comme identifiants pour la Management API et explique comment migrer votre configuration afin d’utiliser des jetons d’accès.

L’utilisation des ID tokens pour appeler des points de terminaison de la Management API est en cours d’abandon. Vous devez utiliser des jetons d’accès. La période de grâce pour cette migration a commencé le 31 mars 2018.

Après avoir terminé votre migration vers les jetons d’accès, désactivez l’option Autoriser les ID Tokens pour l’authentification à Management API v2 dans l’Auth0 Dashboard.

Si vous utilisez des ID tokens pour appeler l’un des points de terminaison suivants, cette migration vous concerne. Ces points de terminaison acceptent désormais des jetons d’accès standard. Rien d’autre ne change dans le fonctionnement de ces points de terminaison. Les schémas de requête et de réponse restent les mêmes, et vous n’avez qu’à mettre à jour le jeton que vous utilisez pour l’autorisation.

​

Points de terminaison concernés

Point de terminaison	Cas d’utilisation
GET /api/v2/users/	Obtenir les renseignements d’un utilisateur
GET /api/v2/users//enrollments	Obtenir toutes les inscriptions MFA Guardian d’un utilisateur
PATCH /api/v2/users/	Mettre à jour les renseignements d’un utilisateur
DELETE /api/v2/users//multifactor/	Supprimer les paramètres du fournisseur MFA d’un utilisateur
POST /api/v2/device-credentials	Créer une clé publique pour un appareil
DELETE /api/v2/device-credentials/	Supprimer un identifiant d’appareil
POST/api/v2/users//identities	Lier des comptes d’utilisateur provenant de divers fournisseurs d’identité
DELETE /api/v2/users//identities//	Dissocier des comptes d’utilisateur

​

Actions

​

Modifications des scopes

Les actions que vous pouvez effectuer avec la Management API dépendent des scopes inclus dans votre jeton d’accès. Avec cette migration, vous pouvez soit obtenir un jeton d’accès limité qui ne peut mettre à jour que les données de l’utilisateur connecté, soit un jeton d’accès qui peut mettre à jour les données de n’importe quel utilisateur. Dans la matrice suivante, vous pouvez voir quels scopes votre jeton doit avoir selon le cas et le point de terminaison.

Par exemple, si vous obtenez un jeton d’accès qui contient le scope read:users, vous pouvez récupérer les données de n’importe quel utilisateur à l’aide du point de terminaison GET /api/v2/users/{id}. Cependant, si votre jeton contient le scope read:current_user, vous pouvez seulement récupérer les renseignements de l’utilisateur actuellement connecté (celui pour lequel le jeton a été émis).

Point de terminaison	Scope pour l’utilisateur actuel	Scope pour n’importe quel utilisateur
GET /api/v2/users/	read:current_user	read:users
GET /api/v2/users//enrollments	read:current_user	read:users
POST/api/v2/users//identities	update:current_user_identities	update:users
DELETE /api/v2/users//identities//	update:current_user_identities	update:users
PATCH /api/v2/users/	update:current_user_metadata	update:users
PATCH /api/v2/users/	create:current_user_metadata	update:users
DELETE /api/v2/users//multifactor/	delete:current_user_metadata	update:users
POST /api/v2/device-credentials	create:current_user_device_credentials	create:device_credentials
DELETE /api/v2/device-credentials/	delete:current_user_device_credentials	delete:device_credentials

​

Obtenir des jetons d’accès

Auth0 a modifié la manière d’obtenir un jeton pour les points de terminaison mentionnés précédemment. Il existe plusieurs façons d’authentifier un utilisateur et d’obtenir des jetons, selon la technologie et le flux OAuth 2.0 utilisé pour l’authentification :

• SPA exécutée dans un navigateur : utilisez le point de terminaison d’autorisation.
• Application Web exécutée sur un serveur, application mobile, processus côté serveur ou application hautement fiable : utilisez le point de terminaison de jeton.
• Authentification croisée : utilisez Lock intégré ou auth0.js pour authentifier les utilisateurs lorsque les requêtes proviennent de domaines différents.

​

Point de terminaison d’autorisation

Dans cette section, nous utiliserons un exemple pour montrer les différences dans la façon d’obtenir un jeton à l’aide du point de terminaison d’autorisation. Gardez à l’esprit que, peu importe le point de terminaison à migrer, les changements sont les mêmes; seule la portée des scopes que vous indiquez dans la requête diffère.

Dans l’exemple ci-dessous, vous utilisez le point de terminaison GET User by ID pour récupérer les renseignements complets du profil de l’utilisateur connecté. Pour ce faire, nous allons d’abord authentifier l’utilisateur à l’aide de l’octroi implicite et récupérer le ou les jetons. Ci-dessous, vous pouvez voir une implémentation de l’ancienne approche, qui obtient un ID Token puis l’utilise pour appeler le point de terminaison.

Dans l’exemple ci-dessous, vous pouvez voir la nouvelle approche pour obtenir un jeton d’accès.

Pour obtenir un jeton d’accès permettant d’accéder à la Management API :

• Définissez audience sur https://{yourDomain}/api/v2/
• Demandez le scope ${scope}
• Définissez response_type sur id_token token pour qu’Auth0 envoie à la fois un jeton d’identité et un jeton d’accès

Si vous décodez le jeton d’accès reçu et en examinez le contenu, vous verrez ce qui suit :

Notez que aud correspond à l’URI d’API de votre locataire, que scope correspond à ${scope} et que sub correspond à l’ID utilisateur de l’utilisateur connecté.

Une fois le jeton d’accès obtenu, vous pouvez l’utiliser pour appeler le point de terminaison. Cette partie reste inchangée : rien d’autre ne change dans la requête, sauf la valeur utilisée comme jeton Bearer. La réponse reste également la même.

​

Point de terminaison de jeton

Dans cette section, nous utiliserons un exemple pour illustrer les différences dans la façon d’obtenir un jeton à partir du point de terminaison de jeton. Gardez toutefois à l’esprit que, peu importe le point de terminaison que vous souhaitez migrer, les modifications sont les mêmes : seule la liste des scopes indiqués dans la requête change.

Dans l’exemple ci-dessous, vous souhaitez utiliser le point de terminaison GET User by ID pour récupérer toutes les informations du profil de l’utilisateur connecté. Commencez par authentifier l’utilisateur à l’aide de l’octroi Password Exchange, puis récupérez le ou les jetons. Ci-dessous, vous pouvez voir une implémentation de l’ancienne approche, qui obtient un ID Token (puis l’utilise pour appeler le point de terminaison).

Dans l’exemple ci-dessous, vous pouvez également voir la nouvelle approche permettant aussi d’obtenir un jeton d’accès.

Pour obtenir un Jeton d’accès permettant d’accéder à la Management API :

• Définissez aud sur https://{yourDomain}/api/v2/
• Demandez le scope read:current_user

Une fois que vous avez le jeton d’accès, vous pouvez l’utiliser pour appeler le point de terminaison. Cette partie reste la même : rien d’autre ne change dans la requête, sauf la valeur utilisée comme jeton Bearer. La réponse reste elle aussi la même.

​

Lock intégré ou auth0.js

Si vous intégrez Lock ou auth0.js v9 à votre application, vous utilisez l’authentification inter-origine. Celle-ci sert à authentifier les utilisateurs lorsque les requêtes proviennent de domaines différents.

Si vous utilisez auth0.js pour accéder à la Management API et gérer vos utilisateurs, vous devrez mettre votre script à jour.

Dans l’exemple ci-dessous, vous pouvez voir l’ancienne méthode.

Dans cet exemple, vous pouvez voir la nouvelle méthode.

• Demandez à la fois un jeton d’identité et un jeton d’accès dans la réponse

  responseType: 'token id_token'

• Définissez la Management API comme audience cible du jeton

  audience: 'https://YOUR_DOMAIN/api/v2/'

• Demandez l’autorisation requise

  scope: 'read:current_user'

• Authentifiez-vous auprès de la Management API à l’aide du jeton d’accès

​

Modifications de la liaison de comptes

Les modifications apportées à cette fonctionnalité sont les suivantes :

• Vous ne pouvez plus utiliser un ID Token dans l’en-tête Authorization

• Si vous utilisez un jeton d’accès dans l’en-tête Authorization, avec update:users comme permission accordée, vous pouvez envoyer dans le corps de la requête soit le user_id, soit l’ID Token du compte secondaire

• Si vous utilisez un jeton d’accès dans l’en-tête Authorization, avec update:current_user_metadata comme permission accordée, vous pouvez uniquement envoyer l’ID Token du compte secondaire dans le corps de la requête. Les conditions suivantes doivent être respectées :

  • Le jeton d’identité doit être signé à l’aide de RS256 (vous pouvez définir cette valeur dans Auth0 Dashboard > Applications > paramètres de l’application > Paramètres avancés > OAuth)
  • La revendication aud du jeton d’identité doit identifier l’application et avoir la même valeur que la revendication azp du jeton d’accès

​

Restrictions

Les jetons d’accès utilisés pour accéder à la Management API ne doivent comporter qu’une seule valeur pour la revendication aud. Si votre jeton contient plus d’une valeur, votre requête vers la Management API échouera.

​

Pour en savoir plus

• Migrer vers les jetons d’accès pour la liaison de comptes