您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
解碼 JWT,而不驗證 JWT 上的簽名。與 Verify JWT 政策搭配使用時,尤其在驗證 JWT 的簽名之前,必須先得知 JWT 中的憑證附加資訊,這一點非常有用。
無論使用何種演算法簽署 JWT,JWT 解碼政策皆可運作。詳情請參閱 JWS 和 JWT 政策總覽。
影片
請觀看短片,瞭解如何解碼 JWT。
範例:解碼 JWT
下列政策會將在流程變數 var.jwt 中找到的 JWT 解碼。這個變數必須存在,且包含可以 (可解碼) 的 JWT。政策可從任何流程變數取得 JWT。
<DecodeJWT name="JWT-Decode-HS256"> <DisplayName>JWT Verify HS256</DisplayName> <Source>var.jwt</Source> </DecodeJWT>
這項政策會將輸出內容寫入內容變數,以便 API Proxy 中的後續政策或條件檢查這些值。如需這項政策設定的變數清單,請參閱流程變數一節。
解碼 JWT 的元素參考資料
政策參考資料說明解碼 JWT 政策的元素和屬性。
套用至頂層元素的屬性
<DecodeJWT name="JWT" continueOnError="false" enabled="true" async="false">
以下是所有政策父項元素的通用屬性。
屬性 | 說明 | 預設 | 外觀狀態 |
---|---|---|---|
名稱 |
政策的內部名稱。名稱中使用的字元僅限 A-Z0-9._\-$ % 。不過,Edge 管理 UI 會強制執行其他限制,例如自動移除非英數字元。您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 false ,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。
設為 |
false | 選用 |
已啟用 |
如要強制執行政策,請設為 true 。
設為 |
true | 選用 |
async | 此屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性,您還可以使用其他自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
預設 | 如果省略這個元素,則會使用政策名稱屬性的值。 |
外觀狀態 | 選用 |
類型 | 字串 |
<來源>
<Source>jwt-variable</Source>
如有顯示,則指定政策預期會尋找要解碼的 JWT 的流程變數。
預設 | request.header.authorization (如需有關預設值的重要資訊,請參閱上述注意事項)。 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 | 邊緣流程變數名稱 |
流程變數
成功執行後,Verify JWT 和 Decode JWT 政策會根據以下模式設定內容變數:
jwt.{policy_name}.{variable_name}
舉例來說,如果政策名稱是 jwt-parse-token
,則政策會將 JWT 中指定的主體儲存至名為 jwt.jwt-parse-token.decoded.claim.sub
的內容變數。(如需回溯相容性,您也可以在 jwt.jwt-parse-token.claim.subject
中使用這個版本)
變數名稱 | 說明 |
---|---|
claim.audience |
JWT 目標對象憑證附加資訊。這個值可以是字串或字串陣列。 |
claim.expiry |
到期日/時間,以 Epoch 紀元時間起算的毫秒為單位。 |
claim.issuedat |
權杖的核發日期,以 Epoch 紀元時間起算的毫秒為單位。 |
claim.issuer |
JWT 核發者憑證附加資訊。 |
claim.notbefore |
如果 JWT 包含 Nbf 憑證附加資訊,這個變數就會含有該值 (從 Epoch 紀元時間起算,以毫秒為單位)。 |
claim.subject |
JWT 主體憑證附加資訊。 |
claim.name |
酬載中的指定聲明值 (標準或其他) 值。系統將針對酬載中的每個憑證附加設定分別設定其中一個選項。 |
decoded.claim.name |
酬載中已命名聲明的 JSON 可剖析值 (標準或其他)。且每個酬載中都會設定一個變數。舉例來說,您可以使用 decoded.claim.iat 擷取 JWT 的核發時間 (從 Epoch 紀元時間起算,以秒為單位)。雖然您也可以使用 claim.name 流程變數,但這是存取聲明時建議使用的變數。 |
decoded.header.name |
酬載中標頭的 JSON 可剖析值。而每個酬載中都會設定一個變數。雖然您也可以使用 header.name 流程變數,但這是存取標頭時建議使用的變數。 |
expiry_formatted |
到期日/時間,格式為使用者可理解的字串。範例:2017-09-28T21:30:45.000+0000 |
header.algorithm |
在 JWT 上使用的簽署演算法。例如 RS256、HS384 等。詳情請參閱「(演算法) 標頭參數」。 |
header.kid |
金鑰 ID (如果在產生 JWT 時新增)。如要驗證 JWT,另請參閱 JWT 政策總覽的「使用 JSON 網路金鑰組 (JWKS)」一節。詳情請參閱「(金鑰 ID) 標頭參數」。 |
header.type |
將設為 JWT 。 |
header.name |
指定標頭的值 (標準或額外值)。系統會針對 JWT 標頭部分中的每個額外標頭設定其中一個標頭。 |
header-json |
JSON 格式的標頭。 |
is_expired |
true 或 false |
payload-claim-names |
JWT 支援的憑證附加資訊陣列。 |
payload-json |
JSON 格式的酬載。
|
seconds_remaining |
權杖的過期秒數。如果權杖已過期,這個數字會是負數。 |
time_remaining_formatted |
權杖的剩餘時間,採用使用者可理解的字串。範例:00:59:59.926 |
valid |
以 VerifyJWT 來說,這個變數在簽章通過驗證時,且目前時間早於權杖到期之前,以及權杖 notBefore 值之後 (如有)。否則傳回 false。
以 DecodeJWT 來說,未設定這個變數。 |
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 修正 |
---|---|---|---|
steps.jwt.FailedToDecode |
401 | 當政策無法解碼 JWT 時發生。JWT 可能格式錯誤、無效或無法解密。 | build |
steps.jwt.FailedToResolveVariable |
401 | 發生於政策 <Source> 元素中指定的資料流變數不存在時產生的。 |
|
steps.jwt.InvalidToken |
401 | 當政策的 <Source> 元素中指定的流程變數超出範圍,或是無法解析時,就會發生這個錯誤。 |
build |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidEmptyElement |
系統會在政策的 <Source> 元素中未指定包含要解碼的 JWT 的流程變數。 |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
Variables | 地點 | 範例 |
---|---|---|
fault.name="fault_name" |
fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 | fault.name Matches "TokenExpired" |
JWT.failed |
所有 JWT 政策設定失敗時,都會設定相同的變數。 | JWT.failed = true |
錯誤回應範例
如要處理錯誤,最佳做法是納入錯誤回應的 errorcode
部分。請勿依賴 faultstring
中的文字,因為文字可能會有所變動。
故障規則示例
<FaultRules> <FaultRule name="JWT Policy Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "TokenExpired")</Condition> </Step> <Condition>JWT.failed=true</Condition> </FaultRule> </FaultRules>