您正在查看 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>