Secure Java Spring Boot apps using Microsoft Entra ID

This article demonstrates a Java Spring Boot web app that signs in users on your Microsoft Entra ID tenant using the Microsoft Entra ID Spring Boot Starter client library for Java. It uses the OpenID Connect protocol.

The following diagram shows the topology of the app:

The client app uses the Microsoft Entra ID Spring Boot Starter client library for Java to sign-in a user and obtain an ID token from Microsoft Entra ID. The ID token proves that the user is authenticated with Microsoft Entra ID and enables the user to access protected routes.

Prerequisites

• JDK version 17. This sample was developed on a system with Java 17, but it might be compatible with other versions.
• Maven 3
• Java Extension Pack for Visual Studio Code is recommended for running this sample in Visual Studio Code.
• A Microsoft Entra ID tenant. For more information, see How to get a Microsoft Entra ID tenant.
• A user account in your Microsoft Entra ID tenant. This sample doesn't work with a personal Microsoft account. Therefore, if you signed in to the Azure portal with a personal account and you don't have a user account in your directory, you need to create one now.
• Visual Studio Code
• Azure Tools for Visual Studio Code

Recommendations

• Some familiarity with the Spring Framework
• Some familiarity with Linux/OSX terminal or Windows PowerShell
• jwt.ms for inspecting your tokens.
• Fiddler for monitoring your network activity and troubleshooting.
• Follow the Microsoft Entra ID Blog to stay up-to-date with the latest developments.

Set up the sample

The following sections show you how to set up the sample application.

Clone or download the sample repository

To clone the sample, open a Bash window and use the following command:

git clone https://github.com/Azure-Samples/ms-identity-msal-java-samples.git
cd 4-spring-web-app/1-Authentication/sign-in

Alternatively, navigate to the ms-identity-msal-java-samples repository, then download it as a .zip file and extract it to your hard drive.

Register the sample applications with your Microsoft Entra ID tenant

There's one project in this sample. The following sections show you how to register the app using the Azure portal.

Choose the Microsoft Entra ID tenant where you want to create your applications

To choose your tenant, use the following steps:

1. Sign in to the Azure portal.

2. If your account is present in more than one Microsoft Entra ID tenant, select your profile in the corner of the Azure portal, and then select Switch directory to change your session to the desired Microsoft Entra ID tenant.

Register the app (java-spring-webapp-auth)

To register the app, use the following steps:

1. Navigate to the Azure portal and select Microsoft Entra ID.

2. Select App Registrations on the navigation pane, then select New registration.

3. In the Register an application page that appears, enter the following application registration information:

   • In the Name section, enter a meaningful application name for display to users of the app - for example, java-spring-webapp-auth.
   • Under Supported account types, select Accounts in this organizational directory only.
   • In the Redirect URI (optional) section, select Web in the combo-box and enter the following redirect URI: http://localhost:8080/login/oauth2/code/.

4. Select Register to create the application.

5. On the app's registration page, find and copy the Application (client) ID value to use later. You use this value in your app's configuration file or files.

6. On the app's registration page, select Certificates & secrets on the navigation pane to open the page where you can generate secrets and upload certificates.

7. In the Client secrets section, select New client secret.

8. Type a description - for example, app secret.

9. Select one of the available durations: In 1 year, In 2 years, or Never Expires.

10. Select Add. The generated value is displayed.

11. Copy and save the generated value for use in later steps. You need this value for your code's configuration files. This value isn't displayed again, and you can't retrieve it by any other means. So, be sure to save it from the Azure portal before you navigate to any other screen or pane.

Configure the app (java-spring-webapp-auth) to use your app registration

Use the following steps to configure the app:

1. Open the project in your IDE.

2. Open the src\main\resources\application.yml file.

3. Find the placeholder Enter_Your_Tenant_ID_Here and replace the existing value with your Microsoft Entra tenant ID.

4. Find the placeholder Enter_Your_Client_ID_Here and replace the existing value with the application ID or clientId of the java-spring-webapp-auth app copied from the Azure portal.

5. Find the placeholder Enter_Your_Client_Secret_Here and replace the existing value with the value you saved during the creation of java-spring-webapp-auth copied from the Azure portal.

Run the sample

mvn com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config

Summary of properties:
Subscription id   : 12345678-1234-1234-1234-123456789101
Resource group name : rg-ms-identity-spring-boot-webapp
Azure Spring Apps name : cluster-ms-identity-spring-boot-webapp
Runtime Java version : Java 11
Region            : eastus
Sku               : Standard
App name          : ms-identity-spring-boot-webapp
Public access     : true
Instance count/max replicas : 1
CPU count         : 1
Memory size(GB)   : 2
Confirm to save all the above configurations (Y/n):
[INFO] Configurations are saved to: /home/user/ms-identity-msal-java-samples/4-spring-web-app/1-Authentication/sign-in/pom.    xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:57 min
[INFO] Finished at: 2024-02-14T13:50:44Z
[INFO] ------------------------------------------------------------------------

<plugin>
    <groupId>com.microsoft.azure</groupId>
    <artifactId>azure-spring-apps-maven-plugin</artifactId>
    <version>1.19.0</version>
    <configuration>
        <subscriptionId>12345678-1234-1234-1234-123456789101</subscriptionId>
        <resourceGroup>rg-ms-identity-spring-boot-webapp</resourceGroup>
        <clusterName>cluster-ms-identity-spring-boot-webapp</clusterName>
        <region>eastus</region>
        <sku>Standard</sku>
        <appName>ms-identity-spring-boot-webapp</appName>
        <isPublic>true</isPublic>
        <deployment>
            <cpu>1</cpu>
            <memoryInGB>2</memoryInGB>
            <instanceCount>1</instanceCount>
            <runtimeVersion>Java 11</runtimeVersion>
            <resources>
                <resource>
                    <directory>${project.basedir}/target</directory>
                    <includes>
                        <include>*.jar</include>
                    </includes>
                </resource>
            </resources>
        </deployment>
    </configuration>
</plugin>

mvn azure-spring-apps:deploy

[INFO] Deployment(default) is successfully created
[INFO] Starting Spring App after deploying artifacts...
[INFO] Deployment Status: Running
[INFO]   InstanceName:demo-default-x-xxxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:UNREGISTERED
[INFO]   InstanceName:demo-default-x-xxxxxxxxx-xxxxx  Status:Terminating Reason:null       DiscoverStatus:UNREGISTERED
[INFO] Getting public url of app(demo)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-demo.azuremicroservices.io

Explore the sample

Use the following steps to explore the sample:

1. Notice the signed-in or signed-out status displayed at the center of the screen.
2. Select the context-sensitive button in the corner. This button reads Sign In when you first run the app. Alternatively, select token details. Because this page is protected and requires authentication, you're automatically redirected to the sign-in page.
3. On the next page, follow the instructions and sign in with an account in the Microsoft Entra ID tenant.
4. On the consent screen, notice the scopes that are being requested.
5. Upon successful completion of the sign-in flow, you should be redirected to the home page - which shows the sign in status - or the token details page, depending on which button triggered your sign-in flow.
6. Notice that the context-sensitive button now says Sign out and displays your user name.
7. If you're on the home page, select ID Token Details to see some of the ID token's decoded claims.
8. Use the button in the corner to sign out. The status page reflects the new state.

About the code

This sample demonstrates how to use Microsoft Entra ID Spring Boot Starter client library for Java to sign in users into your Microsoft Entra ID tenant. The sample also makes use of the Spring Oauth2 Client and Spring Web boot starters. The sample uses claims from the ID token obtained from Microsoft Entra ID to display the details of the signed-in user.

Contents

The following table shows the contents of the sample project folder:

ID token claims

To extract token details, the app makes use of Spring Security's AuthenticationPrincipal and OidcUser object in a request mapping, as shown in the following example. See the Sample Controller for the full details of how this app makes use of ID token claims.

import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
//...
@GetMapping(path = "/some_path")
public String tokenDetails(@AuthenticationPrincipal OidcUser principal) {
    Map<String, Object> claims = principal.getIdToken().getClaims();
}

Sign-in and sign-out links

For sign-in, the app makes a request to the Microsoft Entra ID sign-in endpoint automatically configured by Microsoft Entra ID Spring Boot Starter client library for Java, as shown in the following example:

<a class="btn btn-success" href="/oauth2/authorization/azure">Sign In</a>

For sign-out, the app makes a POST request to the logout endpoint, as shown in the following example:

<form action="#" th:action="@{/logout}" method="post">
  <input class="btn btn-warning" type="submit" value="Sign Out" />
</form>

Authentication-dependent UI elements

The app has some simple logic in the UI template pages for determining content to display based on whether the user is authenticated, as shown in the following example using Spring Security Thymeleaf tags:

<div sec:authorize="isAuthenticated()">
  this content only shows to authenticated users
</div>
<div sec:authorize="isAnonymous()">
  this content only shows to not-authenticated users
</div>

Protect routes with AADWebSecurityConfigurerAdapter

By default, the app protects the ID Token Details page so that only signed-in users can access it. The app configures these routes by using the app.protect.authenticated property from the application.yml file. To configure your app's specific requirements, apply the AadWebApplicationHttpSecurityConfigurer#aadWebApplication method to the HttpSecurity instance. For an example, see this app's SecurityConfig class, shown in the following code:

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig  {
    
    @Value("${app.protect.authenticated}")
    private String[] allowedOrigins;
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        // @formatter:off
        http.apply(AadWebApplicationHttpSecurityConfigurer.aadWebApplication())
            .and()
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(allowedOrigins).authenticated()
                .anyRequest().permitAll()
                );
        // @formatter:on
        return http.build();
    }

    @Bean
    @RequestScope
    public ServletUriComponentsBuilder urlBuilder() {
        return ServletUriComponentsBuilder.fromCurrentRequest();
    }    
}

More information

• Microsoft identity platform (Microsoft Entra ID for developers)
• Overview of Microsoft Authentication Library (MSAL)
• Quickstart: Register an application with the Microsoft identity platform
• Quickstart: Configure a client application to access web APIs
• Understanding Microsoft Entra ID application consent experiences
• Understand user and admin consent
• Application and service principal objects in Microsoft Entra ID
• National Clouds
• MSAL code samples
• Microsoft Entra ID Spring Boot Starter client library for Java
• Microsoft Authentication Library for Java (MSAL4J)
• MSAL4J Wiki
• ID tokens
• Access tokens in the Microsoft identity platform

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