Autoriser l’accès aux API avec la bibliothèque d’authentification Microsoft

5 minutes

Vous pouvez désormais connecter les utilisateurs de votre entreprise à l’application web. Vous souhaitez à présent extraire des informations de leur profil d’employé (poste, adresse e-mail professionnelle, etc.) et les afficher dans la page. Vous constatez que l’API Microsoft Graph permet d’accéder aux données associées aux utilisateurs.

Dans cette unité, vous voyez comment utiliser MSAL pour obtenir un accès autorisé aux services Microsoft, notamment l’API Microsoft Graph.

Autorisations et étendues de l’API

Les services web sécurisés par Microsoft Entra ID définissent un ensemble d’autorisations qui permettent d’accéder aux fonctionnalités d’une API et aux données exposées par ce service. Une application peut demander ces autorisations aux utilisateurs et administrateurs. Ces derniers doivent approuver la demande avant que l’application ne puisse accéder aux données ou agir pour le compte d’un utilisateur. Par exemple, Microsoft Graph a défini des autorisations pour effectuer les tâches suivantes, entre autres :

Lire le calendrier d’un utilisateur
Écrire dans le calendrier d’un utilisateur
Envoi de messages en tant qu’utilisateur

Les utilisateurs et les administrateurs peuvent exercer un contrôle et savoir à quelles données l’application peut accéder. Pour que votre application puisse accéder à une API sécurisée par Microsoft, vous devez fournir à l’application les autorisations nécessaires pour effectuer les actions.

Microsoft Entra ID prend en charge deux types d’autorisations : les autorisations déléguées et les autorisations d’application.

Les autorisations déléguées sont utilisées par les applications pour lesquelles un utilisateur est connecté et présent. Pour ces applications, l’utilisateur ou un administrateur consent aux autorisations demandées par l’application. L’application se voit déléguer la permission d’agir en tant qu’utilisateur connecté lorsqu’elle effectue des appels vers l’API cible. Certaines autorisations à privilèges élevés exigent le consentement de l’administrateur.
Les autorisations d’application sont utilisées par les applications qui s’exécutent sans qu’un utilisateur soit connecté et présent (les applications qui s’exécutent en tant que services ou démons en arrière-plan, par exemple). Seul un administrateur peut consentir aux permissions d’application.

Vous pouvez attribuer ces autorisations d’API au moment de l’inscription de votre application dans le portail Azure.

Étendues

Microsoft Entra ID implémente OAuth 2.0, protocole d’autorisation par le biais duquel une application peut accéder à des ressources hébergées sur le web au nom d’un utilisateur.

Dans OAuth 2.0, ces types de jeux d’autorisations sont appelés des étendues. Lors d’une demande d’autorisation à Microsoft Entra ID, une application demande les autorisations dont elle a besoin en spécifiant l’autorisation dans le paramètre de requête scope de la demande. Par exemple, la valeur d’étendue https://graph.microsoft.com/Calendars.Read est utilisée pour demander l’autorisation de lire les calendriers de l’utilisateur dans Microsoft Graph.

Acquérir des jetons d’accès avec MSAL

Les jetons d’accès permettent aux applications clientes d’appeler de façon sécurisée les API web protégées par Microsoft Entra ID. Il existe plusieurs façons d’acquérir un jeton d’accès avec la bibliothèque d’authentification Microsoft (MSAL). 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.

Plusieurs des méthodes d’acquisition de jetons de MSAL nécessitent un paramètre scopes, une liste de chaînes déclarant les autorisations souhaitées et les ressources demandées.

Modèle d’appel recommandé pour les applications web

MSAL met en cache un jeton après son acquisition. Pour les applications web qui utilisent le flux du code d’autorisation OpenID Connect, le modèle recommandé dans les contrôleurs consiste à :

Essayez d’abord d’obtenir un jeton silencieusement à partir du cache, avant de tenter de l’acquérir par d’autres moyens. Le code suivant est un extrait de l’implémentation de la méthode acquireTokenSilently dans la classe AuthHelper.

final SilentParameters parameters = SilentParameters
                                        .builder(Collections.singleton(Config.SCOPES), context.getAccount())
                                        .build();

final ConfidentialClientApplication client = getConfidentialClientInstance();

client.tokenCache().deserialize(context.getTokenCache());

final IAuthenticationResult result = client.acquireTokenSilently(parameters).get();

S’il n’y a aucun jeton dans le cache et que la demande de jeton silencieuse ne parvient pas à obtenir un jeton, vous pouvez acquérir le jeton à l’aide du flux du code d’autorisation :

final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                                                    .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES))
                                                    .build();

final IAuthenticationResult result = app.acquireToken(authParams).get();

MSAL peut aussi actualiser un jeton quand celui-ci arrive à expiration (étant donné que le cache de jetons contient également un jeton d’actualisation).

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 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 AuthenticationResult retourné par MSAL expose :

Le jeton d’accès pour l’API web.
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é.
Les étendues pour lesquelles le jeton a été émis.
L’ID unique de l’utilisateur.

Présentation de Microsoft Graph

L’API Microsoft Graph offre un seul point de terminaison, https://graph.microsoft.com, pour fournir un accès aux données/insights riches et centrés sur les personnes dans le cloud Microsoft. Vous pouvez utiliser des API REST ou des kits SDK pour accéder au point de terminaison et créer des applications qui prennent en charge des scénarios Microsoft 365, couvrant la productivité, la collaboration, l’éducation, l’intelligence des personnes et du lieu de travail, etc. Microsoft Graph comprend également un ensemble puissant de services qui gèrent l’identité des utilisateurs et des appareils.

Par exemple, vous pouvez lire les propriétés d’un utilisateur connecté en accédant au point de terminaison https://graph.microsoft.com/v1.0/me.