DecodeJWS 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

DecodeJWS 政策會解碼 JWS 標頭，但不會驗證 JWS 的簽章，並將每個標頭寫入流程變數。如果 JWS 簽章驗證前必須先知道 JWS 標頭中的值，這項政策與 VerifyJWS 政策搭配使用時最為實用。

JWS 可以附加酬載，格式如下：

header.payload.signature

或者，JWS 可以省略酬載 (稱為「分離式」酬載)，並採用以下格式：

header..signature

DecodeJWS 政策適用於這兩種形式，因為這項政策只會解碼 JWS 的標頭部分。 無論簽署 JWS 時使用的演算法為何，DecodeJWS 政策都能正常運作。

如需詳細簡介和 JWS 格式總覽，請參閱 JWS 和 JWT 政策總覽。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

範例：解碼 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 使用者介面會強制執行其他限制，例如自動移除非英數字元。 視需要使用 <displayname></displayname> 元素，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。	不適用	必填
continueOnError	設為 false，在政策失敗時傳回錯誤。這是大多數政策的預期行為。 設為 true，即使政策失敗，流程執行作業仍會繼續。	false	選用
已啟用	設為 true 即可強制執行政策。 設為 false 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。	true	選用
非同步	這項屬性已淘汰。	false	已淘汰

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了名稱屬性之外，您也可以使用這個屬性，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。

預設	如果省略這個元素，系統會使用政策名稱屬性的值。
外觀狀態	選用
類型	字串

<Source>

<Source>JWS-variable</Source>

如果存在，則指定政策預期會找到要解碼的 JWS 的流程變數。

注意：根據預設，系統會從變數 request.header.authorization 擷取 JWS。在這種情況下，Apigee 會在要求授權標頭中尋找 JWS。如果您在 Authorization 標頭中傳遞 JWS，就不需要在政策中加入 Source 元素；不過，您必須在授權標頭中加入 Bearer。舉例來說，您會在 Authorization 標頭中傳遞 JWS，如下所示：

curl -v http://52.200.92.187:9001/doctest-JWS/verify-rs256 -H "Authorization: Bearer <your JWS>"

您可以設定政策，從表單或查詢參數變數，或任何其他變數擷取 JWS。如果變數不存在，或政策無法找到 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 的情況下，這個變數並未設定。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Occurs when
steps.jws.FailedToDecode	401	The policy was unable to decode the JWS. The JWS is possibly corrupted.
steps.jws.FailedToResolveVariable	401	Occurs when the flow variable specified in the <Source> element of the policy does not exist.
steps.jws.InvalidClaim	401	For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidJsonFormat	401	Invalid JSON found in the JWS header.
steps.jws.InvalidJws	401	This error occurs when the JWS signature verification fails.
steps.jws.InvalidPayload	401	The JWS payload is invalid.
steps.jws.InvalidSignature	401	<DetachedContent> is omitted and the JWS has a detached content payload.
steps.jws.MissingPayload	401	The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader	401	Occurs when the JWS omits the algorithm header.
steps.jws.UnknownException	401	An unknown exception occurred.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Occurs when
InvalidAlgorithm	The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512.
EmptyElementForKeyConfiguration FailedToResolveVariable InvalidConfigurationForActionAndAlgorithmFamily InvalidConfigurationForVerify InvalidEmptyElement InvalidFamiliesForAlgorithm InvalidKeyConfiguration InvalidNameForAdditionalClaim InvalidNameForAdditionalHeader InvalidPublicKeyId InvalidPublicKeyValue InvalidSecretInConfig InvalidTypeForAdditionalClaim InvalidTypeForAdditionalHeader InvalidValueForElement InvalidValueOfArrayAttribute InvalidVariableNameForSecret MissingConfigurationElement MissingElementForKeyConfiguration MissingNameForAdditionalClaim MissingNameForAdditionalHeader	Other possible deployment errors.

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。

變數	地點	範例
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>