排解 JWT 驗證問題

用戶端應用程式發出的 API 要求若包含 JSON Web Token (JWT)，可擴充服務 Proxy (ESP) 會先驗證 JWT 再將要求傳送至 API 後端。本頁說明若 JWT 驗證失敗，且 ESP 在回應用戶端時傳回錯誤，該如何疑難排解。如需關於 JWT 的詳細資訊，請參閱 RFC 7519。

錯誤：401: Jwt issuer is not configured

在 Cloud Run 中部署 ESPv2 時，可能會發生這種情況，因為 gcloud run deploy 指令未使用 --allow-unauthenticated 標記。如果未使用標記，則 JWT 權杖會遭到攔截，並由 Cloud Run 存取控制 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

  • 檢查 OpenAPI 文件中 x-google-jwks_uri 欄位指定的公開金鑰 URI 是否正確且有效。

錯誤：Issuer not allowed

  • 檢查 JWT 憑證中的 "iss" (核發單位) 憑證附加資訊，是否與 OpenAPI 文件中安全性物件 securityDefinitions 區段的 securityDefinitions 欄位中的 x-google-issuer 欄位相符。

  • 在 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 會驗證目標對象並忽略 OpenAPI 文件中的 x-google-audiences 值。舉例來說，如果您的服務名稱是 "myservice.endpoints.example-project-12345.cloud.goog"，則只要 JWT 的 "aud" 設為 "myservice.endpoints.example-project-12345.cloud.goog" 或 "https://myservice.endpoints.example-project-12345.cloud.goog"，就是有效的目標對象。