Migrer vers les points de terminaison de la Management API au moyen de jetons d’accès

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

L’utilisation de jetons ID pour appeler les points de terminaison de 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.

Une fois votre migration vers les jetons d’accès terminée, désactivez la bascule Allow ID Tokens for Management API v2 Authentication dans le Dashboard.

Si vous utilisez des jetons ID pour appeler l’un des points de terminaison suivants, cette migration vous concerne. Ces points de terminaison acceptent maintenant des jetons d’accès standard. Rien d’autre ne change dans leur fonctionnement. Vous pouvez vous attendre aux mêmes schémas de requête et de réponse; vous n’avez qu’à mettre à jour le jeton utilisé pour l’autorisation.

​

Points de terminaison touchés

Point de terminaison	Cas d’utilisation
GET /api/v2/users/	Récupérer les renseignements d’un utilisateur
GET /api/v2/users//enrollments	Récupérer toutes les inscriptions à Guardian MFA 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 pour un utilisateur
POST /api/v2/device-credentials	Créer une clé publique pour un appareil
DELETE /api/v2/device-credentials/	Supprimer les informations d’authentification d’un appareil
POST/api/v2/users//identities	Lier des comptes d’utilisateur provenant de différents fournisseurs d’identité
DELETE /api/v2/users//identities//	Dissocier des comptes d’utilisateur

​

Actions

​

Modifications des portées

Les actions que vous pouvez effectuer avec la Management API dépendent des portées incluses 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 les portées que votre jeton doit avoir dans chaque cas et pour chaque point de terminaison.

Par exemple, si vous obtenez un jeton d’accès qui contient la portée 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 la portée read:current_user, vous ne pouvez récupérer que les renseignements de l’utilisateur actuellement connecté (celui pour lequel le jeton a été émis).

Point de terminaison	Portée pour l’utilisateur actuel	Portée 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 changé la façon 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 illustrer les différences dans la façon d’obtenir un token avec le point de terminaison d’autorisation. Gardez à l’esprit que, peu importe le point de terminaison que vous souhaitez migrer, les changements sont les mêmes; la seule chose qui diffère, ce sont les portées que vous précisez dans la requête.

Dans l’exemple ci-dessous, vous utilisez le point de terminaison GET User by ID pour récupérer toutes les informations du profil de l’utilisateur connecté. Pour ce faire, nous commencerons par authentifier l’utilisateur au moyen de l’Implicit grant et récupérer le ou les tokens. Ci-dessous, vous pouvez voir une mise en œuvre de l’ancienne approche, qui obtient un jeton d’identité puis l’utilise pour effectuer une requête au 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 pour la Management API :

• Définissez audience sur https://{yourDomain}/api/v2/
• Demandez la portée ${scope}
• Définissez response_type sur id_token token afin 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 de l’API de votre tenant, portée à ${scope} et sub à l’ID de l’utilisateur connecté.

Une fois que vous avez le jeton d’accès, vous pouvez l’utiliser pour envoyer une requête au 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 également la même.

​

Point de terminaison de jeton

Dans cette section, nous utiliserons un exemple pour montrer les différences dans la façon d’obtenir un jeton au moyen du point de terminaison de jeton. Gardez toutefois à l’esprit que, peu importe le point de terminaison que vous souhaitez migrer, les changements sont les mêmes : seule la portée précisée 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 l’ensemble des renseignements de profil de l’utilisateur connecté. Commencez par authentifier l’utilisateur à l’aide du grant Password Exchange, puis récupérez le ou les jetons. Ci-dessous, vous pouvez voir une mise en œuvre de l’ancienne approche, qui obtient un jeton d’identité (puis l’utilise pour envoyer une requête au point de terminaison).

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

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

• Définissez aud sur https://{yourDomain}/api/v2/
• Demandez la portée read:current_user

Une fois que vous avez le jeton d’accès, vous pouvez l’utiliser pour envoyer une requête au 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 également la même.

​

Embedded Lock ou auth0.js

Si vous intégrez Lock ou auth0.js v9 à votre application, vous utilisez l’authentification inter-origines. Elle 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, votre script devra être mis à jour.

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

Cet exemple illustre la nouvelle approche.

• 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 l’audience du token

  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 à la liaison de comptes

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

• Vous ne pouvez plus utiliser un jeton d’identité 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 le jeton d’identité 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 seulement envoyer le jeton d’identité du compte secondaire dans le corps de la requête. Les conditions suivantes doivent être respectées :

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

​

Restrictions

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

​

En savoir plus

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