您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info
結果
解碼 JWS 標頭，但不驗證 JWS 的簽章，並將每個標頭寫入流程變數。與 VerifyJWS 政策搭配使用時，這項政策最為實用，因為在驗證 JWS 的簽名之前，必須先知道 JWS 內標頭的值。
JWS 可以有附加酬載，格式如下：
header.payload.signature
或者，JWS 可以省略酬載 (稱為「分離式」酬載)，並採用以下格式：
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 為空白。
如需這項政策設定的變數完整清單，請參閱「流程變數」。
Decode JWS 的元素參考資料
政策參考資料說明「解碼 JWS」政策的元素和屬性。
適用於頂層元素的屬性
<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">
所有政策父項元素都有下列屬性。
| 屬性 | 說明 | 預設 | 外觀狀態 |
|---|---|---|---|
| 名稱 |
政策的內部名稱。名稱只能使用以下字元：
A-Z0-9._\-$ %。不過，Edge 管理 UI 會強制執行其他限制，例如自動移除非英數字元的字元。
視需要使用 |
N/A | 必填 |
| continueOnError |
設為 false，在政策失敗時傳回錯誤。這是大多數政策的預期行為。
設為 |
false | 選用 |
| 已啟用 |
設為 true 即可強制執行政策。
設為 |
true | 選用 |
| 非同步 | 這項屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性外，您還可以使用這個屬性，在管理 UI 代理項目編輯器中，以其他自然語言名稱標示政策。
| 預設 | 如果省略這個元素，系統會使用政策名稱屬性的值。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
<Source>
<Source>JWS-variable</Source>
如果存在，則指定政策預期會找到要解碼的 JWS 的流程變數。
| 預設 | request.header.authorization (請參閱上方的附註，瞭解預設值的重要資訊)。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
| 有效值 | Edge 流程變數名稱 |
流程變數
成功時，已設定「Verify JWS」(驗證 JWS) 和「Decode JWS」(解碼 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 時加入)。另請參閱「使用 JSON 網路金鑰組 (JWKS)。」在 JWT 和 JWS 中 政策總覽，藉此驗證 JWS。 詳情請參閱(金鑰 ID) 標頭參數。 |
header.type |
標頭類型值。 詳情請見(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。 |
|
|
其他可能的部署錯誤。 |
錯誤變數
系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。
| 變數 | 地點 | 範例 |
|---|---|---|
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>