Spring Boot 3集成Keycloak多租户：动态Realm认证实现方案咨询

Spring Boot 3移除了旧的Keycloak Spring Adapter，需基于Spring Security OAuth2 Resource Server实现多Realm动态认证。核心思路是从请求的JWT令牌中提取Realm信息，动态加载对应Realm的JWT验证器，具体实现步骤如下：

1. 配置Realm相关参数 #

在application.yml中配置所有需要支持的Keycloak Realm的JWKS端点（用于获取公钥验证JWT签名）：

keycloak:
  realms:
    customer-realm:
      jwks-uri: https://your-keycloak-domain/auth/realms/customer-realm/protocol/openid-connect/certs
    admin-realm:
      jwks-uri: https://your-keycloak-domain/auth/realms/admin-realm/protocol/openid-connect/certs

2. 加载Realm配置 #

创建配置类绑定上述参数，方便后续获取：

@Component
@ConfigurationProperties(prefix = "keycloak")
public class KeycloakRealmProperties {
    private Map<String, RealmConfig> realms = new HashMap<>();

    public static class RealmConfig {
        private String jwksUri;

        // Getter & Setter
        public String getJwksUri() {
            return jwksUri;
        }

        public void setJwksUri(String jwksUri) {
            this.jwksUri = jwksUri;
        }
    }

    // Getter & Setter
    public Map<String, RealmConfig> getRealms() {
        return realms;
    }

    public void setRealms(Map<String, RealmConfig> realms) {
        this.realms = realms;
    }
}

3. 实现动态JWT解析器 #

自定义JwtDecoderResolver，从请求的JWT中提取Realm，动态创建或复用对应Realm的JwtDecoder：

@Component
public class DynamicRealmJwtDecoderResolver implements JwtDecoderResolver<HttpServletRequest> {

    private final KeycloakRealmProperties realmProperties;
    private final Map<String, JwtDecoder> decoderCache = new ConcurrentHashMap<>();

    public DynamicRealmJwtDecoderResolver(KeycloakRealmProperties realmProperties) {
        this.realmProperties = realmProperties;
    }

    @Override
    public JwtDecoder resolve(HttpServletRequest request) {
        // 提取Bearer令牌
        String authHeader = request.getHeader(HttpHeaders.AUTHORIZATION);
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            throw new AuthenticationCredentialsNotFoundException("Missing or invalid Authorization header");
        }
        String token = authHeader.substring(7);

        // 解析JWT的issuer字段，提取Realm名称（Keycloak的issuer格式为https://domain/auth/realms/{realm}）
        Jwt jwt = JwtParser.parse(token);
        String issuer = jwt.getIssuer();
        String realmName = extractRealmFromIssuer(issuer);

        // 缓存复用JwtDecoder，避免重复创建
        return decoderCache.computeIfAbsent(realmName, this::buildRealmJwtDecoder);
    }

    private String extractRealmFromIssuer(String issuer) {
        String[] segments = issuer.split("/realms/");
        if (segments.length < 2) {
            throw new IllegalArgumentException("Invalid issuer URL: " + issuer);
        }
        return segments[1];
    }

    private JwtDecoder buildRealmJwtDecoder(String realmName) {
        KeycloakRealmProperties.RealmConfig config = realmProperties.getRealms().get(realmName);
        if (config == null) {
            throw new IllegalArgumentException("Unsupported realm: " + realmName);
        }
        return NimbusJwtDecoder.withJwkSetUri(config.getJwksUri()).build();
    }
}

4. 配置Spring Security #

将动态解析器接入Spring Security的OAuth2资源服务器配置：

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final DynamicRealmJwtDecoderResolver jwtDecoderResolver;

    public SecurityConfig(DynamicRealmJwtDecoderResolver jwtDecoderResolver) {
        this.jwtDecoderResolver = jwtDecoderResolver;
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .decoderResolver(jwtDecoderResolver)
                    .jwtAuthenticationConverter(jwtAuthenticationConverter()) // 可选：角色转换
                )
            );
        return http.build();
    }

    // 可选：将Keycloak的realm角色转换为Spring Security权限
    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter authoritiesConverter = new JwtGrantedAuthoritiesConverter();
        authoritiesConverter.setAuthorityPrefix("ROLE_");
        authoritiesConverter.setAuthoritiesClaimName("realm_access.roles");

        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(authoritiesConverter);
        return converter;
    }
}

关键注意点 #

• 缓存优化：用ConcurrentHashMap缓存JwtDecoder，避免每次请求都创建新的解析器，提升性能
• 异常处理：可自定义AuthenticationEntryPoint处理令牌无效、未知Realm等异常，返回标准化错误响应
• 权限控制：通过JwtAuthenticationConverter可以将Keycloak中的角色映射为Spring Security的权限，实现细粒度的接口授权

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