如果客户端应用在对 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=""managing-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
- 检查在
x-google-jwks_uri
字段正确且有效。
错误:Issuer not allowed
检查 JWT 令牌中的
"iss"
(颁发者)声明是否与x-google-issuer
(位于您的securityDefinitions
OpenAPI 文档。在 OpenAPI 文件中,检查是否为调用的 API 方法启用了安全对象。
请参阅
示例 openapi.yaml
有关如何使用
securityDefinition
和 security
对象。
错误:Audience not allowed
查看 JWT 令牌中的 "aud"
(受众)声明,看它是否与 Endpoints 服务名称(对应于 OpenAPI 文件中的 host
字段)相匹配:
如果 "aud"
声明与 Endpoints 服务名称不同,请执行下列操作:
检查 JWT 中的
"aud"
声明是否与 OpenAPI 文件中指定的某个x-google-audiences
值相匹配。确保
x-google-audiences
和x-google-issuer
位于 OpenAPI 文件的同一securityDefinitions
对象中。
如果 "aud"
声明与 Endpoints 服务名称相同,
ESP 会验证受众群体并
并忽略
x-google-audiences
设置好 OpenAPI 文档例如,如果您的服务名称是 "myservice.endpoints.example-project-12345.cloud.goog"
,则 "aud"
设置为 "myservice.endpoints.example-project-12345.cloud.goog"
或 "https://myservice.endpoints.example-project-12345.cloud.goog"
的 JWT 为有效受众群体。