Acquérir et mettre en cache des jetons à l’aide de la bibliothèque d’authentification Microsoft (MSAL)

  • Article

Les jetons d’accès permettent aux clients d’appeler de manière sécurisée des API web protégées par Azure. Il existe plusieurs façons d’acquérir un jeton en utilisant la bibliothèque d’authentification Microsoft (MSAL). Certaines nécessitent une interaction de l’utilisateur via un navigateur web, d’autres n’en demandent aucune. En général, la méthode utilisée pour acquérir un jeton dépend de la nature de l’application : application cliente publique (bureau ou mobile) ou application cliente confidentielle (application web, API web ou application démon).

MSAL met en cache un jeton après son acquisition. Le code de votre application doit d’abord essayer d’obtenir un jeton silencieusement à partir du cache, avant de tenter de l’acquérir par d’autres moyens.

Vous pouvez également effacer le cache des jetons en supprimant les comptes du cache. Le cookie de session qui se trouve dans le navigateur n’est quant à lui pas supprimé.

Étendues lors de l’acquisition de jetons

Les étendues correspondent aux autorisations qu’une API web expose pour que les applications clientes puissent demander à y accéder. Les applications clientes demandent le consentement de l’utilisateur pour ces étendues lors des demandes d’authentification pour obtenir des jetons permettant d’accéder aux API web. MSAL vous permet d’obtenir des jetons pour accéder aux API de la plateforme d’identité de Microsoft. Le protocole v2.0 utilise des étendues au lieu de ressources dans les requêtes. Selon la configuration de la version de jeton acceptée par l’API web, le point de terminaison v2.0 retourne un jeton d’accès à MSAL.

Plusieurs méthodes d’acquisition de jetons de MSAL nécessitent un paramètre scopes. Le paramètre scopes représente une liste de chaînes qui déclarent les autorisations souhaitées et les ressources demandées. Les autorisations Microsoft Graph sont des étendues bien connues.

Demander des étendues pour une API web

Quand votre application a besoin de demander un jeton d’accès avec des autorisations spécifiques pour une API de ressource, passez les étendues contenant l’URI de l’ID d’application de l’API au format <app ID URI>/<scope>.

Voici quelques exemples de valeurs d’étendue pour différentes ressources :

  • API Microsoft Graph : https://graph.microsoft.com/User.Read
  • API web personnalisée : api://11111111-1111-1111-1111-111111111111/api.read

Le format de la valeur d’étendue varie en fonction de la ressource (l’API) qui reçoit le jeton d’accès, et des valeurs de revendication audqu’elle accepte.

Pour Microsoft Graph uniquement, l’étendue user.read mappe à https://graph.microsoft.com/User.Read, et les deux formats d’étendue peuvent être utilisés indifféremment.

Certaines API web, comme l’API Azure Resource Manager (https://management.core.windows.net/) attendent une barre oblique (/) de fin dans la revendication d’audience (aud) du jeton d’accès. Dans ce cas, transmettez l’étendue sous la forme https://management.core.windows.net//user_impersonation, en incluant la double barre oblique (//).

D’autres API peuvent exiger qu’aucun schéma ou hôte ne soit inclus dans la valeur d’étendue, et que seuls l’ID d’application (un GUID) et le nom de l’étendue soient attendus, par exemple :

11111111-1111-1111-1111-111111111111/api.read

Conseil

Si la ressource en aval n’est pas sous votre contrôle, vous devrez peut-être essayer différents formats de valeur d’étendue (par exemple, avec/sans schéma et hôte) si vous recevez 401 ou d’autres erreurs lors du passage du jeton d’accès à la ressource.

À mesure que les fonctionnalités fournies par votre application, ou les exigences, changent, vous pouvez au besoin demander des autorisations supplémentaires en utilisant le paramètre d’étendue. De telles étendues dynamiques permettent à vos utilisateurs de fournir un consentement incrémentiel aux étendues.

Par exemple, vous pouvez connecter l’utilisateur, mais lui refuser au départ l’accès aux ressources. Plus tard, vous pouvez lui donner la possibilité de consulter son calendrier, en demandant l’étendue du calendrier dans la méthode d’acquisition de jeton et en obtenant le consentement de l’utilisateur pour ce faire. Par exemple, en demandant les étendues https://graph.microsoft.com/User.Read et https://graph.microsoft.com/Calendar.Read.

Acquisition silencieuse de jetons (à partir du cache)

MSAL gère un cache de jetons (ou deux caches pour les applications clientes confidentielles) et met en cache un jeton après qu’il a été acquis. Dans de nombreux cas, une tentative d’obtention silencieuse d’un jeton acquiert un autre jeton avec d’autres étendues basées sur un jeton dans le cache. MSAL est également capable d’actualiser un jeton quand il arrive à expiration (étant donné que le cache de jetons contient également un jeton d’actualisation).

Le code source de l’application doit d’abord essayer d’obtenir un jeton silencieusement à partir du cache. Si l’appel de méthode retourne une erreur ou exception de type « Interface utilisateur requise », essayez d’acquérir un jeton par d’autres moyens.

Il existe deux flux pour lesquels vous ne devez pas tenter d’acquérir silencieusement un jeton :

  • Le flux des informations d’identification du client, qui n’utilise pas le cache de jetons d’utilisateur, mais un cache de jetons d’application. Cette méthode se charge de vérifier le cache de jetons d’application avant d’envoyer une demande au service d’émission de jeton de sécurité (STS).
  • Le flux du code d’autorisation dans les applications web, car il accepte un code que l’application a obtenu en connectant l’utilisateur et en lui demandant son consentement pour d’autres d’étendues. Dans la mesure où du code, et non un compte, est passé comme paramètre, la méthode ne peut pas examiner le cache avant d’accepter le code, ce qui lance un appel au service.

Pour les applications web qui utilisent le flux du code d’autorisation OpenID Connect, le modèle recommandé dans les contrôleurs consiste à :

  • Instancier une application cliente confidentielle avec un cache de jetons avec sérialisation personnalisée.
  • Acquérir le jeton en utilisant le flux du code d’autorisation

Acquisition des jetons

La méthode d’acquisition d’un jeton varie selon qu’il s’agit d’une application cliente publique ou confidentielle.

Applications clientes publiques

Dans les applications clientes publiques (bureau et mobile), vous pouvez :

  • Obtenir des jetons de façon interactive, en obligeant l’utilisateur à se connecter via une interface utilisateur ou une fenêtre contextuelle.
  • Obtenir un jeton de manière silencieuse pour l’utilisateur connecté en utilisant l’authentification Windows intégrée (IWA/Kerberos) si l’application de bureau s’exécute sur un ordinateur Windows joint à un domaine ou à Azure.
  • Obtenez un jeton avec un nom d’utilisateur et un mot de passe dans les applications clientes de bureau .NET Framework (non recommandé). Vous n’utilisez pas de nom d’utilisateur/mot de passe dans les applications clientes confidentielles.
  • Obtenir un jeton via le flux de code d’appareil dans les applications qui s’exécutent sur des appareils ne disposant pas de navigateur web. L’utilisateur reçoit une URL et un code. Il accède alors à un navigateur web sur un autre appareil, puis entre le code pour se connecter. Microsoft Entra ID renvoie ensuite un jeton au périphérique sans navigateur.

Applications clientes confidentielles

Pour les applications clientes confidentielles (application web, API web ou application démon, comme un service Windows), vous pouvez ;

  • Vous acquérez des jetons pour l’application elle-même et non pour un utilisateur, à l’aide du flux des informations d’identification du client. Cette technique peut être utilisée pour des outils de synchronisation ou des outils qui traitent des utilisateurs en général, et non un utilisateur en particulier.
  • Utilisez le flux OBO (on-behalf-of) pour qu’une API web appelle une API pour le compte de l’utilisateur. L’application est identifiée avec des informations d’identification du client, afin d’acquérir un jeton basé sur une assertion d’utilisateur (par exemple, SAML ou un jeton JWT). Ce flux est utilisé par les applications qui ont besoin d’accéder aux ressources d’un utilisateur particulier dans des appels de service à service. Les jetons doivent être mis en cache en fonction de la session et non de l’utilisateur.
  • Vous acquérez des jetons à l’aide du flux du code d’autorisation dans les applications web une fois que l’utilisateur s’est connecté par le biais de l’URL de la demande d’autorisation. L'application OpenID Connect utilise généralement ce mécanisme, qui permet à l'utilisateur de se connecter à l'aide d'OpenID Connect, puis d'accéder aux API Web au nom de l'utilisateur. Les jetons peuvent être mis en cache en fonction de l’utilisateur ou de la session. Si vous mettez en cache des jetons en fonction de l’utilisateur, nous vous recommandons de limiter la durée de vie de la session, de sorte que Microsoft Entra ID puisse vérifier fréquemment l’état des stratégies d’accès conditionnel.

Résultats d’authentification

Lorsque votre client demande un jeton d'accès, Microsoft Entra ID renvoie également un résultat d'authentification qui inclut des métadonnées sur le jeton d'accès. Ces informations incluent le délai d’expiration du jeton d’accès et les étendues dans lesquelles il est valide. Ces données permettent à votre application d’effectuer une mise en cache intelligente des jetons d’accès sans avoir à les analyser eux-mêmes. Le résultat d’authentification expose :

  • Le jeton d’accès pour que l’API web accède aux ressources. Cette chaîne est généralement un jeton JWT encodé en Base64, mais le client ne doit jamais regarder à l’intérieur du jeton d’accès. La stabilité du format n’est pas garantie et ce dernier peut être chiffré pour la ressource. L’écriture humaine de code qui dépend du contenu des jetons d’accès sur le client constitue l’une des sources les plus courantes d’erreurs et de ruptures de logique client.
  • Le jeton d’ID pour l’utilisateur (un jeton JWT).
  • L’expiration du jeton, qui indique la date/heure auxquelles le jeton expire.
  • L’ID de locataire contient le locataire dans lequel l’utilisateur a été trouvé. Pour les utilisateurs invités (scénarios Microsoft Entra B2B), l’ID de locataire est le locataire invité et non le locataire unique. Quand le jeton est remis au nom d’un utilisateur, le résultat d’authentification contient également des informations sur cet utilisateur. Pour les flux de clients confidentiels où les jetons sont demandés sans aucun utilisateur (pour l’application), ces informations sur l’utilisateur sont manquantes ou inconnues.
  • Les étendues pour lesquelles le jeton a été émis.
  • L’ID unique de l’utilisateur.

(Avancé) Accès aux jetons mis en cache de l’utilisateur dans les applications et services en arrière-plan

Vous pouvez utiliser l’implémentation du cache de jeton MSAL pour permettre aux applications, aux API et aux services en arrière-plan d’utiliser le cache de jeton d’accès afin de continuer à agir au nom des utilisateurs en leur absence. Cela s’avère particulièrement utile si les applications et les services en arrière-plan doivent continuer à travailler au nom de l’utilisateur une fois que celui-ci a quitté l’application web front-end.

Aujourd’hui, la plupart des processus en arrière-plan utilisent des autorisations d’application lorsqu’ils doivent travailler avec les données d’un utilisateur sans que l’utilisateur soit présent pour l’authentification ou la réauthentification. Étant donné que les autorisations d’application requièrent souvent un consentement de l’administrateur, ce qui nécessite une élévation des privilèges, un conflit inutile est décelé, car le développeur n’avait pas l’intention d’obtenir une autorisation au-delà de celle consentie à l’origine par l’utilisateur pour son application.

Cet exemple de code sur GitHub montre comment éviter ce conflit inutile en accédant au cache de jeton MSAL à partir d’applications en arrière-plan :

Accès au cache de jeton de l’utilisateur connecté à partir d’applications, d’API et de services en arrière-plan

Voir aussi

Plusieurs des plateformes que MSAL prend en charge font l’objet d’informations supplémentaires relatives au cache de jeton dans la documentation de la bibliothèque de cette plateforme. Par exemple :