Keycloak API问题：使用Refresh Token获取AccessToken返回401错误

一、修复Refresh Token请求401错误 #

你遇到的401问题大概率是以下几个原因导致，逐一排查：

1. 修正Token端点URL #

当前请求URL错误使用了/admin/realms/{realm-name}/...路径，这是Keycloak管理API的专属路径，正确的OpenID Connect Token端点需去掉admin前缀：

http://localhost:8080/realms/{realm-name}/protocol/openid-connect/token

/admin路径下的接口要求管理员权限认证，普通Token刷新请求无需走该路径。

2. 统一请求Content-Type #

Keycloak的Token端点仅接受application/x-www-form-urlencoded格式的请求体，无论客户端是公开还是机密类型。你的应用中使用application/json会导致Keycloak无法解析参数，直接返回401。修改请求配置示例：

fetch('http://localhost:8080/realms/{realm-name}/protocol/openid-connect/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    client_id: 'admin-cli',
    grant_type: 'refresh_token',
    refresh_token: '你的刷新令牌'
  })
})

Postman/Insomnia中也需确保使用x-www-form-urlencoded格式传递参数，而非Raw JSON。

3. 验证客户端配置 #

登录Keycloak管理后台，检查admin-cli客户端的核心配置：

• 确认Access Type设置为public（非机密客户端）
• 确认Refresh Token Enabled已勾选
• 确认Direct Access Grants Enabled已开启（部分版本依赖该配置）
• 检查Valid Redirect URIs是否包含你的应用域名（SPA应用可设为*或具体域名）

二、实现用户活动触发Token刷新逻辑 #

解决401问题后，即可实现基于用户活动的Token自动刷新：

1. 监听用户活动事件 #

覆盖常见的用户交互场景，绑定事件监听：

const activityEvents = ['mousemove', 'keydown', 'scroll', 'visibilitychange'];

2. 防抖处理避免频繁请求 #

用防抖函数控制请求频率，短时间内多次活动仅触发一次检查：

function debounce(func, delay) {
  let timeoutId;
  return (...args) => {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => func.apply(this, args), delay);
  };
}

3. 检查Token过期并自动刷新 #

编写Token过期检查逻辑，当Token即将过期时触发刷新：

// 解析JWT获取过期时间（毫秒）
function getTokenExpiration(token) {
  const payload = JSON.parse(atob(token.split('.')[1]));
  return payload.exp * 1000;
}

// 刷新Access Token
async function refreshAccessToken() {
  const refreshToken = localStorage.getItem('refresh_token');
  if (!refreshToken) return;

  try {
    const response = await fetch('http://localhost:8080/realms/{realm-name}/protocol/openid-connect/token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: new URLSearchParams({
        client_id: 'admin-cli',
        grant_type: 'refresh_token',
        refresh_token: refreshToken
      })
    });

    if (!response.ok) throw new Error('Token刷新失败');
    const data = await response.json();
    
    // 更新本地存储的Token（Keycloak会返回新的Refresh Token）
    localStorage.setItem('access_token', data.access_token);
    localStorage.setItem('refresh_token', data.refresh_token);
  } catch (error) {
    // 刷新失败，跳转登录页
    window.location.href = '/login';
  }
}

// 防抖后的活动处理逻辑：剩余时间小于5分钟时刷新
const handleUserActivity = debounce(() => {
  const accessToken = localStorage.getItem('access_token');
  if (!accessToken) return;

  const expTime = getTokenExpiration(accessToken);
  const now = Date.now();
  const timeUntilExpire = expTime - now;

  if (timeUntilExpire < 300000) { // 300000毫秒=5分钟
    refreshAccessToken();
  }
}, 30000); // 30秒防抖间隔

// 绑定所有活动事件
activityEvents.forEach(event => {
  window.addEventListener(event, handleUserActivity);
});

4. 关键注意事项 #

• 每次刷新成功后必须更新本地存储的refresh_token，旧Refresh Token会被Keycloak失效
• 可在页面隐藏时（visibilitychange事件）暂停监听，页面显示时恢复，减少无效检查
• 添加刷新状态标志，避免同一时间重复发起刷新请求

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