Keycloak+NestJS中ResourceGuard始终返回403 Forbidden错误排查

• 核对资源/作用域名称一致性
  确保NestJS代码中@Resource()、@Scopes()装饰器指定的名称，和Keycloak后台创建的资源、作用域完全一致（含大小写、特殊字符）。比如Keycloak里资源是user-api/v1/profile，代码里不能写成User-API/V1/Profile，大小写敏感会直接导致匹配失败。

• 解析Token确认权限信息
  用jwt.io解析请求携带的Access Token，检查是否包含permissions字段，且字段内有对应资源和作用域的条目。如果没有，说明Keycloak未将权限信息注入Token：

  • 确认Keycloak客户端的「Authorization Enabled」已开启
  • 检查客户端的Token Scope是否包含urn:ietf:params:oauth:grant-type:uma-ticket，或在客户端设置中配置了默认的权限相关Scope

• 检查Keycloak权限策略的隐性条件
  虽然Keycloak评估工具显示有权限，但实际请求可能触发了策略的隐性限制：

  • 查看权限策略是否设置了IP范围、时间窗口等条件
  • 确认组权限是否正确关联到目标资源，且组与用户的关联关系生效（比如用户是否真的在Testproject组里，有没有同步延迟）

• 验证NestJS Keycloak模块配置

  • 确认客户端ID、Keycloak服务器地址、Realm名称和后台配置完全匹配
  • 检查客户端的「Policy Enforcement Mode」是否设为Enforcing（若设为Disabled会跳过授权，但这里是403，需确认模式配置正确）
  • 如果使用UMA模式，确保客户端拥有uma_protection权限，且模块配置了正确的UMA端点

• 查看调试日志定位问题

  • 开启Keycloak的调试日志（修改standalone.xml或keycloak.conf设置日志级别为DEBUG），查看授权请求时的详细错误信息，比如资源匹配失败、策略评估异常
  • 开启NestJS的日志，跟踪Keycloak授权中间件的处理流程，获取具体错误提示

• 排查守卫配置冲突
  确认代码中没有同时使用角色守卫和资源守卫导致的冲突，比如某个角色守卫先拦截请求返回403，资源授权逻辑未执行。

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