本文详解 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 解析：
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 且允许委托权限。
✅ 总结与验证步骤
- 升级依赖至 spring-cloud-azure-starter-active-directory:5.14.0+；
- 在 application.yml 中正确配置 tenant-id、client-id、client-secret 及 resource-server.enabled: true；
- 编写 SecurityFilterChain Bean，启用 .oauth2ResourceServer().jwt()；
- 启动应用，用 Postman 携带有效 Azure AD Access Token 请求 /api/test，验证 200/401 响应；
- 结合前端调用，确认跨域（CORS）、token 传递、scope 匹配无误。
官方权威文档参考：Spring Cloud Azure AD Developer Guide (v5.x)。迁移虽需调整，但新模型更清晰、更安全、更符合 Spring 生态演进方向。
