Authenticating with Azure AD in Spring Boot: A Senior Dev's Guide

If you're building enterprise Spring Boot applications, chances are you've encountered Azure Active Directory. It's Microsoft's identity platform, and integrating it properly can make or break your app's security. I've seen teams spend weeks wrestling with token validation, only to discover they misconfigured a single property.

In this guide, I'll walk you through setting up Azure AD authentication in Spring Boot using the official spring-cloud-azure-starter-active-directory library. We'll cover configuration, securing endpoints, role-based access, and—most importantly—the gotchas that the official docs gloss over. By the end, you'll have a production-ready setup that handles token validation, role mapping, and common edge cases.

This isn't a beginner's tutorial. I assume you know Spring Security basics and have an Azure AD tenant. If not, check out our Spring Security basics article first. Let's dive into the real-world integration.

Why Azure AD for Spring Boot?

Azure AD is more than just an identity provider—it's a full-fledged IAM solution. When you pair it with Spring Boot, you get enterprise-grade authentication and authorization out of the box. I've used this combo in SaaS platforms handling millions of users, and it scales beautifully if configured correctly.

The key advantage is that Azure AD handles token issuance, validation, and lifecycle management. Your Spring Boot app only needs to validate tokens and extract claims. This reduces your security surface area significantly. But it also means you're dependent on Microsoft's infrastructure—so you need to handle outages and token rotation gracefully.

In production, I've seen teams struggle with token validation because they didn't understand the OIDC discovery endpoint. The spring-cloud-azure-starter-active-directory library abstracts most of this, but you still need to know what's happening under the hood. Let's set it up properly.

<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
    <version>5.12.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Configuration: The Devil in the Details

Configuration is where most teams stumble. You need three critical values from your Azure AD app registration: tenant ID, client ID, and client secret. You'll also need to expose the application ID URI (usually api://{client-id}).

Here's a minimal configuration that works in production. Notice the profile section—this tells Spring Security to use Azure AD's OIDC endpoints. The credential section uses a client secret, but in production, you should use a certificate or managed identity.

One gotcha: the app-id-uri must match the aud claim in your token. If you're calling APIs, the audience is the API's app ID URI. If you're authenticating users, the audience is 00000003-0000-0000-c000-000000000000 (Microsoft Graph). Get this wrong, and you'll get 401 errors.

spring:
  cloud:
    azure:
      active-directory:
        enabled: true
        profile:
          tenant-id: your-tenant-id
        credential:
          client-id: your-client-id
          client-secret: your-client-secret
        app-id-uri: api://your-client-id
        user-group:
          allowed-groups: Users,Admins

Securing Endpoints with Roles

Once authentication is working, you need authorization. Azure AD can assign roles to users, and these roles appear as roles claim in the JWT. Spring Security maps these to GrantedAuthority objects with a ROLE_ prefix by default.

Here's how to secure endpoints. The @PreAuthorize annotation checks for a role named 'Admin'. Note that the role in the annotation is without the ROLE_ prefix—Spring adds it internally.

In production, I've seen teams forget to define the role in Azure AD. If the role isn't assigned, the user gets a 403. Also, role names are case-sensitive. 'Admin' and 'admin' are different.

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/public").permitAll()
                .requestMatchers("/api/admin").hasRole("Admin")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(Customizer.withDefaults())
            );
        return http.build();
    }
}

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/admin")
    @PreAuthorize("hasRole('Admin')")
    public String adminEndpoint() {
        return "Hello Admin";
    }
}

What the Official Docs Won't Tell You

Here are the real gotchas I've encountered:

1. Trailing Slash in Issuer URI: This is the #1 cause of 401 errors. The issuer URI must match exactly, including trailing slash. Azure AD's OIDC endpoint returns the issuer with a trailing slash. If your config omits it, validation fails.
2. Token Lifetime: Azure AD access tokens default to 1 hour. If your app caches tokens, ensure it respects the exp claim. I've seen apps use stale tokens for hours because they didn't check expiration.
3. Role Claim Format: Azure AD sends roles as an array of strings. But if a user has no roles, the claim is absent entirely. Your code must handle missing roles gracefully.
4. Multi-Tenant Apps: If your app supports multiple tenants, you cannot use a single issuer URI. You need to dynamically validate the issuer against a list of allowed tenants. The starter doesn't support this out of the box—you need a custom JwtIssuerAuthenticationManagerResolver.
5. Logout: Azure AD's logout endpoint requires a post_logout_redirect_uri parameter. If you don't configure it, the user is redirected to a generic Microsoft page. Always set this to your app's post-logout URL.

@Component
public class CustomIssuerResolver implements JwtIssuerAuthenticationManagerResolver {

    private final Set<String> allowedIssuers = Set.of(
        "https://login.microsoftonline.com/tenant1/v2.0/",
        "https://login.microsoftonline.com/tenant2/v2.0/"
    );

    @Override
    public AuthenticationManager resolve(String issuer) {
        if (allowedIssuers.contains(issuer)) {
            JwtDecoder decoder = JwtDecoders.fromOidcIssuerLocation(issuer);
            return authentication -> {
                JwtAuthenticationToken token = (JwtAuthenticationToken) decoder.decode(((JwtAuthenticationToken) authentication).getToken().getTokenValue());
                return token;
            };
        }
        throw new AuthenticationServiceException("Unknown issuer: " + issuer);
    }
}

Testing Azure AD Authentication

Testing is critical but often overlooked. You can't rely on hitting a real Azure AD tenant in unit tests. Instead, mock the JWT decoder. Here's how I test authentication in production-grade apps.

First, generate a test JWT using a library like jjwt. Then, configure a mock JwtDecoder bean for tests. This isolates your security logic from Azure AD.

In integration tests, use @WithMockJwtAuth from the spring-security-test library. It creates a mock authentication with specified roles.

For end-to-end tests, you can use a test Azure AD tenant or a tool like WireMock to stub the JWKS endpoint.

@SpringBootTest
@AutoConfigureMockMvc
public class SecurityTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testAdminEndpointWithValidRole() throws Exception {
        mockMvc.perform(get("/api/admin")
                .with(jwt().authorities(new SimpleGrantedAuthority("ROLE_Admin"))))
                .andExpect(status().isOk());
    }

    @Test
    public void testAdminEndpointWithoutRole() throws Exception {
        mockMvc.perform(get("/api/admin")
                .with(jwt()))
                .andExpect(status().isForbidden());
    }
}

Production Hardening and Monitoring

Once your app is live, you need to monitor authentication health. Key metrics: token validation failures, 401/403 rates, and token refresh success. Use Spring Boot Actuator to expose these metrics and integrate with Prometheus/Grafana.

Also, implement a health check that validates the Azure AD endpoint is reachable. A common pattern is to hit the OIDC discovery endpoint and verify the response.

Finally, handle token refresh gracefully. Azure AD refresh tokens expire after 90 days of inactivity. Your app should silently refresh tokens before they expire. The OAuth2 client library handles this automatically, but ensure your session timeout is longer than the token lifetime.

@Component
public class AzureAdHealthIndicator implements HealthIndicator {

    @Value("${spring.cloud.azure.active-directory.profile.tenant-id}")
    private String tenantId;

    @Override
    public Health health() {
        try {
            String url = "https://login.microsoftonline.com/" + tenantId + "/v2.0/.well-known/openid-configuration";
            RestTemplate rest = new RestTemplate();
            rest.getForEntity(url, String.class);
            return Health.up().build();
        } catch (Exception e) {
            return Health.down(e).build();
        }
    }
}