本頁適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
結果
解碼 JWS 標頭，但不會驗證 JWS 上的簽名，並將每個標頭寫入流程變數。當您必須先知道 JWS 中的標頭值，才能驗證 JWS 的簽名時，這項政策搭配VerifyJWS 政策使用時最有用。
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 為空白。如需這項政策設定的完整變數清單，請參閱「流程變數」。
解碼 JWS 的元素參考
政策參考資料說明「解碼 JWS」政策的元素和屬性。
套用至頂層元素的屬性
<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">
以下屬性適用於所有政策父元素。
| 屬性 | 說明 | 預設 | 在家狀態 |
|---|---|---|---|
| 名稱 |
政策的內部名稱。您可以在名稱中使用的字元僅限：
A-Z0-9._\-$ %。不過，Apigee UI 會強制執行其他限制，例如自動移除非英數字元的字元。您可以選擇使用 |
不適用 | 必填 |
| continueOnError |
將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 |
false | 選用 |
| 已啟用 |
設為 true 即可強制執行政策。
將其設為 |
是 | 選用 |
| 非同步 | 此屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性之外，您也可以使用其他自然語言名稱，在管理介面 Proxy 編輯器中標示政策。
| 預設 | 如果省略這個元素，系統會使用政策的 name 屬性值。 |
| 在家狀態 | 選用 |
| 類型 | 字串 |
<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>