如何配置Keycloak采用URL会话追踪替代Cookie适配跨域iframe认证

问题背景 #

在商户域的iframe里用Keycloak实现3D Secure (3DS)认证时，Chrome隐私浏览器默认会拦截跨域iframe的第三方Cookie，直接导致认证失败，抛出cookie_not_found错误。

环境信息 #

• Keycloak版本：21
• 浏览器：Chrome隐私浏览器（默认拦截第三方Cookie）
• 架构：商户域iframe内嵌3DS认证流程

错误详情 #

type=LOGIN_ERROR, realmId=195767a4-c9e6-41ae-93ae-7466f8e64587, 
clientId=null, userId=null, , error=cookie_not_found

问题原因 #

Keycloak默认依赖Cookie追踪会话，但跨域iframe场景下浏览器会拦截第三方Cookie，会话无法维持就会触发报错。

配置Keycloak用URL参数追踪会话 #

Keycloak本身支持通过URL参数传递会话信息替代Cookie，按以下步骤调整配置：

1. 修改Realm级会话设置 #

登录Keycloak管理控制台，进入目标Realm：

• 进入Realm Settings > Security Defenses
• 将Cookie SameSite设置为None（注意：必须部署在HTTPS环境下，Chrome要求SameSite=None必须配合Secure属性，HTTP环境下该设置无效）
• 开启Use Session Cookies in URLs（Keycloak 21中对应选项可能为Session Tracking Mode，选择url即可）

2. 配置目标客户端的会话参数 #

找到3DS认证对应的客户端：

• 进入Clients > 目标客户端 > Settings
• 根据架构需求，将Access Type设置为confidential或public
• 开启Always Include Redirect URI in Authorization Response，确保会话参数能正确传递到回调地址
• 切换到Advanced Settings，设置会话空闲超时和最大生命周期，同时确认Use Refresh Tokens的配置不会干扰URL会话追踪逻辑

3. 保证认证流程中URL参数不丢失 #

Keycloak已在URL中包含session_code、tab_id、execution等会话参数，需确保这些参数在整个认证流程中持续传递：

• 发起认证请求时，将response_mode设置为query或fragment，让会话参数附加在URL中
• 所有跳转步骤需保留URL中的会话相关参数，避免重定向时丢失

4. 验证配置效果 #

完成配置后，用Chrome隐私浏览器测试3DS认证流程：

• 观察认证过程中的URL，确认session_code等参数在各步骤中持续存在
• 查看Keycloak日志，确认不再出现cookie_not_found错误

额外注意事项 #

• HTTPS强制要求：使用SameSite=None时，Keycloak必须部署在HTTPS环境，否则Cookie仍会被拦截
• URL长度限制：过多会话参数可能导致URL过长，需确保服务器和浏览器支持足够长度的URL
• 安全性：基于URL的会话追踪存在泄露风险（如URL被分享导致会话盗用），建议仅在必要场景使用，同时设置较短的会话超时时间

内容的提问来源于stack exchange，提问作者mohamed amine salah