启用SSL终止后Keycloak-Angular应用重定向循环问题排查

问题现象 #

启用Nginx SSL终止后，基于Angular+Keycloak的应用出现以下异常：

• 首次访问可正常跳转至Keycloak登录页，登录后能返回首页
• 刷新页面或跳转路由时，陷入https://domain/realms/realm/protocol/openid-connect/3p-cookies/step1.html与step2.html的请求循环
• 登录前刷新页面也会触发相同循环
• /realms/realm/protocol/openid-connect/auth?client_id请求返回200（HTML文件）而非预期的302重定向
• 浏览器已保存AUTH_SESSION_ID、KEYCLOAK_SESSION、KEYCLOAK_IDENTITY等旧版本Cookie

根本原因 #

1. Keycloak Cookie属性不兼容HTTPS：启用SSL后，Keycloak生成的Cookie未标记Secure属性，浏览器在HTTPS环境下拒绝发送这些Cookie，导致Keycloak无法识别用户会话，反复触发第三方Cookie检测流程
2. Nginx代理头配置不一致：/realms/与/resources/路径的Host头配置存在差异，且X-Forwarded-*系列头传递不完整，导致Keycloak无法正确判断请求的协议与端口，生成错误的Cookie属性
3. Keycloak代理模式配置缺失：仅设置PROXY_ADDRESS_FORWARDING未明确指定KC_PROXY为edge，Keycloak无法正确处理反向代理后的HTTPS请求
4. Angular Silent SSO逻辑冲突：checkLoginIframe: false配合onLoad: 'check-sso'时，Keycloak JS依赖第三方Cookie检测流程，而Cookie无法正常传递时就会陷入循环

解决步骤 #

1. 修正Keycloak Docker配置 #

更新环境变量，明确代理模式并强制Cookie使用Secure属性：

services:
  keycloak:
    image: quay.io/keycloak/keycloak:25.0.6
    container_name: keycloak
    environment:
      KEYCLOAK_IMPORT: /opt/keycloak/data/import/realm.json
      KC_HTTP_ENABLED: 'true'
      KC_HTTP_PORT: 8081
      KC_PROXY: edge  # 适配SSL终止场景的代理模式
      KC_PROXY_HEADERS: xforwarded
      PROXY_ADDRESS_FORWARDING: 'true'
      KC_HOSTNAME_STRICT: 'false'
      KC_COOKIE_SECURE: 'true'  # 强制Cookie添加Secure属性
      KC_HOSTNAME: domain  # 替换为你的实际域名

2. 统一Nginx代理头配置 #

合并/realms/与/resources/的代理配置，确保头信息一致完整：

# 统一Keycloak相关路径的代理配置
location ~ ^/(realms|resources)/ {
    proxy_pass http://ip;  # 替换为你的Keycloak容器IP/端口
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_pass_header Set-Cookie;
    proxy_cookie_path / /;  # 确保Cookie路径正确传递
}

移除原有的分开配置，使用正则匹配统一处理Keycloak路径。

3. 调整Angular Keycloak初始化配置 #

优化Silent SSO逻辑，避免依赖第三方Cookie检测：

export function initializeKeycloak(keycloak: KeycloakService) {
  return () =>
    keycloak.init({
      config: {
        url: 'https://domain',
        realm: 'realm',
        clientId: 'realm-client',
      },
      initOptions: {
        onLoad: 'check-sso',
        silentCheckSsoRedirectUri: window.location.origin + '/assets/silent-check-sso.html',
        checkLoginIframe: true,  # 启用iframe检测替代第三方Cookie流程
        pkceMethod: 'S256',  # 启用PKCE增强安全性，减少Cookie依赖
      },
      enableBearerInterceptor: true,
      bearerExcludedUrls: ['/assets', '/clients/public'],
    });
}

确保assets目录下存在silent-check-sso.html文件，内容如下：

<!DOCTYPE html>
<html>
<body>
  <script>
    parent.postMessage(location.href, location.origin);
  </script>
</body>
</html>

4. 清理浏览器旧Cookie #

由于浏览器保存了未标记Secure的旧Cookie，可在Nginx中添加临时配置强制清除：

add_header Set-Cookie "AUTH_SESSION_ID=; Path=/; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT";
add_header Set-Cookie "KEYCLOAK_SESSION=; Path=/; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT";
add_header Set-Cookie "KEYCLOAK_IDENTITY=; Path=/; Secure; HttpOnly; SameSite=Lax; Expires=Thu, 01 Jan 1970 00:00:00 GMT";

将上述配置添加到Nginx的server块中，部署后刷新页面一次即可移除旧Cookie，之后可删除该配置。

5. 验证Keycloak客户端配置 #

登录Keycloak管理后台，检查realm-client的配置：

• 确保Access Type设置为public（Angular应用属于公共客户端）
• 验证Valid Redirect URIs包含https://domain/*
• 确认Web Origins设置为https://domain（生产环境建议明确域名，避免使用*）

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