RestHeart启用JWT认证后无法访问资源的技术咨询

一、JWT生成必须遵循的规则 #

要让RestHeart认可你生成的JWT，必须满足以下要求：

• 签名与密钥匹配：使用配置中指定的HS256算法签名，密钥必须是jwt_secret_key（因base64Encoded: false，直接用明文密钥，不能做base64编码）。
• 必填字段校验：
  • iss字段：值必须与配置的myIssuer完全一致，RestHeart会校验签发者合法性。
  • aud字段：值必须与配置的myAudience完全一致，RestHeart会校验受众合法性。
  • sub字段：因配置了usernameClaim: sub，JWT payload中必须包含该字段，用于标识用户身份（需与你userList集合中的用户标识对应）。
  • roles字段：因你未启用fixedRoles（注释掉了- admin），JWT payload中必须包含roles数组字段，里面的角色需匹配RestHeart资源的权限要求（比如集合要求admin角色，数组里就要有admin）。

二、配置参数疑问解答 #

• usernameClaim：非可选参数，必须配置且JWT中存在对应字段。RestHeart依赖该字段识别用户身份，若缺失或不匹配，会导致认证失败。
• rolesClaim：当未配置fixedRoles时，该参数为必填，JWT中必须存在对应数组字段；若启用fixedRoles，所有认证用户会被赋予固定角色，此时rolesClaim可忽略（但配置了也不会冲突）。该字段会被校验，若配置了但JWT中缺失，会导致权限不足。

三、403/401问题排查 #

1. 访问集合返回403 #

• 先验证JWT合法性：用jwt.io解析Token，检查签名是否正确、iss/aud/sub/roles字段是否符合要求。
• 检查集合权限配置：确保RestHeart中该集合的ACLs设置允许对应角色或已认证用户访问。例如，若要允许所有已认证用户查看，ACLs可配置为：

  acls:
  - predicate: path-prefix('/your-collection')
    permission: read
    authenticated: true
  

  若需特定角色，需确保JWT的roles数组包含对应角色，同时ACLs中指定该角色。

2. 访问/tokens端点返回401 #

/tokens是RestHeart内置的Token获取端点，需通过**Basic Auth（用户名+密码）**请求（对应MongoDB用户集合中的凭证），而非携带JWT访问。你自己用Express实现的登录端点生成的Token，无法用于访问该端点——该端点的作用是让用户用账号密码交换RestHeart签发的JWT，和你自定义的认证流程无关，出现401是正常的。

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