Partager via

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 règle générale, le moyen utilisé pour acquérir un jeton dépend de la nature de l’application : ce peut être une application cliente publique, comme une application de bureau ou mobile, mais aussi une application cliente confidentielle, telle qu’une application web, une API web ou une application de 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 de 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 d’Azure AD pour développeurs (v1.0) et de la Plateforme d’identités Microsoft. Le protocole v2.0 utilise des étendues au lieu de ressources dans les demandes. 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.

Il est également possible d’accéder à des ressources v1.0 dans MSAL. Pour plus d’informations, consultez Étendues pour une application v1.0.

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, cependant, dans lesquels vous ne devez pas essayer d’acquérir silencieusement un jeton :

  • Flux d’informations d’identification du client qui n’utilise pas le cache de jetons 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

En règle générale, 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 comme les applications de bureau et mobiles, 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.
  • Obtenir 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. Azure AD renvoie alors un jeton à l’appareil sans navigateur.

Applications clientes confidentielles

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

  • Acquérir des jetons pour l’application elle-même et non pour un utilisateur, à l’aide du flux d’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.
  • 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 utilisent généralement ce mécanisme, ce qui permet à l’utilisateur de se connecter à l’aide d’Open ID Connect, puis d’accéder aux API web pour le compte de l’utilisateur.

Résultats d’authentification

Quand votre client demande un jeton d’accès, Azure AD retourne é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 d’Azure AD B2B), l’ID de locataire correspond au locataire invité, pas au 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.