Keycloak令牌交换未返回refresh token问题求助

核心问题根源 #

你的前端React应用是公共客户端（无密钥），Keycloak出于安全默认限制，不会给公共客户端返回Refresh Token。同时，当前的令牌交换请求缺少必要的权限范围，后端客户端的权限配置也可能不足。

具体解决步骤 #

1. 配置前端公共客户端（FRONTEND_CLIENT_ID） #

进入Keycloak控制台，找到你的前端客户端：

• 切换到Settings标签页，确认Access Type设置为public。
• 展开Advanced Settings，找到OAuth 2.0 Configuration部分，勾选Allow Refresh Token（部分版本可能在Capability Config下）。
• 若需要长期有效的刷新令牌，还需在Client Scopes标签页，给客户端添加offline_access内置客户端范围。

2. 给后端客户端添加Impersonation权限 #

后端Node应用的客户端需要有代表用户执行令牌交换的权限：

• 进入后端客户端的Service Account Roles标签页。
• 在Client Roles下拉框选择realm-management，添加impersonation角色到服务账号。

3. 调整令牌交换请求参数 #

在请求中添加scope参数，明确请求包含Refresh Token的权限范围：

export const doUserLogin = async (user: User) => {
    return axios
        .post(
            `https://${Conf.keycloak.domain}/realms/${Conf.keycloak.realm}/protocol/openid-connect/token`,
            new URLSearchParams({
                client_id: Conf.keycloak.credentials.clientId,
                client_secret: Conf.keycloak.credentials.clientSecret,
                grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
                requested_token_type: 'urn:ietf:params:oauth:token-type:refresh_token',
                requested_subject: user.keycloakId,
                audience: 'FRONTEND_CLIENT_ID',
                scope: 'openid offline_access', // 新增：明确请求刷新令牌权限
            }),
        )
        .then((res) => res.data);
};

4. 额外验证点 #

• 确认audience参数是前端客户端的准确Client ID，无拼写错误。
• 确认requested_subject是用户的Keycloak UUID（而非用户名）。
• 若使用较旧Keycloak版本，检查前端客户端的Login Settings是否开启Use Refresh Tokens。

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