Spring Boot 3 集成 Azure AD 的完整配置指南

本文详解 spring boot 3 中基于 spring security 6+ 和 spring-cloud-azure-starter-active-directory 5.x 实现 azure ad 认证与资源保护的现代配置方式，涵盖依赖升级、yaml 配置、安全配置类编写及前后端（angular + pkce）协同要点。

本文详解 spring boot 3 中基于 spring security 6+ 和 spring-cloud-azure-starter-active-directory 5.x 实现 azure ad 认证与资源保护的现代配置方式，涵盖依赖升级、yaml 配置、安全配置类编写及前后端（angular + pkce）协同要点。

随着 Spring Boot 3 的全面发布，其底层依赖已升级至 Spring Security 6.x，废弃了所有继承 WebSecurityConfigurerAdapter 的旧式配置方式，转而采用函数式安全配置（SecurityFilterChain Bean）。这意味着 Spring Boot 2 中常见的 AADResourceServerWebSecurityConfigurerAdapter 已彻底不可用。若你正将项目从 Spring Boot 2 迁移至 3，并希望继续使用 Azure AD 作为认证/授权中心（尤其配合 Angular 前端的 PKCE 流程），必须同步升级 Azure AD 集成方案。

✅ 正确依赖：使用 Spring Cloud Azure Starter（v5.x）

首先，请立即替换过时的 azure-spring-boot-starter-active-directory v4.x（该版本仅适配 Spring Boot 2.x + Spring Security 5.x）。Spring Boot 3 要求使用 spring-cloud-azure-starter-active-directory v5.0.0+（当前推荐 5.14.0），它原生支持 Spring Security 6 的组件模型和 OAuth2 Resource Server 模式：

<!-- ✅ 正确依赖（Spring Boot 3 兼容） -->
<dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-starter-active-directory</artifactId>
    <version>5.14.0</version>
</dependency>
<!-- 可选：如需 OAuth2 登录（例如管理后台），保留 client starter -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

⚠️ 注意：spring-cloud-azure-starter-active-directory v5.x 已内置 spring-boot-starter-oauth2-resource-server，无需额外引入；若同时启用登录（client）与 API 保护（resource server），两个 starter 可共存，但需明确区分用途。

?️ 核心配置：application.yml

在 application.yml 中完成 Azure AD 元数据声明。关键点在于明确指定 client-id、client-secret（服务主体凭据）、tenant-id，并启用 JWT Bearer 解析：

Okaaaay

适用于所有人的AI文本和内容生成器

下载

spring:
  cloud:
    azure:
      active-directory:
        # Azure AD 租户 ID（非应用 ID）
        tenant-id: your-tenant-id.onmicrosoft.com
        # 后端应用注册的 Client ID（即“API”应用的 Application (client) ID）
        client-id: your-backend-app-client-id
        # 后端应用注册的 Client Secret（建议使用 Azure Key Vault 管理）
        client-secret: your-client-secret
        # 启用 JWT Bearer token 验证（用于保护 REST API）
        resource-server:
          enabled: true
          # 可选：显式指定 issuer URI（增强校验严谨性）
          jwt:
            issuer-uri: https://login.microsoftonline.com/your-tenant-id/v2.0
  security:
    oauth2:
      resourceserver:
        jwt:
          # 此配置在 v5.x 中通常自动生效，显式声明可提升可读性
          jwk-set-uri: https://login.microsoftonline.com/your-tenant-id/discovery/v2.0/keys

? 提示：client-id 必须是 Azure AD 中为后端 API 应用注册的 ID（而非前端 Angular 应用的 ID），且该应用需在 “Expose an API” 中定义 scope（如 api:///access_as_user），并在前端请求 token 时明确携带该 scope。

? 安全配置：声明 SecurityFilterChain Bean

Spring Security 6 不再支持继承式配置，所有规则必须通过 @Bean SecurityFilterChain 显式声明。以下是一个典型的保护 /api/** 端点、要求有效 Azure AD JWT 的配置：

@Configuration
@EnableMethodSecurity // 启用 @PreAuthorize 等注解（可选但推荐）
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/actuator/**").permitAll() // 健康检查放行
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/**").authenticated() // 所有 /api/ 下接口需认证
                .anyRequest().denyAll()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(azureJwtBearerTokenConverter()) // 使用 Azure 提供的 converter
                )
            );
        return http.build();
    }

    /**
     * Azure 提供的 JWT Converter，自动解析 roles 声明（来自 groups 或 appRoles）
     */
    @Bean
    JwtAuthenticationConverter azureJwtBearerTokenConverter() {
        AzureJwtBearerTokenConverter converter = new AzureJwtBearerTokenConverter();
        // 可选：自定义 authorities 映射逻辑（如处理 groups/appRoles）
        return converter;
    }
}

此配置将自动：

• 验证传入 Authorization: Bearer 的 JWT 签名与 issuer；
• 解析 roles、groups、appRoles 声明并转换为 Spring GrantedAuthority；
• 支持 @PreAuthorize("hasRole('Admin')") 或 @PreAuthorize("hasAuthority('ROLE_Admin')") 方法级鉴权。

? 前后端协同要点（Angular + PKCE）

• Angular 前端应使用 @azure/msal-browser v2+，配置 PKCE 流程，scopes 必须包含后端 API 的 scope（如 ["api:///access_as_user"]）；
• 后端 Spring Boot 应用 无需实现登录页或重定向逻辑（那是 OAuth2 Client 的职责），仅作为 Resource Server 接收并验证前端附带的 Access Token；
• 确保 Azure AD 应用注册中：
  ▪ 前端应用的 “API permissions” 已添加后端应用的 access_as_user 权限并完成管理员同意；
  ▪ 后端应用的 “Expose an API” 已正确定义 scope 且允许委托权限。

✅ 总结与验证步骤

1. 升级依赖至 spring-cloud-azure-starter-active-directory:5.14.0+；
2. 在 application.yml 中正确配置 tenant-id、client-id、client-secret 及 resource-server.enabled: true；
3. 编写 SecurityFilterChain Bean，启用 .oauth2ResourceServer().jwt()；
4. 启动应用，用 Postman 携带有效 Azure AD Access Token 请求 /api/test，验证 200/401 响应；
5. 结合前端调用，确认跨域（CORS）、token 传递、scope 匹配无误。

官方权威文档参考：Spring Cloud Azure AD Developer Guide (v5.x)。迁移虽需调整，但新模型更清晰、更安全、更符合 Spring 生态演进方向。