Keycloak Bearer Only类型Node.js适配器返回403错误如何解决

核心故障原因 #

你遇到的403错误是Keycloak的Token校验不通过导致，常见触发原因如下：

• 受众（aud）校验失败：后端配置中开启了verify-token-audience: true，要求Token的aud字段必须包含后端客户端的ID。但默认你前端登录获取的Token的aud只有公开客户端react-frontend，不包含后端listings-backend，触发校验拦截。
• Authorization头格式不规范：前端代码中写的是bearer （小写b），部分严格的Keycloak适配器要求必须是Bearer （大写B），会直接拒绝格式错误的认证头。
• 资源角色校验失败：后端配置开启了use-resource-role-mappings: true，要求登录用户必须分配listings-backend客户端的对应角色，没有分配对应角色的合法Token也会被拦截。
• 配置参数不匹配：你描述中创建的后端客户端是service-backend，但后端配置里的resource字段值是listings-backend，如果Keycloak中实际创建的Bearer Only客户端ID和配置值不一致，也会导致校验失败；另外realm字段大小写不匹配也会触发同类问题。

对应解决步骤 #

1. 优先修复aud校验问题：
   登录Keycloak管理后台，进入react-frontend客户端的客户端范围配置，将listings-backend添加到受众列表中；生产环境不建议直接关闭verify-token-audience配置，会有安全风险。
2. 修正认证头格式：
   将前端请求代码中的

   headers.set('Authorization', 'bearer ' + keycloak.token)
   

   修改为

   headers.set('Authorization', 'Bearer ' + keycloak.token)
   

3. 修复角色校验问题：
   如果你的接口不需要做客户端角色校验，可以把后端配置中的use-resource-role-mappings改为false，或者将keycloak.protect()的入参改为'*'允许所有合法Token访问；如果需要角色校验，则给登录用户分配listings-backend客户端的对应角色。
4. 核对基础配置：
   确认Keycloak中创建的Bearer Only客户端ID、Realm名称，和后端配置里的resource、realm字段值完全一致，Keycloak的配置值大小写敏感。
5. 快速排查手段：
   可以将前端获取到的Token粘贴到JWT解析工具中，查看aud、resource_access字段是否符合预期，快速定位是哪个校验项触发的拦截。

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