A Java Web application that signs in users with the Microsoft identity platform and calls Microsoft Graph

05/23/2024

About this sample

This sample is also available as a quickstart for the Microsoft identity platform: Quickstart: Add sign-in with Microsoft to a Java web app

Overview

This sample demonstrates a Java web application calling a Microsoft Graph that is secured using Microsoft Entra ID.

The Java web application uses the Microsoft Authentication Library for Java (MSAL4J) to obtain an:
- Id Token from Microsoft Entra ID to sign in an user
- Access token that is used as a bearer token when calling the Microsoft Graph to get basic information of the signed-in user.

For a java web app sample using Spring Security framework take a look at Spring Security webapp sample.

For a java web app sample using MSAL with Azure Active Directory B2C take a look at MSAL B2C webapp sample.

Scenario

This sample shows how to build a Java web app that uses OpenId Connect to sign in/ sign out an user and to get access to the Microsoft Graph using MSAL4J. For more information about how the protocols work in this scenario and other scenarios, see Authentication Scenarios for Microsoft Entra ID.

How to run this sample

To run this sample, you'll need:

Working installation of Java and Maven
An Internet connection
a Microsoft Entra tenant. For more information on how to get a Microsoft Entra tenant, see How to get a Microsoft Entra tenant
A user account in your Microsoft Entra tenant.

Step 1: Download Java (8 and above) for your platform

To successfully use this sample, you need a working installation of Java and Maven.

Step 2: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/ms-identity-java-webapp.git

Step 3: Register the sample with your Microsoft Entra tenant

To register these projects, you can:

either follow the steps in the paragraphs below
or use PowerShell scripts that:
- automatically create for you the Microsoft Entra applications and related objects (passwords, permissions, dependencies)

If you want to use this automation, read the instructions in App Creation Scripts. Please note that the configuration of your code (Step 4) still needs to be done manually.

First step: choose the Microsoft Entra tenant where you want to create your applications

As a first step you'll need to:

Sign in to the Microsoft Entra admin center.
On the top bar, click on your account, and then on Switch Directory.
Once the Directory + subscription pane opens, choose the Active Directory tenant where you wish to register your application, from the Favorites or All Directories list.
Click on All services in the portal menu, and choose Microsoft Entra ID.

In the next steps, you might need the tenant name (or directory name) or the tenant ID (or directory ID). These are presented in the Properties of the Microsoft Entra ID window respectively as Name and Directory ID

Register the app (java-webapp)

In the Microsoft Entra ID pane, click on App registrations and choose New registration.
Enter a friendly name for the application, for example 'java-webapp', select Accounts in any organizational directory and personal Microsoft Accounts (e.g. Skype, Xbox, Outlook.com).
Click Register to register the application.
On the application Overview page:
- copy Application (client) ID
- copy Directory (tenant) ID
- You'll need both of these values later to configure the project, so copy them in a safe place.
On the application Authentication page, under Redirect URIs, select Web. You will need to enter two different redirect URIs: one for the sign-in page, and one for the graph page. For both, you should use the same host and port number, then followed by "/msal4jsample/secure/aad" for the sign-in page and "msal4jsample/graph/me" for the user info page. By default, the sample uses:
- https://localhost:8443/msal4jsample/secure/aad.
- https://localhost:8443/msal4jsample/graph/me
Click on save.
On the application menu, choose Certificates & Secrets and click on New client secret in the Client Secrets section:
- Type a key description (for instance app secret),
- Select a key duration of either In 1 year, In 2 years, or Never Expires.
- The key value will display when you select Add. Copy the its value in a safe place.
- You'll need this key later to configure the project. This key value will not be displayed again, nor retrievable by any other means, so record it as soon as it is visible from the Microsoft Entra admin center.

Step 4: Configure the sample to use your Microsoft Entra tenant

Open application.properties in the src/main/resources folder.

Fill in your tenant and app registration information noted in registration step.
- Replace Enter_the_Tenant_Info_Here with the Tenant Id
- Replace Enter_the_Application_Id_here with the Application Id
- Replace Enter_the_Client_Secret_Here with the secret key value
If you did not use the default redirect URIs, then you'll have to update Microsoft Entra ID.redirectUriSignin and Microsoft Entra ID.redirectUriGraph as well with the registered redirect URIs.
- You can use any host and port number, but the path must stay the same (/msal4jsample/secure/aad and /msal4jsample/graph/me) as these are mapped to the controllers that will process the requests.
In order to use HTTPS on localhost, you need to set up a self-signed certificate.

This terminal command will use Java's keytool utility to create a keystore called keystore.p12 in the current directory, which is secured using the password password, and will create a cert with an alias of testCert and add it to the keystore.

keytool -genkeypair -alias testCert -keyalg RSA -storetype PKCS12 -keystore keystore.p12 -storepass password

Once you have your keystore/certificate, add its info to the SSL keystore properties in application.properties.
- Replace Enter_Key_Store_Here with the path to the keystore.p12 file
- Replace Enter_Key_Store_Password_Here and Enter_Key_Password_Here with the password
- Replace Enter_Key_Store_Type_Here with the store type (PKCS12)
- Replace Enter_Key_Alias_Here with the cert's alias

Step 5: Run the application

To run the project, you can either:

Run it directly from your IDE by using the embedded spring boot server or package it to a WAR file using maven and deploy it a J2EE container solution such as Apache Tomcat.

Running from IDE

If you running you web application from an IDE, click on run, then navigate to the home page of the project. For this sample, the standard home page URL is https://localhost:8443

Packaging and deploying to container

If you would like to deploy the web sample to Tomcat, you will need to make a couple of changes to the source code.

Open ms-identity-java-webapp/pom.xml
- Under <name>msal-web-sample</name> add <packaging>war</packaging>

Open ms-identity-java-webapp/src/main/java/com.microsoft.azure.msalwebsample/MsalWebSampleApplication

Delete all source code and replace with the following:

 package com.microsoft.azure.msalwebsample;

 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.boot.builder.SpringApplicationBuilder;
 import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;

 @SpringBootApplication
 public class MsalWebSampleApplication extends SpringBootServletInitializer {

  public static void main(String[] args) {
   SpringApplication.run(MsalWebSampleApplication.class, args);
  }

  @Override
  protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
   return builder.sources(MsalWebSampleApplication.class);
  }
 }

Tomcat's default HTTP port is 8080, though an HTTPS connection over port 8443 is needed. To configure this:

Go to tomcat/conf/server.xml
Search for the <connector> tag, and replace the existing connector with:

<Connector
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="C:/Path/To/Keystore/File/keystore.p12" keystorePass="KeystorePassword"
           clientAuth="false" sslProtocol="TLS"/>

Open a command prompt, go to the root folder of this sample (where the pom.xml file is located), and run mvn package to build the project
- This will generate a msal-web-sample-0.1.0.war file in your /targets directory.
- Rename this file to msal4jsample.war
- Deploy this war file using Tomcat or any other J2EE container solution.
  - To deploy, copy the msal4jsample.war file to the /webapps/ directory in your Tomcat installation, and then start the Tomcat server.
Once deployed, go to https://localhost:8443/msal4jsample in your browser

You're done

Click on "Login" to start the process of logging in. Once logged in, you'll see the account information for the user that is logged in. You'll then have the option to "Sign out" or to "Show User Info", which will display the basic information of the signed-in user.

Developers who wish to gain good familiarity of programming for Microsoft Graph are advised to go through the An introduction to Microsoft Graph for developers recorded session.

Community Help and Support

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before. Make sure that your questions or comments are tagged with [msal Java].

If you find a bug in the sample, please raise the issue on GitHub Issues.

To provide a recommendation, visit the following User Voice page.

Contributing

If you'd like to contribute to this sample, see CONTRIBUTING.MD.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

More information

For more information, see MSAL4J conceptual documentation

For more information about web apps scenarios on the Microsoft identity platform see Scenario: Web app that signs in users and Scenario: Web app that calls web APIs

For more information about how OAuth 2.0 protocols work in this scenario and other scenarios, see Authentication Scenarios for Microsoft Entra ID.

Share via