JWT 驗證疑難排解

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

錯誤: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

  • 檢查 ApiIssuer 註解的 jwksUri 中指定的公開金鑰 URI 是否正確且有效。

錯誤:Issuer not allowed

  • 檢查 JWT 憑證中的 "iss" (核發單位) 憑證附加資訊是否符合 ApiIssuer 註解中的 issuer 值。

錯誤:Audience not allowed

如果 JWT 憑證中的 "aud" (目標對象) 憑證附加資訊符合 Endpoints 服務名稱,則 Cloud Endpoints Frameworks 會驗證目標對象並忽略 ApiIssuerAudience 註解的 audiences 元素中設定的值。例如,如果您的服務名稱是 "myservice.appspot.com",則只要 JWT 的 "aud" 設為 "myservice.appspot.com""https://myservice.appspot.com",就是有效的目標對象。

如果 "aud" 憑證附加資訊與 Endpoints 服務名稱不同:

  • 請檢查 JWT 中的 "aud" 憑證附加資訊是否與 ApiIssuerAudience 註解中 audiences 元素的其中一個值相符。
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine 適用的 Cloud Endpoints Frameworks
需要協助嗎?請前往我們的支援網頁