如何在自定义UI中调用Keycloak忘记密码流程并解决请求失败问题

问题背景 #

使用Keycloak的忘记密码流程，希望用户停留在自定义网站UI中，流程如下：

1. 发送包含自定义页面链接的UPDATE_PASSWORD邮件，链接的code参数值为Keycloak密码更新URL：

   code=[keycloak_url]/realms/[my_realm]/login-actions/action-token?key=[action_token]
   

2. 浏览器访问该链接后，跳转至带client_id和tab_id的Keycloak链接：

   [keycloak_url]/realms/[my_realm]/login-actions/action-token?key=[action_token]&client_id=[my_client_id]&tab_id=[tab_id]
   

3. 最终获取到密码重置的目标URL：

   [keycloak_url]/realms/[my_realm]/login-actions/required-action?session_code=[session_code]&execution=UPDATE_PASSWORD&client_id=[my_client_id]&tab_id=[tab_id]
   

向该最终URL发送POST请求提交新密码时，浏览器和Postman中正常，但应用内fetch请求无法生效。

可能遗漏的关键点 #

1. 跨域资源共享（CORS）配置缺失 #

Keycloak默认未允许前端域名发起跨域请求，需在Keycloak控制台的客户端配置中，将你的前端域名添加到Web Origins列表（支持通配符如https://your-frontend-domain.com/*）。

2. 请求未携带会话Cookie #

Keycloak的密码重置会话依赖Cookie验证身份，fetch请求默认不会自动携带Cookie，需在配置中添加credentials: 'include'：

fetch(finalResetUrl, {
  method: 'POST',
  credentials: 'include', // 关键配置，确保携带会话Cookie
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    password: 'new-password',
    passwordConfirm: 'new-password'
  })
});

同时要保证Content-Type设置为application/x-www-form-urlencoded，和浏览器表单提交格式一致。

3. 会话上下文不一致 #

session_code和tab_id与浏览器会话绑定，若fetch请求在不同上下文（如iframe、新会话环境）发起，会导致会话验证失败。需确保fetch请求和之前获取最终URL的操作处于同一个浏览器会话，不要清除或修改相关Cookie。

4. 动作令牌重复使用或过期 #

Keycloak的action_token有过期时间且只能使用一次，重复使用旧令牌会导致POST请求失效。测试时需每次重新触发忘记密码流程，获取新的令牌链接。

5. 未捕获错误信息 #

fetch默认不会抛出HTTP错误状态码（如4xx、5xx），需手动处理响应状态以获取具体失败原因：

fetch(finalResetUrl, { /* 请求配置 */ })
  .then(response => {
    if (!response.ok) {
      return response.text().then(text => { throw new Error(text) });
    }
    return response;
  })
  .catch(error => {
    console.error('密码重置失败:', error);
  });

通过捕获错误信息，可明确Keycloak返回的具体问题（如令牌无效、密码不符合规则等）。

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