Exemples de cas d’utilisation : Portées and claims

Découvrez, à l’aide d’exemples pratiques, comment les portées OAuth 2.0 et les claims JWT déterminent les données et les actions auxquelles les applications peuvent accéder au nom des utilisateurs.

Dans ces exemples, nous utilisons le flux du code d’autorisation pour authentifier un utilisateur et demander les permissions (portées) et les jetons nécessaires. Pour en savoir plus sur les paramètres de la requête ou sur la façon d’implémenter entièrement ce flux, consultez notre tutoriel : Ajouter la connexion aux applications Web régulières.

​

Authentifier un utilisateur et demander des claims standard

Dans cet exemple, nous voulons authentifier un utilisateur et obtenir des renseignements sur celui-ci qui nous permettront de personnaliser notre interface utilisateur. Pour ce faire, nous devons obtenir un ID token qui contient le nom de l’utilisateur, son nickname, sa photo de profil et son adresse courriel.

1. Lancez le flux d’authentification en envoyant l’utilisateur à l’URL d’autorisation :

   Notez que, dans cet exemple :

   • Le paramètre response_type comprend une valeur :

     • code : comme nous utilisons le flux d’application Web régulière, notre requête initiale vise à obtenir un authorization code; lorsque nous demanderons nos jetons à l’aide de ce code, nous recevrons le ID token dont nous avons besoin pour l’authentification.

   • Le paramètre scope comprend trois valeurs; les portées OIDC demandées :

     • openid : pour indiquer que l’application a l’intention d’utiliser OIDC pour vérifier l’identité de l’utilisateur.
     • profile : pour obtenir name, nickname et picture.
     • email : pour obtenir email et email_verified.

2. Une fois que l’utilisateur a donné son consentement (au besoin) et qu’Auth0 l’a redirigé vers votre application, demandez des jetons.

3. Extrayez le ID token de la réponse et décodez-le. Vous devriez voir les claims suivants :

   Votre application peut maintenant récupérer les attributs de l’utilisateur et les utiliser pour personnaliser votre interface utilisateur.

​

Demander un accès à une API personnalisée

Dans cet exemple, nous demandons une portée personnalisée pour une API de calendrier qui autorisera l’application appelante à lire les rendez-vous de l’utilisateur. Pour ce faire, nous voulons obtenir un jeton d’accès contenant la portée appropriée pour lire les rendez-vous à partir de l’API. Notez que la demande d’un jeton d’accès ne dépend pas de la demande d’un ID Token.

Avant d’utiliser une API personnalisée, vous devez savoir quelles portées sont disponibles pour l’API que vous appelez. Si l’API personnalisée est sous votre contrôle, vous devez enregistrer à la fois votre application et l’API auprès d’Auth0 et définir les portées de votre API à l’aide de l’Auth0 Dashboard. Vous pouvez aussi utiliser des permissions définies pour personnaliser l’invite de consentement pour vos utilisateurs.

1. Lancez le flux d’autorisation en envoyant l’utilisateur vers l’URL d’autorisation :

   Remarquez que, dans cet exemple :

   • Le paramètre response_type comprend toujours une valeur :

     • code : puisque nous utilisons le flux d’application web régulière, notre demande initiale vise à obtenir un code d’autorisation; lorsque nous demanderons nos jetons à l’aide de ce code, nous recevrons le jeton d’accès que nous pourrons utiliser pour faire une requête à notre API.

   • le paramètre scope comprend une valeur, soit la portée d’API demandée :

     • read:appointments : pour nous permettre de lire les rendez-vous de l’utilisateur à partir de l’API.

   • Le paramètre audience est nouveau et comprend une valeur :

     • L’identifiant unique de l’API à partir de laquelle nous voulons lire les rendez-vous de l’utilisateur.

2. Comme dans l’exemple précédent, une fois que l’utilisateur a donné son consentement (au besoin) et qu’Auth0 a redirigé l’utilisateur vers votre application, demandez des jetons.

3. Extrayez le jeton d’accès de la réponse et faites une requête à l’API en utilisant le jeton d’accès comme informations d’authentification.

​

Authentifier un utilisateur et demander des claims standards ainsi qu’un accès à une API personnalisée

Dans cet exemple, nous combinons nos deux exemples précédents pour authentifier un utilisateur, demander des claims standards et aussi demander une portée personnalisée pour une API de calendrier qui permettra à l’application appelante de lire les rendez-vous de l’utilisateur. Pour ce faire, obtenez deux jetons :

• Un ID token qui contient :

  • Le nom de l’utilisateur
  • Le pseudonyme
  • La photo de profil
  • Les renseignements sur le courriel

• Un jeton d’accès qui contient la portée appropriée pour lire les rendez-vous à partir de l’API. Notez que la demande d’un jeton d’accès ne dépend pas de la demande d’un ID token.

Avant d’utiliser une API personnalisée, vous devez savoir quelles portées sont offertes pour l’API que vous appelez. Si l’API personnalisée est sous votre contrôle, vous devez enregistrer à la fois votre application et votre API auprès d’Auth0, puis définir les portées de votre API à l’aide du Auth0 Dashboard. Vous pouvez aussi utiliser des permissions définies pour personnaliser l’invite de consentement pour vos utilisateurs.

1. Lancez le flux d’authentification en envoyant l’utilisateur vers l’URL d’autorisation :

   Notez que, dans cet exemple :

   • Le paramètre response_type comprend toujours une valeur :

     • code : puisque nous utilisons le flux d’application Web régulière, notre requête initiale vise un code d’autorisation; lorsque nous demanderons nos jetons à l’aide de ce code, nous recevrons à la fois l’ID token dont nous avons besoin pour l’authentification et le jeton d’accès que nous pourrons utiliser pour effectuer une requête vers notre API.

   • Le paramètre scope est utilisé à la fois pour les portées OIDC et les portées d’API; il comprend donc maintenant quatre valeurs :

     • openid : pour indiquer que l’application a l’intention d’utiliser OIDC pour vérifier l’identité de l’utilisateur.
     • profile : pour obtenir name, nickname et picture.
     • email : pour obtenir email et email_verified.
     • read:appointments : pour nous permettre de lire les rendez-vous de l’utilisateur à partir de l’API.

   • le paramètre audience comprend une valeur :

     • L’identificateur unique de l’API à partir de laquelle nous voulons lire les rendez-vous de l’utilisateur

2. Comme dans les exemples précédents, après que l’utilisateur a donné son consentement (au besoin) et qu’Auth0 a redirigé l’utilisateur vers votre application, demandez les jetons.

3. Extrayez l’ID token de la réponse, décodez-le, récupérez les attributs de l’utilisateur et utilisez-les pour personnaliser votre UI.

4. Extrayez le jeton d’accès de la réponse et effectuez une requête vers l’API en utilisant le jeton d’accès comme informations d’identification.

​

Ajouter des claims personnalisés à un jeton

Dans cet exemple, nous ajoutons la couleur préférée d’un utilisateur et sa méthode de contact privilégiée à l’ID Token. Pour ce faire, nous créons une Action afin de personnaliser l’ID token en y ajoutant ces claims. Une fois ajoutés, nous pourrons aussi récupérer les claims personnalisés en appelant le point de terminaison /userinfo (bien que l’Action ne s’exécute que pendant le processus d’authentification).

Auth0 prend en charge les claims avec et sans espace de noms, mais certaines restrictions s’appliquent (consultez Restrictions générales). Pour éviter les collisions de noms, nous recommandons d’utiliser des claims avec espace de noms. En cas de collision, la transaction n’échouera pas, mais votre claim personnalisé ne sera pas ajouté à vos jetons.

Supposons que :

• À un certain moment, l’utilisateur a sélectionné email comme méthode preferred_contact et red comme valeur de favorite_color, et que nous l’avons enregistré dans le user_metadata de l’utilisateur.
• Nous avons utilisé la Management API ou le Dashboard pour définir des renseignements propres à l’application pour cet utilisateur.

Dans ce cas, le profil utilisateur normalisé stocké par Auth0 est :

{
  "email": "[e-mail]",
  "email_verified": true,
  "user_id": "custom|123",
  "favorite_color": "blue",
  "user_metadata": {
    "preferred_contact": "email"
  }
}

Pour ce profil, Auth0 retournerait normalement à votre application les claims suivants de l’ID Token :

{
  "email": "[e-mail]",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970
}

Notez que dans cet exemple :

• Le claim sub contient la valeur de la propriété user_id.
• Ni les propriétés favorite_color ni user_metadata ne sont présentes, car OpenID Connect (OIDC) ne définit pas de claims standard pour représenter favorite_color ou user_metadata.

Pour recevoir les données personnalisées, nous devrons créer une nouvelle Action afin de personnaliser le jeton avec des claims personnalisés qui représentent ces propriétés du profil utilisateur.

1. Accédez à Auth0 Dashboard > Actions > Library, puis sélectionnez Build Custom.

2. Saisissez un Name descriptif pour votre Action (par exemple, Add user metadata to tokens), sélectionnez le trigger Login / Post Login puisque vous ajouterez l’Action au Login flow, puis sélectionnez Create.

3. Repérez le Actions Code Editor, copiez-y le code Javascript suivant, puis sélectionnez Save Draft pour enregistrer vos modifications :

   exports.onExecutePostLogin = async (event, api) => {
     const namespace = 'https://myapp.example.com';
     const { favorite_color, preferred_contact } = event.user.user_metadata;
   
     if (event.authorization) {
       // Définir les claims 
       api.idToken.setCustomClaim(`${namespace}/favorite_color`, favorite_color);
       api.idToken.setCustomClaim(`${namespace}/preferred_contact`, preferred_contact);
     }
   };
   

4. Dans la barre latérale du Actions Code Editor, sélectionnez Test (icône de lecture), puis sélectionnez Run pour tester votre code.

5. Lorsque vous êtes prêt à mettre l’Action en service, sélectionnez Deploy.

Enfin, ajoutez l’Action que vous avez créée au Login Flow. Pour savoir comment attacher des Actions à des Flows, consultez la section “Attach the Action to a flow” dans Write Your First Action.

Une fois cette Action activée, Auth0 inclura les claims personnalisés favorite_color et preferred_contact dans le ID Token :

{
  "email": "[e-mail]",
  "email_verified": true,
  "iss": "https://my-domain.auth0.com/",
  "sub": "custom|123",
  "aud": "my_client_id",
  "iat": 1311280970,
  "exp": 1311281970,
  "https://myapp.example.com/favorite_color": "red",
  "https://myapp.example.com/preferred_contact": "email"
}

Lorsque vous créez votre Action, assurez-vous de définir une logique qui détermine à quel moment inclure des claims supplémentaires. Injecter des claims personnalisées dans chaque ID Token émis n’est pas idéal.

Cet exemple montre des claims personnalisées ajoutées à un ID Token à l’aide de la méthode api.idToken.setCustomClaims. Pour ajouter ces claims à un jeton d’accès, utilisez la méthode api.accessToken.setCustomClaim.

Pour en savoir plus sur l’objet Event associé au trigger, consultez Actions Triggers: post-login - Event Object. Pour en savoir plus sur les jetons, consultez Tokens.

​

En savoir plus

• OpenID Connect Scopes
• Créer des claims personnalisés
• API Scopes
• Configurer l’API logique pour plusieurs API