本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
結果
解碼 JWS 標頭，但不驗證 JWS 的簽章，並將每個標頭寫入流程變數。與 VerifyJWS 政策搭配使用時，這項政策最為實用，因為在驗證 JWS 的簽名之前，必須先知道 JWS 內標頭的值。
JWS 可以有附加酬載，格式如下：
header.payload.signature
或者，JWS 可以省略酬載 (稱為「分離式」酬載)，格式如下：
header..signature
DecodeJWS 政策適用於這兩種形式，因為它只會解碼 JWS 的標頭部分。 無論用來簽署 JWS 的演算法為何，DecodeJWS 政策都能正常運作。
如需詳細介紹和 JWS 格式總覽，請參閱 JWS 和 JWT 政策總覽。
這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。
影片
請觀看短片，瞭解如何解碼 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._\-$ %。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。
視需要使用 |
不適用 | 必填 |
| continueOnError |
設為 false，以便在政策失敗時傳回錯誤。這是大多數政策的預期行為。
設為 |
false | 選用 |
| 已啟用 |
設為 true 即可強制執行政策。
設為 |
是 | 選用 |
| 非同步 | 這項屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性外，您還可以使用這個屬性，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。
| 預設 | 如果省略這個元素，系統會使用政策名稱屬性的值。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
<Source>
<Source>JWS-variable</Source>
如果存在，則指定政策預期會找到要解碼的 JWS 的流程變數。
| 預設 | request.header.authorization (請參閱上方的附註，瞭解預設值的重要資訊)。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
| 有效值 | Apigee 流程變數名稱 |
流程變數
成功後，「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 時新增)。如要驗證 JWS，請參閱「JWT 和 JWS 政策總覽」一文中的「使用 JSON Web 金鑰集合 (JWKS)」一節。詳情請參閱「(Key ID) 標頭參數」。 |
header.type |
標頭類型值。詳情請參閱「(Type) 標頭參數」。 |
header.name |
命名標頭的值 (標準或額外)。在 JWS 的標頭部分，每個額外標頭都會設定其中一個。 |
header-json |
以 JSON 格式提供的標頭。 |
payload |
如果 JWS 有附加的酬載，則為 JWS 酬載。如果是分離的酬載，這個變數會是空白。 |
valid |
在 VerifyJWS 的情況下，如果簽名已驗證，且目前時間在符記到期時間之前，且在符記 notBefore 值之後 (如果有這些值的話)，這個變數就會設為 true。否則為 false。
在 DecodeJWS 的情況下，這個變數並未設定。 |
錯誤參考資料
本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。
執行階段錯誤
政策執行時可能會發生這些錯誤。
| 錯誤代碼 | 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>