排查 JWT 验证问题

如果客户端应用在对 API 的请求中包含 JSON 网络令牌 (JWT)，可扩展服务代理 (ESP) 会在向 API 后端发送请求之前验证 JWT。如果 JWT 验证失败并且 ESP 在对客户端的响应中返回错误，您可以参考本页面的问题排查信息。如需详细了解 JWT，请参阅 RFC7519。

错误：401: Jwt issuer is not configured

在 Cloud Run 中部署 ESPv2 时，gcloud run deploy 命令可能不使用 --allow-unauthenticated 标志。如果不使用该标志，JWT 令牌将由 Cloud Run <a=" docs="" management-access"="" run="" securing="">访问权限控制 IAM 服务器（而不是 ESPv2）拦截并验证。IAM 使用的颁发者可能与 ESPv2 不同。</a>

错误：BAD_FORMAT

请按如下所述进行检查：

  • 确保 JWT 包含有效的 JSON。
  • 检查 JWT 标头是否含有 "alg" 字段以及是否被设置为以下某个值："RS256"、"HS256"、"RS384"、"HS384"、"RS512" 或 "HS512"
  • 检查 JWT 负载中以下字段的数据类型（如果存在这些字段）：
    • "iat"（颁发时间）、"exp"（过期时间）和 "nbf"（不早于）声明是大于 0 的数字而不是字符串。
    • "sub"（主题）、"iss"（签发者）和 "jti" (JWT ID) 字段为字符串。
    • "aud"（受众群体）声明是字符串或字符串数组。
  • 确保 JWT 载荷中存在以下声明："sub"（主题）、"iss"（颁发者）和 "aud"（目标对象）。

以下是有效的已解码 JWT 令牌的示例：

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "42ba1e234ac91ffca687a5b5b3d0ca2d7ce0fc0a"
}

Payload:
{
  "iss": "myservice@myproject.iam.gserviceaccount.com",
  "iat": 1493833746,
  "aud": "myservice.appspot.com",
  "exp": 1493837346,
  "sub": "myservice@myproject.iam.gserviceaccount.com"
}
错误：TIME_CONSTRAINT_FAILURE

使用 jwt.io 解码 JWT 并确保：

  • 存在 "exp"（过期时间）声明。
  • "exp"（过期时间）声明值是将来的日期/时间。当前日期/时间必须晚于或等于 "exp" 声明中所列的日期/时间。
  • "nbf"（不早于）声明（如果存在）是过去的日期/时间。当前日期/时间必须晚于或等于 "nbf" 声明中所列的日期/时间。
错误：UNKNOWN

使用 jwt.io 解码 JWT 并确保：

  • 如果 "iss"（颁发者）声明是电子邮件地址，则 "sub"（主题）和 "iss" 声明应该相同。这是为了确保对于电子邮件颁发者而言，JWT 是自颁发的。

错误：KEY_RETRIEVAL_ERROR

  • 检查在 endpoints.Issuer 对象的第二个参数中指定的公钥 URI 是否正确有效。

错误：Issuer not allowed

  • 检查 JWT 令牌中的 "iss"（颁发者）声明是否与 endpoints.Issuer 对象的第一个参数匹配。

错误：Audience not allowed

如果 JSTT 令牌中的 "aud"（受众群体）声明与 Endpoints}} 服务名称匹配，则 Cloud Endpoints Frameworks 会验证受众群体并忽略在 @endpoints.api 修饰器的 audiences 参数中设置的值。例如，如果您的服务名称是 "myservice.appspot.com"，则 "aud" 设置为 "myservice.appspot.com" 或 "https://myservice.appspot.com" 的 JWT 为有效受众群体。

如果 "aud" 声明与 Endpoints 服务名称不同：

  • 检查 JWT 中的 "aud" 声明是否与 @endpoints.api 修饰器的 audiences 参数中的值匹配。