Activer la connexion pour les applications Java Tomcat à l’aide de l’ID Microsoft Entra
Cet article illustre une application Java Tomcat qui connecte des utilisateurs à votre locataire Microsoft Entra ID à l’aide de 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 connecter des utilisateurs à leur propre locataire d’ID Microsoft Entra et obtenir un jeton d’ID à partir de l’ID Microsoft Entra. Le jeton d’ID prouve qu’un utilisateur est authentifié auprès de ce locataire. L’application protège ses itinéraires en fonction de l’état d’authentification de l’utilisateur.
Prérequis
- JDK version 8 ou ultérieure
- Maven 3
- Un locataire Microsoft Entra ID. Pour plus d’informations, 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 créé de compte d’utilisateur dans votre locataire Microsoft Entra ID, vous devez le faire avant de continuer. Pour plus d’informations, 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 n’importe quel annuaire organisationnel, c’est-à-dire en mode multilocataire. Vous devez modifier cet exemple pour qu’il fonctionne avec un compte Microsoft personnel. Si vous n’avez pas encore créé de compte d’utilisateur dans votre locataire Microsoft Entra ID, vous devez le faire avant de continuer. Pour plus d’informations, consultez Comment créer, inviter et supprimer des utilisateurs.
- Un compte Microsoft personnel ( par exemple, Xbox, Hotmail, Live, et ainsi de suite) si vous souhaitez utiliser des comptes Microsoft personnels.
Recommandations
- Certaines familiarités avec java / Jakarta Servlets.
- Vous connaissez bien le terminal Linux/OSX ou Windows PowerShell.
- 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 à jour avec les derniers développements.
Configurer l’exemple
Les sections suivantes vous montrent comment configurer l’exemple d’application.
Cloner ou télécharger l’exemple de référentiel
Pour cloner l’exemple, ouvrez une fenêtre Bash et utilisez la commande suivante :
git clone https://github.com/Azure-Samples/ms-identity-java-servlet-webapp-authentication.git
cd 1-Authentication/sign-in
Vous pouvez également accéder au référentiel ms-identity-java-servlet-webapp-authentication , puis le télécharger en tant que fichier .zip et l’extraire sur votre disque dur.
Important
Pour éviter les limitations de longueur du chemin de fichier sur Windows, clonez ou extrayez le référentiel dans un répertoire près de la racine de votre disque dur.
Inscrire l’exemple d’application auprès de votre locataire Microsoft Entra ID
Il existe un projet dans cet exemple. Pour inscrire l’application sur le Portail Azure, vous pouvez suivre les étapes de configuration manuelles ou utiliser un script PowerShell. Le script effectue les tâches suivantes :
- Crée les applications Microsoft Entra ID et les objets associés, tels que les mots de passe, les autorisations et les dépendances.
- Modifie les fichiers de configuration du projet.
- Par défaut, configure une application qui fonctionne avec des comptes dans votre annuaire organisationnel uniquement.
Pour exécuter le script PowerShell, procédez comme suit :
Sur Windows, ouvrez PowerShell et accédez à la racine du répertoire cloné.
Utilisez la commande suivante pour définir la stratégie d’exécution pour PowerShell :
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process -Force
Utilisez les commandes suivantes pour exécuter le script de configuration :
cd .\AppCreationScripts\ .\Configure.ps1
Remarque
D’autres méthodes d’exécution des scripts sont décrites dans les scripts de création d’application. Les scripts fournissent également un guide pour l’inscription, la configuration et la suppression automatisées des applications, ce qui peut vous aider dans vos scénarios CI/CD.
Configurer l’application pour utiliser votre inscription d’application
Pour configurer l’application, procédez comme suit :
Remarque
Dans les étapes suivantes, ClientID
il s’agit de la même chose que Application ID
ou AppId
.
Ouvrez le projet dans votre IDE.
Ouvrez le fichier ./src/main/resources/authentication.properties .
Recherchez la chaîne
{enter-your-tenant-id-here}
. Remplacez la valeur existante par l’une des valeurs suivantes :- Votre ID de locataire Microsoft Entra ID si vous avez inscrit votre application auprès des comptes dans cette option d’annuaire organisationnel uniquement .
- Mot
organizations
si vous avez inscrit votre application auprès des comptes dans n’importe quelle option d’annuaire organisationnel . - Mot
common
si vous avez inscrit votre application auprès des comptes dans n’importe quel annuaire organisationnel et option de comptes Microsoft personnels. - Mot
consumers
si vous avez inscrit votre application avec l’option Comptes Microsoft personnels.
Recherchez la chaîne
{enter-your-client-id-here}
et remplacez la valeur existante par l’ID d’application ouclientId
l’applicationjava-servlet-webapp-authentication
copiée à partir du Portail Azure.Recherchez la chaîne
{enter-your-client-secret-here}
et remplacez la valeur existante par la valeur que vous avez enregistrée lors de la création de l’applicationjava-servlet-webapp-authentication
, 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 de 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
Les sections suivantes vous montrent comment déployer l’exemple sur Azure App Service.
Prérequis
Plug-in Maven pour les applications Azure App Service
Si Maven n’est pas votre outil de développement préféré, consultez les didacticiels similaires suivants qui utilisent d’autres outils :
Configurer le plug-in Maven
Lorsque vous déployez sur Azure App Service, le déploiement utilise automatiquement vos informations d’identification Azure à partir d’Azure CLI. Si Azure CLI n’est pas installé localement, le plug-in Maven s’authentifie avec OAuth ou la connexion de l’appareil. Pour plus d’informations, consultez Authentification avec les plug-ins Maven.
Pour configurer le plug-in, procédez comme suit :
Exécutez la commande suivante pour configurer le déploiement. Cette commande vous aide à configurer le système d’exploitation Azure App Service, la version Java et la version tomcat.
mvn com.microsoft.azure:azure-webapp-maven-plugin:2.12.0:config
Pour créer une configuration d’exécution, appuyez sur Y, puis appuyez sur Entrée.
Pour Définir la valeur du système d’exploitation, appuyez sur 1 pour Windows ou 2 pour Linux, puis appuyez sur Entrée.
Pour Définir la valeur de javaVersion, appuyez sur 2 pour Java 11, puis appuyez sur Entrée.
Pour Définir la valeur pour webContainer, appuyez sur 4 pour Tomcat 9.0, puis appuyez sur Entrée.
Pour Définir la valeur de pricingTier, appuyez sur Entrée pour sélectionner le niveau P1v2 par défaut.
Pour Confirmer, appuyez sur Y, puis appuyez sur Entrée.
L’exemple suivant montre la sortie du processus de déploiement :
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] ------------------------------------------------------------------------
Une fois que vous avez confirmé vos choix, le plug-in ajoute l’élément de plug-in et les paramètres requis au fichier de pom.xml de votre projet pour configurer votre application à exécuter dans Azure App Service.
La partie pertinente du fichier pom.xml doit ressembler à l’exemple suivant :
<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>
Vous pouvez modifier les configurations d’App Service directement dans votre pom.xml. Certaines configurations courantes sont répertoriées dans le tableau suivant :
Propriété | Obligatoire | Description |
---|---|---|
subscriptionId |
false | L'ID de l'abonnement. |
resourceGroup |
true | Groupe de ressources Azure pour votre application. |
appName |
true | Nom de votre application. |
region |
false | Région dans laquelle héberger votre application. La valeur par défaut est centralus . Pour les régions valides, consultez Régions prises en charge. |
pricingTier |
false | Niveau tarifaire de votre application. La valeur par défaut est P1v2 pour une charge de travail de production. La valeur minimale recommandée pour le développement et le test Java est B2 . Pour plus d’informations, consultez Tarification App Service. |
runtime |
false | Configuration de l’environnement d’exécution. Pour plus d’informations, consultez Détails de configuration. |
deployment |
false | Configuration du déploiement. Pour plus d’informations, consultez Détails de configuration. |
Pour obtenir la liste complète des configurations, consultez la documentation de référence sur le plug-in. Tous les plug-ins Azure Maven partagent un ensemble commun de configurations. Pour ces configurations, consultez Configurations courantes. Pour connaître les configurations spécifiques à Azure App Service, consultez l’application Azure : Détails de configuration.
Veillez à enregistrer les valeurs et resourceGroup
les appName
valeurs pour une utilisation ultérieure.
Préparer l’application pour le déploiement
Lorsque vous déployez votre application sur App Service, votre URL de redirection passe à l’URL de redirection de votre instance d’application déployée. Pour modifier ces paramètres dans votre fichier de propriétés, procédez comme suit :
Accédez au fichier authentication.properties de votre application et modifiez la valeur du
app.homePage
nom de domaine de votre application déployée, comme illustré dans l’exemple suivant. Par exemple, si vous avez choisiexample-domain
le nom de votre application à l’étape précédente, vous devez maintenant l’utiliserhttps://example-domain.azurewebsites.net
pour laapp.homePage
valeur. Assurez-vous que vous avez également modifié le protocole dehttp
vershttps
.# app.homePage is by default set to dev server address and app context path on the server # for apps deployed to azure, use https://your-sub-domain.azurewebsites.net app.homePage=https://<your-app-name>.azurewebsites.net
Après avoir enregistré ce fichier, utilisez la commande suivante pour reconstruire votre application :
mvn clean package
Important
Dans ce même fichier authentication.properties , vous avez un paramètre pour votre aad.secret
. Il n’est pas recommandé de déployer cette valeur sur App Service. Il n’est pas recommandé de laisser cette valeur dans votre code et de l’envoyer à votre dépôt Git. Pour supprimer cette valeur secrète de votre code, vous trouverez des instructions plus détaillées dans la section Déployer sur App Service - Supprimer le secret . Ces instructions ajoutent des étapes supplémentaires pour envoyer (push) la valeur secrète à Key Vault et utiliser les références Key Vault.
Mettre à jour votre inscription d’application Microsoft Entra ID
Étant donné que l’URI de redirection change vers votre application déployée dans Azure App Service, vous devez également modifier l’URI de redirection dans l’inscription de votre application Microsoft Entra ID. Pour cela, effectuez les étapes suivantes :
Accédez à la page Inscriptions d’applications de la plateforme d’identités Microsoft pour les développeurs.
Utilisez la zone de recherche pour rechercher l’inscription de votre application , par exemple
java-servlet-webapp-authentication
.Ouvrez votre inscription d’application en sélectionnant son nom.
Sélectionnez Authentification dans le menu déroulant.
Dans la section URI de redirection web - , sélectionnez Ajouter un URI.
Renseignez l’URI de votre application, en ajoutant
/auth/redirect
, par exemplehttps://<your-app-name>.azurewebsites.net/auth/redirect
.Sélectionnez Enregistrer.
Déployer l’application
Vous êtes maintenant prêt à déployer votre application sur Azure App Service. Utilisez la commande suivante pour vous assurer que vous êtes connecté à votre environnement Azure pour exécuter le déploiement :
az login
Avec toutes les configurations prêtes dans votre fichier pom.xml , vous pouvez maintenant utiliser la commande suivante pour déployer votre application Java sur Azure :
mvn package azure-webapp:deploy
Une fois le déploiement terminé, votre application est prête à http://<your-app-name>.azurewebsites.net/
. Ouvrez l’URL avec votre navigateur web local, où vous devez voir la page de démarrage de l’application msal4j-servlet-auth
.
Explorer l’exemple
Pour explorer l’exemple, procédez comme suit :
- Notez que l’état de connexion ou de déconnexion s’affiche au centre de l’écran.
- Sélectionnez le bouton contextuel dans le coin. Ce bouton lit la connexion lorsque vous exécutez l’application pour la première fois.
- Dans la page suivante, suivez les instructions et connectez-vous avec un compte dans le locataire Microsoft Entra ID.
- Sur l’écran de consentement, notez les étendues demandées.
- Notez que le bouton contextuel indique maintenant se déconnecter et affiche votre nom d’utilisateur.
- Sélectionnez Détails du jeton d’ID pour afficher certaines revendications décodées du jeton d’ID.
- Utilisez le bouton dans le coin pour vous déconnecter.
- Après la déconnexion, sélectionnez Détails du jeton d’ID pour observer que l’application affiche une
401: unauthorized
erreur au lieu des revendications de jeton d’ID lorsque l’utilisateur n’est pas autorisé.
À propos du code
Cet exemple montre comment utiliser MSAL pour Java (MSAL4J) pour connecter des utilisateurs à votre locataire Microsoft Entra ID. Si vous souhaitez utiliser MSAL4J dans vos propres applications, vous devez l’ajouter à 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 d’assistanceet d’authentification dans le dossier src/main/java/com/microsoft/azuresamples/msal4j. Vous avez également besoin du fichier authentication.properties . Ces classes et 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 pour traiter l’objectif de cet exemple.
Contenu
Le tableau suivant montre le contenu de l’exemple de dossier de projet :
Fichier/Dossier | Description |
---|---|
AppCreationScripts/ | Scripts pour configurer automatiquement les inscriptions d’applications Microsoft Entra ID. |
src/main/java/com/microsoft/azuresamples/msal4j/authwebapp/ | Ce répertoire contient les classes qui définissent la logique métier principale de l’application. |
src/main/java/com/microsoft/azuresamples/msal4j/authservlets/ | Ce répertoire contient les classes utilisées pour les points de terminaison de connexion et de déconnexion. |
____Servlet.java | Tous les points de terminaison disponibles sont définis dans .java classes se terminant par ____Servlet.java.. |
src/main/java/com/microsoft/azuresamples/msal4j/helpers/ | Classes d’assistance pour l’authentification. |
AuthenticationFilter.java | Redirige les demandes non authentifiées vers des points de terminaison protégés vers une page 401. |
src/main/resources/authentication.properties | Configuration de l’ID et du programme Microsoft Entra. |
src/main/webapp/ | Ce répertoire contient l’interface utilisateur - Modèles JSP |
CHANGELOG.md | Liste des modifications apportées à l’exemple. |
CONTRIBUTING.md | Instructions pour contribuer à l’exemple. |
LICENCE | Licence de l’exemple. |
ConfidentialClientApplication
Une ConfidentialClientApplication
instance est créée dans le fichier AuthHelper.java , comme illustré dans l’exemple suivant. Cet objet permet d’élaborer l’URL d’autorisation d’ID Microsoft Entra et d’échanger le jeton d’authentification pour 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, qui est une exigence pour les applications clientes confidentielles.
- L’autorité d’IDENTIFICATION Microsoft Entra, qui inclut votre ID de locataire Microsoft Entra ID.
Dans cet exemple, ces valeurs sont lues à partir du fichier authentication.properties à l’aide d’un lecteur de propriétés dans le fichier Config.java.
Procédure pas-à-pas
Les étapes suivantes fournissent une procédure pas à pas des fonctionnalités de l’application :
La première étape du processus de connexion consiste à envoyer une demande au
/authorize
point de terminaison sur votre locataire Microsoft Entra ID. L’instance MSAL4JConfidentialClientApplication
est utilisée pour construire une URL de demande d’autorisation. L’application redirige le navigateur vers cette URL, qui est l’emplacement 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
: paramètres qui doivent être définis pour générer un AuthorizationRequestUrl.REDIRECT_URI
: Où Microsoft Entra ID redirige le navigateur, ainsi que 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 dans le Portail Azure.SCOPES
: les étendues sont des autorisations demandées par l’application. Normalement, les trois étenduesopenid profile offline_access
suffisent pour recevoir une réponse de jeton d’ID.Vous trouverez une 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
.
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 demande valide adressée à ce point de terminaison contient un code d’autorisation.
L’instance
ConfidentialClientApplication
échange ensuite ce code d’autorisation pour 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 pour un ID et/ou un jeton d’accès.authCode
: code d’autorisation reçu au 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 passées à nouveau.
Si
acquireToken
réussit, les revendications du jeton sont extraites. Si la nonce case activée passe, les résultats sont placés danscontext
- une instance deIdentityContextData
- et enregistrées dans la session. L’application peut ensuite instancier laIdentityContextData
session à partir d’une instance de chaque fois qu’elle a besoin d’yIdentityContextAdapterServlet
accéder, comme indiqué 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 plus d’informations 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 app.protect.authenticated
propriété 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 claim(s)
app.protect.authenticated=/token_details
Étendues
Les étendues indiquent à Microsoft Entra ID le niveau d’accès demandé par l’application.
En fonction des étendues demandées, l’ID Microsoft Entra présente un dialogue de consentement à l’utilisateur lors de la connexion. Si l’utilisateur consent à une ou plusieurs étendues et obtient un jeton, les étendues consentées sont encodées dans le résultat access_token
.
Pour connaître les étendues demandées par l’application, consultez authentication.properties. Ces trois étendues sont demandées par MSAL et fournies par l’ID Microsoft Entra par défaut.
Plus d’informations
- Bibliothèque d’authentification Microsoft (MSAL) pour Java
- Documentation de référence MSAL Java
- Plateforme d'identités Microsoft (ID Microsoft Entra pour les développeurs)
- Démarrage rapide : Inscrire une application à l’aide de la plateforme d’identités Microsoft
- Présentation des expériences de consentement de l’application Microsoft Entra ID
- Comprendre le consentement de l’utilisateur et de l’administrateur
- Exemples de code MSAL
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour