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

Décrit l’abandon de l’utilisation des jetons d’ID comme informations d’identification pour Management API et comment migrer votre configuration pour utiliser les jetons d’accès.

L’utilisation des jetons d’ID pour appeler les points de terminaison de Management API est obsolète. 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 la migration vers les jetons d’accès terminée, désactivez le bouton à bascule Autoriser les jetons d’ID pour l’authentification Management API v2 dans le Dashboard.

Si vous utilisez des jetons d’ID pour appeler l’un des points de terminaison suivants, vous êtes concerné par cette migration. Ces points de terminaison peuvent désormais accepter des jetons d’accès ordinaires. Rien d’autre ne change dans la façon dont les points de terminaison fonctionnent. Les schémas de demande et de réponse sont les mêmes et il suffit de 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/	Récupérer les informations d’un utilisateur
GET /api/v2/users//enrollments	Récupérer toutes les inscriptions Guardian MFA pour un utilisateur
PATCH /api/v2/users/	Mettre à jour les informations d’un utilisateur
DELETE /api/v2/users//multifactor/	Supprimer les paramètres du fournisseur multi-facteurs 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’identification d’un appareil
POST/api/v2/users//identities	Associer des comptes d’utilisateurs de différents fournisseurs d’identité
DELETE /api/v2/users//identities//	Désassocier des comptes d’utilisateurs

​

Actions

​

Modifications de permissions

Les actions que vous pouvez effectuer avec Management API dépendent des permissions que votre jeton d’accès contient. Avec cette migration, vous pouvez obtenir soit 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 permissions que votre jeton doit avoir par cas et par point de terminaison.

Par exemple, si vous obtenez un jeton d’accès qui contient la permission read:users, vous pouvez récupérer les données de n’importe quel utilisateur en utilisant le point de terminaison GET /api/v2/users/{id} . Toutefois, si votre jeton contient la permission read:current_user, vous ne pouvez récupérer que les informations de l’utilisateur actuellement connecté (celui pour lequel le jeton a été émis).

| Point de terminaison | Permission pour l’utilisateur actuel | Permission pour tout 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 façon dont vous obtenez un jeton pour les points de terminaison mentionnés ci-dessus. Il existe plusieurs variantes sur la manière d’authentifier un utilisateur et d’obtenir des jetons, en fonction de la technologie et du flux OAuth 2.0 que vous utilisez pour l’authentification :

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

​

Point de terminaison d’autorisation

Dans cette section, nous allons utiliser un exemple pour montrer les différences dans la façon dont vous obtenez un jeton avec le point de terminaison Authorization. Gardez à l’esprit que, quel que soit le point de terminaison que vous souhaitez migrer, les changements sont les mêmes, la seule chose qui diffère sont les permissions que vous spécifiez dans la requête.

Dans l’exemple ci-dessous, vous utilisez le point de terminaison GET User by ID (Obtenir l’utilisateur par identifiant) pour récupérer les informations de profil complètes 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(s) jeton(s). Vous pouvez voir ci-dessous une implémentation de l’ancienne approche qui obtient un jeton d’ID et l’utilise ensuite pour appeler le point de terminaison.

codeblockOld.header.login.logInButton codeblockOld.header.login.configureSnippet

https://{yourDomain}/authorize?
      scope=openid
      &response_type=id_token
      &client_id={yourClientId}
      &redirect_uri=https://{yourApp}/callback
      &nonce={nonce}
      &state={opaqueValue}

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

codeblockOld.header.login.logInButton codeblockOld.header.login.configureSnippet

https://{yourDomain}/authorize?
      audience=https://{yourDomain}/api/v2/
      &scope=read:current_user
      &response_type=token%20id_token
      &client_id={yourClientId}
      &redirect_uri=https://{yourApp}/callback
      &nonce={nonce}
      &state={opaqueValue}

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

• Définir audience à https://{yourDomain}/api/v2/
• Demander la permission ${scope}
• Définissez le response_type à id_token token pour que Auth0 envoie à la fois un jeton d’ID et un jeton d’accès.

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

{
      "iss": "https://{yourDomain}/",
      "sub": "auth0|5a620d29a840170a9ef43672",
      "aud": "https://{yourDomain}/api/v2/",
      "iat": 1521031317,
      "exp": 1521038517,
      "azp": "{yourClientId}",
      "scope": "${scope}"
    }

Remarquez que aud est défini sur l’URI de l’API de votre locataire, scope est défini sur ${scope}, et sub est défini sur l’identifiant de l’utilisateur connecté.

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

​

Point de terminaison du jeton

Dans cette section, nous allons utiliser un exemple pour montrer les différences dans la façon dont vous obtenez un jeton avec le point de terminaison du jeton. Gardez à l’esprit que, quel que soit le point d’accès que vous souhaitez migrer, les changements sont les mêmes, la seule chose qui diffère est les permissions que vous spécifiez dans la requête.

Dans l’exemple ci-dessous, vous souhaitez utiliser le point de terminaison GET User by ID pour récupérer les informations de profil complètes de l’utilisateur connecté. Tout d’abord, authentifiez l’utilisateur à l’aide de l’octroi Password Exchange (Échange de mot passe), puis récupérez le(s) jeton(s). Vous pouvez voir ci-dessous une implémentation de l’ancienne approche qui obtient un jeton d’ID (et l’utilise ensuite pour appeler le point de terminaison).

codeblockOld.header.login.logInButton codeblockOld.header.login.configureSnippet

POST https://{yourDomain}/oauth/token
    Content-Type: application/x-www-form-urlencoded
    {
      "grant_type": "password",
      "username": "{yourUsername}",
      "password": "{yourPassword}",
      "scope": "openid",
      "client_id": "{yourClientId}",
      "client_secret": "{yourClientSecret}",
    }

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

codeblockOld.header.login.logInButton codeblockOld.header.login.configureSnippet

POST https://{yourDomain}/oauth/token
    Content-Type: application/x-www-form-urlencoded
    {
      "grant_type": "password",
      "username": "{yourUsername}",
      "password": "{yourPassword}",
      "audience": "https://{yourDomain}/api/v2/",
      "scope": "read:current_user",
      "client_id": "{yourClientId}",
      "client_secret": "{yourClientSecret}",
    }

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

• Définir le aud à https://{yourDomain}/api/v2/
• Demandez la permission 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 inchangée, rien d’autre ne change dans la demande, à l’exception de la valeur utilisée comme jeton Bearer. La réponse reste également la même.

​

Lock intégré ou auth0.js

Si vous intégrez Lock ou auth0.js v9 dans votre application, vous utilisez l’authentification inter-origines. Celle-ci est utilisée pour authentifier les utilisateurs lorsque les demandes proviennent de domaines différents.

Si vous utilisez auth0.js pour accéder à Management API et gérer vos utilisateurs, votre script devra être mis à jour.

Dans l’exemple ci-dessous, vous pouvez voir l’ancienne approche.

codeblockOld.header.login.logInButton codeblockOld.header.login.configureSnippet

// get an ID Token
    var webAuth = new auth0.WebAuth({
      clientID: '{yourClientId}',
      domain: '{yourDomain}',
      redirectUri: 'https://{yourApp}/callback',
      scope: 'openid',
      responseType: 'id_token'
    });
    // create a new instance
    var auth0Manage = new auth0.Management({
      domain: '{yourDomain}',
      token: '{yourIdToken}'
    });

Dans cet exemple, vous pouvez voir la nouvelle approche.

codeblockOld.header.login.logInButton codeblockOld.header.login.configureSnippet

// get an Access Token
    var webAuth = new auth0.WebAuth({
      clientID: '{yourClientId}',
      domain: '{yourDomain}',
      redirectUri: 'https://{yourApp}/callback',
      audience: 'https://{yourDomain}/api/v2/',
      scope: 'read:current_user',
      responseType: 'token id_token'
    });
    // create a new instance
    var auth0Manage = new auth0.Management({
      domain: '{yourDomain}',
      token: '{yourMgmtApiAccessToken}'
    });

• Demandez un jeton d’ID et un jeton d’accès dans la réponse

  responseType: ’token id_token’

• Définir Management API comme audience visée par le jeton

  audience: ’https://YOUR_DOMAIN/api/v2/’

• Demander la permission requise

  scope: ’read:current_user’

• S’authentifier auprès de Management API à l’aide du jeton d’accès

​

Changements dans la liaison des comptes

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

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

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

​

Restrictions

Les jetons d’accès utilisés pour accéder à Management API ne doivent contenir qu’une seule valeur au niveau de la demande aud. Si votre jeton contient plus d’une valeur, votre demande au Management API sera rejetée.

​

En savoir plus

• Migrate to Access Tokens for Account Linking (Migrer vers des jetons d’accès pour associer les comptes)