Permettre aux applications Java Tomcat de connecter les utilisateurs et d'accéder à Microsoft Graph.

Cet article présente une application Java Tomcat qui connecte les utilisateurs et obtient un jeton d’accès pour appeler Microsoft Graph. Elle utilise la Bibliothèque d’authentification Microsoft (MSAL) pour Java.

Le diagramme suivant illustre la topologie de l’application :

L’application cliente utilise MSAL pour Java (MSAL4J) pour se connecter à un utilisateur et obtenir un jeton d’accès pour Microsoft Graph à partir de Microsoft Entra ID. Le jeton d’accès prouve que l’utilisateur est autorisé à accéder au point de terminaison d’API Microsoft Graph tel que défini dans l’étendue.

Prérequis

• Java 8 ou version ultérieure
• Maven 3
• Un locataire Microsoft Entra ID. Pour en savoir plus, consultez Comment obtenir un locataire Microsoft Entra ID.
• Un compte d’utilisateur dans votre propre locataire Microsoft Entra ID si vous souhaitez utiliser des comptes dans votre annuaire organisationnel uniquement, c’est-à-dire en mode monolocataire. Si vous n’avez pas encore créé de compte d’utilisateur dans votre locataire, vous devez le faire avant de continuer. Pour en savoir plus, consultez Comment créer, inviter et supprimer des utilisateurs.
• Un compte d’utilisateur dans le locataire Microsoft Entra ID d’une organisation si vous souhaitez utiliser des comptes dans un annuaire organisationnel, c’est-à-dire en mode multilocataire. Cet exemple doit être modifié pour fonctionner avec un compte Microsoft personnel. Si vous n’avez pas encore créé de compte d’utilisateur dans votre locataire, vous devez le faire avant de continuer. Pour en savoir plus, consultez Comment créer, inviter et supprimer des utilisateurs.
• Un compte Microsoft personnel (par exemple, Xbox, Hotmail, Live, etc.) si vous souhaitez utiliser des comptes Microsoft personnels.

• Tomcat 9
• Visual Studio Code
• Outils Azure pour Visual Studio Code

Recommandations

• Être familiarisé avec Java/Jakarta Servlets.
• Être familiarisé avec le terminal Linux/OSX.
• jwt.ms pour inspecter vos jetons.
• Fiddler pour la supervision de votre activité réseau et la résolution des problèmes.
• Suivez le blog Microsoft Entra ID pour rester au courant des dernières évolutions.

Configurer l’exemple

Les sections suivantes vous montrent comment configurer l’exemple d’application.

Clonez ou téléchargez l’exemple de dépôt

Pour cloner l’exemple, ouvrez une fenêtre Bash et utilisez la commande suivante :

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 3-java-servlet-web-app/2-Authorization-I/call-graph

Vous pouvez également accéder au dépôt ms-identity-msal-java-samples, puis le télécharger en tant que fichier .zip et l’extraire sur votre disque dur.

Inscrivez l’exemple d’application auprès de votre locataire Microsoft Entra ID

Cet exemple contient un seul projet. Les sections suivantes vous montrent comment inscrire l’application à l’aide du Portail Azure.

Choisissez le locataire Microsoft Entra ID où vous voulez créer vos applications.

Pour choisir votre locataire, suivez les étapes ci-dessous :

1. Connectez-vous au portail Azure.

2. Si votre compte est présent dans plusieurs locataires Microsoft Entra ID, sélectionnez votre profil dans le coin du portail Azure, puis sélectionnez Changer d’annuaire pour faire correspondre votre session au locataire Microsoft Entra ID souhaité.

Inscrivez l’application (java-servlet-webapp-call-graph)

Commencez par inscrire une nouvelle application dans le portail Azure en suivant les instructions de Démarrage rapide : inscrire une application sur la plateforme d’identité Microsoft.

Procédez comme suit pour compléter l’inscription :

1. Accédez à la page Inscriptions d’applications de la plateforme d’identités Microsoft pour les développeurs.

2. Sélectionnez Nouvelle inscription.

3. Dans la page Inscrire une application qui s’affiche, saisissez les informations suivantes relatives à l’inscription de votre application :

   • Dans la section Nom, saisissez un nom d’application cohérent qui s’affichera pour les utilisateurs de l’application, par exemple java-servlet-webapp-call-graph.

   • Sous Types de comptes pris en charge, sélectionnez l’une des options suivantes :

     • Sélectionnez Comptes dans cet annuaire organisationnel uniquement si vous créez une application destinée uniquement aux utilisateurs de votre locataire, c’est-à-dire une application monolocataire.
     • Sélectionnez Comptes dans n’importe quel annuaire organisationnel si vous souhaitez que les utilisateurs de n’importe quel locataire Microsoft Entra ID puissent utiliser votre application, c’est-à-dire une application multilocataire.
     • Sélectionnez Comptes dans un annuaire organisationnel et comptes Microsoft personnels pour l’ensemble de clients le plus vaste, c’est-à-dire une application multilocataire qui prend également en charge les comptes personnels Microsoft.

   • Sélectionnez Comptes Microsoft personnels pour une utilisation uniquement par les utilisateurs de comptes Microsoft personnels (par exemple, Hotmail, Live, Skype et Xbox).

   • Dans la section URI de redirection, sélectionnez Web dans la zone de liste modifiable et entrez l’URI de redirection suivant : http://localhost:8080/msal4j-servlet-graph/auth/redirect.

4. Sélectionnez Inscrire pour créer l’application.

5. Dans la page d’inscription de l’application, recherchez et copiez la valeur ID d’application (client) pour l’utiliser ultérieurement. Vous utilisez cette valeur dans le ou les fichiers de configuration de votre application.

6. Cliquez sur Enregistrer pour enregistrer vos modifications.

7. Sur la page d’inscription de l’application, sélectionnez Certificats et secrets dans le volet de navigation pour ouvrir la page permettant de générer des secrets et de charger des certificats.

8. Dans la section Secrets client, sélectionnez Nouveau secret client.

9. Saisissez une description (par exemple, secret de l’application).

10. Sélectionnez l’une des durées disponibles : Dans 1 an, Dans 2 ans ou N’expire jamais.

11. Sélectionnez Ajouter. La valeur générée s’affiche.

12. Copiez et sauvegardez la valeur générée pour l’utiliser dans les étapes ultérieures. Vous avez besoin de cette valeur pour les fichiers de configuration de votre code. Cette valeur n’apparaîtra plus, et vous ne pouvez pas la récupérer par d’autres moyens. Veillez donc à la sauvegarder à partir du portail Azure avant d’accéder un autre écran ou à un autre volet.

13. Sur la page d’inscription de l’application, sélectionnez Autorisations d’API dans le volet de navigation pour ouvrir la page permettant d’ajouter l’accès aux API dont votre application a besoin.

14. Sélectionnez Ajouter des autorisations.

15. Vérifiez ensuite que l’onglet API Microsoft est sélectionné.

16. Dans la section API Microsoft couramment utilisées, sélectionnez Microsoft Graph.

17. Dans la section Autorisations déléguées, sélectionnez User.Read dans la liste. Utilisez la zone de recherche au besoin.

18. Sélectionnez Ajouter des autorisations.

Configurer l’application (java-servlet-webapp-call-graph) pour utiliser l’inscription de votre application

Pour configurer l’application, procédez comme suit :

1. Ouvrez le projet dans votre IDE.

2. Ouvrez le fichier ./src/main/resources/authentication.properties.

3. Recherchez la chaîne {enter-your-tenant-id-here}. Remplacez la valeur existante par l’une des valeurs suivantes :

   • L’ID de votre locataire Microsoft Entra ID si vous avez inscrit votre application avec l’option Comptes dans cette annuaire organisationnel uniquement.
   • Le mot organizations si vous avez inscrit votre application avec l’option Comptes dans un annuaire organisationnel.
   • Le mot common si vous avez inscrit votre application avec l’option Comptes dans un annuaire organisationnel et des comptes Microsoft personnels.
   • Le mot consumers si vous avez inscrit votre application avec l’option Comptes Microsoft personnels.

4. Recherchez la chaîne {enter-your-client-id-here} et remplacez la valeur existante par l’ID d’application ou l’clientId de l’application java-servlet-webapp-call-graph que vous avez copié à partir du portail Azure.

5. Recherchez la chaîne {enter-your-client-secret-here} et remplacez la valeur existante par celle que vous avez sauvegardée durant la création de l’application java-servlet-webapp-call-graph dans le portail Azure.

Générer l’exemple

Pour générer l’exemple à l’aide de Maven, accédez au répertoire contenant le fichier pom.xml pour l’exemple, puis exécutez la commande suivante :

mvn clean package

Cette commande génère un fichier .war que vous pouvez exécuter sur différents serveurs d’applications.

Exécution de l'exemple

Please confirm webapp properties
AppName : msal4j-servlet-auth-1707209552268
ResourceGroup : msal4j-servlet-auth-1707209552268-rg
Region : centralus
PricingTier : P1v2
OS : Linux
Java Version: Java 11
Web server stack: Tomcat 9.0
Deploy to slot : false
Confirm (Y/N) [Y]: [INFO] Saving configuration to pom.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  37.112 s
[INFO] Finished at: 2024-02-06T08:53:02Z
[INFO] ------------------------------------------------------------------------

<build>
    <plugins>
        <plugin>
            <groupId>com.microsoft.azure</groupId>
            <artifactId>>azure-webapp-maven-plugin</artifactId>
            <version>x.xx.x</version>
            <configuration>
                <schemaVersion>v2</schemaVersion>
                <resourceGroup>your-resourcegroup-name</resourceGroup>
                <appName>your-app-name</appName>
            ...
            </configuration>
        </plugin>
    </plugins>
</build>

az login

mvn package azure-webapp:deploy

Explorer l’exemple

Procédez comme suit pour examiner l’exemple :

1. Notez l’état de connexion ou de déconnexion qui s’affiche au centre de l’écran.
2. Sélectionnez le bouton contextuel dans le coin. Ce bouton indique Connexion lorsque vous exécutez l’application pour la première fois.
3. Suivez les instructions de la page suivante et connectez-vous avec un compte dans le locataire Microsoft Entra ID.
4. Sur l’écran de consentement, notez les portées demandées.
5. Notez que le bouton contextuel indique maintenant Déconnexion et affiche votre nom d’utilisateur.
6. Sélectionnez Détails du jeton d’ID pour voir certaines des revendications décodées du jeton d’ID.
7. Sélectionnez Appeler Graph pour effectuer un appel au point de terminaison de Microsoft Graph /me et afficher une sélection des détails utilisateur obtenus.
8. Utilisez le bouton dans le coin pour vous déconnecter.

À propos du code

Cet exemple utilise MSAL pour Java (MSAL4J) pour connecter un utilisateur et obtenir un jeton pour l’API Microsoft Graph. Il utilise le Kit de développement logiciel (SDK) Microsoft Graph pour Java pour obtenir des données à partir de Graph. Vous devez ajouter ces bibliothèques à vos projets à l’aide de Maven.

Si vous souhaitez répliquer le comportement de cet exemple, vous pouvez copier le fichier pom.xml et le contenu des dossiers helpers et authservlets dans le dossier src/main/java/com/microsoft/azuresamples/msal4j. Vous avez également besoin du fichier authentication.properties. Ces classes et ces fichiers contiennent du code générique que vous pouvez utiliser dans un large éventail d’applications. Vous pouvez également copier le reste de l’exemple, mais les autres classes et fichiers sont créés spécifiquement aux fins de l’objectif de cet exemple.

Contenu

Le tableau suivant montre le contenu de l’exemple de dossier du projet :

ConfidentialClientApplication

Une ConfidentialClientApplication instance est créée dans le fichier AuthHelper.java, comme le montre l’exemple suivant. Cet objet permet de créer l’URL d’autorisation de Microsoft Entra ID et d’échanger le jeton d’authentification contre un jeton d’accès.

// getConfidentialClientInstance method
IClientSecret secret = ClientCredentialFactory.createFromSecret(SECRET);
confClientInstance = ConfidentialClientApplication
                     .builder(CLIENT_ID, secret)
                     .authority(AUTHORITY)
                     .build();

Les paramètres suivants sont utilisés pour l’instanciation :

• ID client de l’application.
• Secret client, lequel est une exigence pour les applications clientes confidentielles.
• L’autorité Microsoft Entra ID, qui inclut votre ID de locataire Microsoft Entra.

Dans cet exemple, ces valeurs sont lues à partir du fichier authentication.properties avec un lecteur de propriétés dans le fichier Config.java.

Procédure pas-à-pas

Les étapes suivantes présentent le fonctionnement détaillé de l’application :

1. La première étape du processus de connexion consiste à envoyer une demande au point de terminaison /authorize de votre locataire Microsoft Entra ID. L’instance ConfidentialClientApplication MSAL4J est utilisée pour construire une URL de demande d’autorisation. L’application redirige le navigateur vers cette URL, où l’utilisateur se connecte.

   final ConfidentialClientApplication client = getConfidentialClientInstance();
   AuthorizationRequestUrlParameters parameters = AuthorizationRequestUrlParameters.builder(Config.REDIRECT_URI, Collections.singleton(Config.SCOPES))
           .responseMode(ResponseMode.QUERY).prompt(Prompt.SELECT_ACCOUNT).state(state).nonce(nonce).build();
   
   final String authorizeUrl = client.getAuthorizationRequestUrl(parameters).toString();
   contextAdapter.redirectUser(authorizeUrl);
   

   La liste suivante décrit les fonctionnalités de ce code :

   • AuthorizationRequestUrlParameters : les paramètres qui doivent être définis pour générer une AuthorizationRequestUrl.
   • REDIRECT_URI : où Microsoft Entra ID redirige le navigateur, avec le code d’authentification, après avoir collecté les informations d’identification de l’utilisateur. Il doit correspondre à l’URI de redirection dans l’inscription de l’application Microsoft Entra ID sur le portail Azure
   • SCOPES : les Étendues sont des autorisations demandées par l’application.
     • Normalement, les trois étendues openid profile offline_access suffisent pour recevoir une réponse du jeton d’ID.
     • Vous trouverez la liste complète des étendues demandées par l’application dans le fichier authentication.properties. Vous pouvez ajouter d’autres étendues telles que User.Read.

2. L’utilisateur reçoit une invite de connexion de Microsoft Entra ID. Si la tentative de connexion réussit, le navigateur de l’utilisateur est redirigé vers le point de terminaison de redirection de l’application. Une requête valide à ce point de terminaison contient un code d’autorisation.

3. L’instance ConfidentialClientApplication échange ensuite ce code d’autorisation contre un jeton d’ID et un jeton d’accès à partir de Microsoft Entra ID.

   // First, validate the state, then parse any error codes in response, then extract the authCode. Then:
   // build the auth code params:
   final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
           .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES)).build();
   
   // Get a client instance and leverage it to acquire the token:
   final ConfidentialClientApplication client = AuthHelper.getConfidentialClientInstance();
   final IAuthenticationResult result = client.acquireToken(authParams).get();
   

   La liste suivante décrit les fonctionnalités de ce code :

   • AuthorizationCodeParameters : paramètres qui doivent être définis pour échanger le code d’autorisation contre un ID et/ou un jeton d’accès.
   • authCode : code d’autorisation reçu au niveau du point de terminaison de redirection.
   • REDIRECT_URI : l’URI de redirection utilisé à l’étape précédente doit être repassé.
   • SCOPES : les étendues utilisées à l’étape précédente doivent être repassées.

4. Si acquireToken réussit, les revendications du jeton sont extraites. Si le contrôle nonce réussit, les résultats sont placés dans context (instance de IdentityContextData ) et enregistrés dans la session. L’application peut ensuite instancier les IdentityContextData à partir de la session (au moyen d’une instance de IdentityContextAdapterServlet) chaque fois qu’elle a besoin d’y accéder, comme montré dans le code suivant :

   // parse IdToken claims from the IAuthenticationResult:
   // (the next step - validateNonce - requires parsed claims)
   context.setIdTokenClaims(result.idToken());
   
   // if nonce is invalid, stop immediately! this could be a token replay!
   // if validation fails, throws exception and cancels auth:
   validateNonce(context);
   
   // set user to authenticated:
   context.setAuthResult(result, client.tokenCache().serialize());
   

Protéger les itinéraires

Pour en savoir plus sur la façon dont l’exemple d’application filtre l’accès aux itinéraires, consultez AuthenticationFilter.java. Dans le fichier authentication.properties, la propriété app.protect.authenticated contient les itinéraires séparés par des virgules auxquels seuls les utilisateurs authentifiés peuvent accéder, comme illustré dans l’exemple suivant :

# for example, /token_details requires any user to be signed in and does not require special roles or groups claim(s)
app.protect.authenticated=/token_details, /call_graph

Appeler Graph

Quand l’utilisateur navigue vers /call_graph, l’application crée une instance d’IGraphServiceClient (kit SDK Java Graph) et passe le jeton d’accès de l’utilisateur connecté. Le client Graph place le jeton d’accès dans les en-têtes d’Authorization de ses demandes. L’application demande ensuite au client Graph d’appeler le point de terminaison de /me pour obtenir des détails sur l’utilisateur actuellement connecté.

Si vous disposez déjà d’un jeton d’accès valide pour le service Graph avec l’étendue User.Read, vous avez uniquement besoin du code suivant pour accéder au point de terminaison /me :

//CallGraphServlet.java
User user = GraphHelper.getGraphClient(contextAdapter).me().buildRequest().get();

Étendues

Les étendues indiquent à Microsoft Entra ID le niveau d’accès demandé par l’application.

Selon les étendues demandées, Microsoft Entra ID affiche une boîte de dialogue invitant l’utilisateur à donner son consentement au moment de la connexion. Si l’utilisateur donne son consentement pour une ou plusieurs étendues et obtient un jeton, les étendues qui ont fait l’objet d’un consentement sont encodées dans le access_token obtenu.

Pour connaître les étendues demandées par l’application, consultez authentication.properties. Par défaut, l’application définit la valeur des étendues sur User.Read. Cette étendue de l’API Microsoft Graph particulière permet d’accéder aux informations de l’utilisateur connecté actuel. Le point de terminaison Graph pour accéder à ces informations est https://graph.microsoft.com/v1.0/me. Toutes les demandes valides adressées à ce point de terminaison doivent contenir un access_token qui comprend l’étendue User.Read dans l’en-tête Authorization.

Plus d’informations

• Bibliothèque d’authentification Microsoft (MSAL) pour Java
• Plate-forme d’identité Microsoft (Microsoft Entra ID pour les développeurs)
• Démarrage rapide : Inscrire une application à l’aide de la plateforme d’identités Microsoft
• Comprendre les expériences de consentement à l’application Microsoft Entra ID
• Comprendre le consentement de l’utilisateur et de l’administrateur
• Exemples de code MSAL