如何在Spring Boot 3中集成Keycloak SAML？迁移适配求助

一、依赖替换（弃用旧Spring-SAML扩展） #

Spring Boot 3 搭配 Spring Security 6，官方已提供原生SAML2支持，无需再使用第三方扩展。直接引入官方依赖：

Maven 依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-saml2-service-provider</artifactId>
</dependency>

Gradle 依赖

implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.security:spring-security-saml2-service-provider'

二、Keycloak 端基础配置 #

1. 在Keycloak控制台创建SAML协议的客户端，填写客户端ID（需与Spring Boot配置的entity-id一致）
2. 配置ACS URL：{你的应用域名}/login/saml2/sso/{自定义注册ID}，例如http://localhost:8080/login/saml2/sso/keycloak
3. 开启签名验证，选择SHA-256算法
4. 从Keycloak元数据地址（{Keycloak地址}/realms/{你的Realm名}/protocol/saml/descriptor）提取公钥，保存为keycloak-saml-cert.crt放到项目resources目录下

三、Spring Boot 端配置 #

1. 配置文件（application.yml）

spring:
  security:
    saml2:
      relyingparty:
        registration:
          keycloak: # 这里的keycloak就是上面ACS URL里的自定义注册ID
            entity-id: "你的Spring Boot应用实体ID" # 与Keycloak客户端ID一致
            identityprovider:
              entity-id: "{Keycloak地址}/realms/{你的Realm名}"
              verification.credentials:
                - certificate-location: "classpath:keycloak-saml-cert.crt"
              singlesignon.url: "{Keycloak地址}/realms/{你的Realm名}/protocol/saml"
              singlesignon.sign-request: true

2. 安全FilterChain配置

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            // 所有请求需认证
            .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
            // SAML2登录配置，指定登录成功跳转页
            .saml2Login(saml2 -> saml2.defaultSuccessUrl("/dashboard", true))
            // SAML2登出配置，指定登出成功跳转页
            .saml2Logout(saml2 -> saml2.logoutSuccessUrl("/"));
        
        return http.build();
    }
}

四、自定义用户信息映射（可选） #

如果需要将Keycloak返回的SAML断言字段映射到自定义UserDetails，可实现Saml2AuthenticatedUserConverter：

import org.springframework.security.core.userdetails.User;
import org.springframework.security.saml2.provider.service.authentication.Saml2AuthenticatedUser;
import org.springframework.security.saml2.provider.service.authentication.Saml2UserAuthenticationConverter;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.stereotype.Component;

@Component
public class CustomSamlUserConverter implements Saml2UserAuthenticationConverter {
    @Override
    public Authentication convert(Saml2AuthenticatedUser user) {
        // 从SAML断言中提取用户属性，比如邮箱、角色
        String email = user.getFirstAttribute("email");
        return new UsernamePasswordAuthenticationToken(
            User.withUsername(email).password("").authorities("USER").build(),
            null,
            user.getAuthorities()
        );
    }
}

五、测试验证 #

1. 启动Spring Boot应用，访问任意受保护端点，会自动跳转至Keycloak登录页
2. 使用Keycloak账号登录后，会回调至ACS URL，最终跳转至配置的成功页
3. 可通过SecurityContextHolder.getContext().getAuthentication()获取当前登录用户信息

内容的提问来源于stack exchange，提问作者manjosh