Spring Boot 3+Keycloak+OAuth2单点登出失效问题求助

环境与现有配置 #

• Java 21
• Spring Boot 3.4.5
• Keycloak 作为身份提供商

application.properties 配置 #

spring.security.oauth2.client.provider.oidcclient.issuer-uri=${AUTH_SERVER:http://localhost:8180/auth}/realms/${REALM:realm}
spring.security.oauth2.client.provider.oidcclient.user-name-attribute=preferred_username
spring.security.oauth2.client.registration.oidcclient.client-id=${RESOURCE:resource}
spring.security.oauth2.client.registration.oidcclient.client-secret=${KEYCLOAK_SECRET:99b22503-44a7-4579-ba86-373c9ce56270}
spring.security.oauth2.client.registration.oidcclient.client-name=OIDC-Client
spring.security.oauth2.client.registration.oidcclient.provider=oidcclient
spring.security.oauth2.client.registration.oidcclient.scope=openid,profile,email

pom.xml 依赖 #

<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
   <groupId>org.springframework.boot</groupId>
   <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

Spring Security 配置 #

@Bean
public SecurityFilterChain webOAuth2FilterChain(HttpSecurity httpSecurity,
    ClientRegistrationRepository clientRegistrationRepository)
    throws Exception {
  return httpSecurity.csrf(AbstractHttpConfigurer::disable)
      .authorizeHttpRequests(
          authorize -> authorize.anyRequest().authenticated())
      .headers(headers
          -> headers.frameOptions(
              HeadersConfigurer.FrameOptionsConfig::sameOrigin))
      .oauth2Login(
          login -> { login.loginPage("/oauth2/authorization/oidcclient"); })
      .oauth2Client(Customizer.withDefaults())
      .logout(logout
          -> logout.logoutSuccessHandler(
              oidcLogoutSuccessHandler(clientRegistrationRepository)))
      .oidcLogout((logout) -> logout.backChannel(Customizer.withDefaults()))
      .build();
}

@Bean
public LogoutSuccessHandler oidcLogoutSuccessHandler(
    ClientRegistrationRepository clientRegistrationRepository) {
  OidcClientInitiatedLogoutSuccessHandler oidcLogoutSuccessHandler =
      new OidcClientInitiatedLogoutSuccessHandler(clientRegistrationRepository);
  oidcLogoutSuccessHandler.setPostLogoutRedirectUri("{baseUrl}");
  return oidcLogoutSuccessHandler;
}

Keycloak 客户端配置 #

{
  "clientId": "b22-emcs-business",
  "rootUrl": "https://view-business-b22-emcs-new.dev.openshift.local",
  "adminUrl": "https://view-business-b22-emcs.dev.openshift.local",
  "baseUrl": "/",
  "surrogateAuthRequired": false,
  "enabled": true,
  "alwaysDisplayInConsole": false,
  "clientAuthenticatorType": "client-secret",
  "redirectUris": [
    "https://view-business-b22-emcs-new.dev.openshift.local/*",
    "https://view-business-b22-emcs.dev.openshift.local/*"
  ],
  "webOrigins": [
    "+"
  ],
  "notBefore": 0,
  "bearerOnly": false,
  "consentRequired": false,
  "standardFlowEnabled": true,
  "implicitFlowEnabled": false,
  "directAccessGrantsEnabled": true,
  "serviceAccountsEnabled": true,
  "publicClient": false,
  "frontchannelLogout": false,
  "protocol": "openid-connect",
  "attributes": {
    "saml.multivalued.roles": "false",
    "saml.force.post.binding": "false",
    "frontchannel.logout.session.required": "false",
    "oauth2.device.authorization.grant.enabled": "false",
    "backchannel.logout.revoke.offline.tokens": "false",
    "saml.server.signature.keyinfo.ext": "false",
    "use.refresh.tokens": "true",
    "oidc.ciba.grant.enabled": "false",
    "backchannel.logout.session.required": "true",
    "client_credentials.use_refresh_token": "false",
    "saml.client.signature": "false",
    "require.pushed.authorization.requests": "false",
    "saml.allow.ecp.flow": "false",
    "saml.assertion.signature": "false",
    "id.token.as.detached.signature": "false",
    "client.secret.creation.time": "1696319788",
    "saml.encrypt": "false",
    "saml.server.signature": "false",
    "exclude.session.state.from.auth.response": "false",
    "saml.artifact.binding": "false",
    "saml_force_name_id_format": "false",
    "tls.client.certificate.bound.access.tokens": "false",
    "acr.loa.map": "{}",
    "saml.authnstatement": "false",
    "display.on.consent.screen": "false",
    "token.response.type.bearer.lower-case": "false",
    "saml.onetimeuse.condition": "false",
    "backchannel.logout.url": "https://view-business-b22-emcs-new.dev.openshift.local/logout/connect/back-channel/oidcclient"
  },
  "authenticationFlowBindingOverrides": {},
  "fullScopeAllowed": false,
  "nodeReRegistrationTimeout": -1,
  "defaultClientScopes": [
    "web-origins",
    "roles",
    "profile",
    "client_roles_to_userinfo",
    "email"
  ],
  "optionalClientScopes": [
    "address",
    "phone",
    "offline_access",
    "microprofile-jwt"
  ],
  "access": {
    "view": true,
    "configure": true,
    "manage": true
  }
}

问题描述 #

当前单点登录功能正常，但仅在本应用触发登出时有效；用户在其他应用登出后，本应用的用户会话未同步失效。

缺失配置与解决步骤 #

1. 启用 Keycloak 前端通道登出（Frontchannel Logout） #

当前 Keycloak 客户端配置中 *frontchannelLogout* 为 false，这是跨应用登出的关键配置之一。前端通道登出通过在用户浏览器中加载登出 iframe，触发所有已登录应用的会话失效。

修改 Keycloak 客户端配置：

• 将 *frontchannelLogout* 设置为 true
• 确保 attributes 中的 *frontchannel.logout.session.required* 保持 true（已配置）

2. 配置 Spring Security 处理前端通道登出请求 #

Spring Security 需要接收并处理 Keycloak 发送的前端通道登出请求，需添加对应的端点配置：

更新 SecurityFilterChain，添加前端通道登出处理器，并忽略该端点的 CSRF 检查：

@Bean
public SecurityFilterChain webOAuth2FilterChain(HttpSecurity httpSecurity,
    ClientRegistrationRepository clientRegistrationRepository)
    throws Exception {
  return httpSecurity.csrf(csrf -> csrf
          .ignoringRequestMatchers("/logout/connect/front-channel/**")) // 忽略前端登出端点的CSRF检查
      .authorizeHttpRequests(
          authorize -> authorize.anyRequest().authenticated())
      .headers(headers
          -> headers.frameOptions(
              HeadersConfigurer.FrameOptionsConfig::sameOrigin))
      .oauth2Login(
          login -> { login.loginPage("/oauth2/authorization/oidcclient"); })
      .oauth2Client(Customizer.withDefaults())
      .logout(logout -> logout
          .logoutSuccessHandler(oidcLogoutSuccessHandler(clientRegistrationRepository))
          .addLogoutHandler(new OidcFrontChannelLogoutHandler())) // 添加前端通道登出处理器
      .oidcLogout((logout) -> logout.backChannel(Customizer.withDefaults()))
      .build();
}

3. 验证后端通道登出配置（Backchannel Logout） #

已配置后端通道登出，需确认以下几点：

• Keycloak 客户端的 *backchannel.logout.url* 正确指向应用的后端登出端点（已配置）
• 应用能接收 Keycloak 的 POST 请求，无防火墙/反向代理拦截
• Spring Security 的 *oidcLogout().backChannel()* 已启用（已配置）

4. 确保所有应用共享同一 Keycloak Realm #

跨应用单点登出要求所有应用都注册在 Keycloak 的同一 Realm下，用户会话由该 Realm 统一管理。

5. 验证用户会话同步 #

完成配置后测试流程：

1. 登录应用A和应用B
2. 在应用A触发登出
3. 检查应用B是否自动登出，或刷新后需重新登录

关键原理 #

• 前端通道登出：Keycloak 在用户登出时，通过 iframe 向所有已登录应用的前端登出端点发送请求，触发应用清除本地会话。
• 后端通道登出：Keycloak 直接调用应用的后端登出 API，强制失效服务器端会话。
  两种方式结合确保跨应用会话同步失效。

内容的提问来源于stack exchange，提问作者Lyss P. Hacker