您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
解碼 JWS 標頭而不驗證 JWS 上的簽名,然後將每個標頭寫入資料流變數。這項政策與 VerifyJWS 政策搭配使用時,最能發揮效用,因為在驗證 JWS 的簽名之前,必須先得知 JWS 中的標頭值。
JWS 可以有「附加」酬載,如下所示:
header.payload.signature
或者,JWS 可以省略酬載 (稱為「卸離」detached酬載),並採用下列格式:
header..signature
DecodeJWS 政策只會解碼 JWS 的標頭部分,因此適用於這兩種表單。無論用於簽署 JWS 的演算法為何,DecodeJWS 政策也能運作。
如需 JWS 格式的詳細介紹和總覽,請參閱 JWS 和 JWT 政策總覽。
影片
請觀看短片,瞭解如何解碼 JWT。雖然這部影片專屬於特定 JWT,但許多概念都與 JWS 相同。
範例:解碼 JWS
下列政策會將在流程變數 var.JWS 中找到的 JWS 解碼。這個變數必須存在,且包含可以 (可解碼) 的 JWS。政策可從任何流程變數取得 JWS。
<DecodeJWS name="JWS-Decode-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Source>var.JWS</Source> </DecodeJWS>
針對 JWS 標頭部分中的每個標頭,這項政策會設定名為:
jws.policy-name.header.header-name
如果 JWS 有已連接的酬載,則會將 jws.policy-name.header.payload
流程變數設為酬載。如果是卸離的酬載,payload
會是空白的。如需這項政策設定變數的完整清單,請參閱流程變數一文。
JWS 的元素參照
政策參考資料說明瞭解碼 JWS 政策的元素和屬性。
套用至頂層元素的屬性
<DecodeJWS name="JWS" 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>JWS-variable</Source>
如果有,則指定政策預期在當中尋找 JWS 要解碼的流程變數。
預設 | request.header.authorization (如需有關預設值的重要資訊,請參閱上述注意事項)。 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 | 邊緣流程變數名稱 |
流程變數
成功執行後,「Verify JWS」和「Decode JWS」政策會根據以下模式設定結構定義變數:
jws.{policy_name}.{variable_name}
舉例來說,如果政策名稱是 verify-jws
,則政策會在 JWS 中指定的演算法儲存至這個內容變數:jws.verify-jws.header.algorithm
變數名稱 | 說明 |
---|---|
decoded.header.name |
酬載中標頭的 JSON 可剖析值。而每個酬載中都會設定一個變數。雖然您也可以使用 header.name 流程變數,但這是存取標頭時建議使用的變數。 |
header.algorithm |
JWS 使用的簽署演算法。例如 RS256、HS384 等。詳情請參閱「(演算法) 標頭參數」。 |
header.kid |
金鑰 ID (如果在產生 JWS 時加入)。另請參閱 JWT 和 JWS 政策總覽的「使用 JSON 網路金鑰組 (JWKS)」一節,瞭解如何驗證 JWS。 詳情請參閱「(金鑰 ID) 標頭參數」。 |
header.type |
標頭類型值。詳情請參閱「(類型) 標頭參數」。 |
header.name |
指定標頭的值 (標準或額外值)。系統會針對 JWS 標頭部分中的每個額外標頭設定其中一個標記。 |
header-json |
JSON 格式的標頭。 |
payload |
如果 JWS 已附加酬載,則 JWS 酬載。如果是卸離的酬載,這個變數會是空白的。 |
valid |
以 VerifyJWS 來說,這個變數在驗證簽章時為 true,而且目前時間在權杖過期之前,以及權杖 notBefore 值之後 (如果有的話)。否則傳回 false。
如果是 DecodeJWS,則未設定這個變數。 |
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 發生時機 |
---|---|---|
steps.jws.FailedToDecode |
401 | 政策無法解碼 JWS。JWS 可能已損毀。 |
steps.jws.FailedToResolveVariable |
401 | 發生於政策 <Source> 元素中指定的資料流變數不存在時產生的。 |
steps.jws.InvalidClaim |
401 | 可能是因為缺少版權聲明或版權聲明不符,或是缺少標題或標頭不符的情形。 |
steps.jws.InvalidJsonFormat |
401 | JWS 標頭含有無效的 JSON。 |
steps.jws.InvalidJws |
401 | 當 JWS 簽名驗證失敗時,就會發生這個錯誤。 |
steps.jws.InvalidPayload |
401 | JWS 酬載無效。 |
steps.jws.InvalidSignature |
401 | 省略 <DetachedContent> ,且 JWS 具有卸離的內容酬載。 |
steps.jws.MissingPayload |
401 | 缺少 JWS 酬載。 |
steps.jws.NoAlgorithmFoundInHeader |
401 | JWS 省略演算法標頭時發生。 |
steps.jws.UnknownException |
401 | 發生不明例外狀況。 |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 發生時機 |
---|---|
InvalidAlgorithm |
有效值僅為:RS256、RS384、RS512、PS256、PS384、PS512、ES256、ES384、ES512、HS256、HS384、HS512。 |
|
其他可能的部署錯誤。 |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
Variables | 地點 | 範例 |
---|---|---|
fault.name="fault_name" |
fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 | fault.name Matches "TokenExpired" |
JWS.failed |
當測試失敗時,所有 JWS 政策都會設定相同的變數。 | jws.JWS-Policy.failed = true |
錯誤回應範例
如要處理錯誤,最佳做法是納入錯誤回應的 errorcode
部分。請勿依賴 faultstring
中的文字,因為文字可能會有所變動。
故障規則示例
<FaultRules> <FaultRule name="JWS Policy Errors"> <Step> <Name>JavaScript-1</Name> <Condition>(fault.name Matches "TokenExpired")</Condition> </Step> <Condition>JWS.failed=true</Condition> </FaultRule> </FaultRules>