DecodeJWS 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。 資訊

結果

這個外掛程式能解碼 JWS 標頭，但不會在 JWS 上驗證簽章，並將每個標頭寫入 流程變數這項政策與 VerifyJWS 政策搭配使用時最實用。 必須在驗證 JWS 簽章之前知道 JWS 中的標頭值。

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

header.payload.signature

或者，JWS 可以省略酬載 (稱為「卸離」酬載)，格式如下：

header..signature

DecodeJWS 政策僅將 JWS 的標頭部分解碼，因此適用於這兩種表單。 無論用於簽署 JWS 的演算法為何，DecodeJWS 政策也能正常運作。

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

影片

請觀看短片，瞭解如何解碼 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._\-$ %。不過，邊緣管理 UI 會強制執行額外的 限制 (例如自動移除非英數字元的字元)。

視需要使用 <displayname></displayname> 元素 在管理 UI Proxy 編輯器中，以不同的自然語言為政策加上標籤 名稱。

 不適用 必填
continueOnError 如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
已啟用 如要強制執行政策，請設為 true。

將 false 設為「關閉」政策。不會強制執行這項政策 即使服務仍附加於資料流

 true 選用
非同步 此屬性已淘汰。 false 已淘汰

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

除了名稱屬性以外，還能在管理 UI Proxy 編輯器中為政策加上標籤 使用不同的自然語言名稱

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

&lt;Source&gt;

<Source>JWS-variable</Source>

如果有，請指定政策預期在哪個流程變數中找出 JWS 解碼器。

預設 request.header.authorization (如需重要資訊，請參閱上方的附註 。
外觀狀態 選用
類型 字串
有效值 邊緣流程變數名稱

Flow variables

Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:

jws.{policy_name}.{variable_name}

For example, if the policy name is verify-jws, then the policy will store the algorithm specified in the JWS to this context variable: jws.verify-jws.header.algorithm

Variable name Description
decoded.header.name The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
header.algorithm The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more.
header.type The header type value. See (Type) Header Parameter for more.
header.name The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWS.
header-json The header in JSON format.
payload The JWS payload if the JWS has an attached payload. For a detached payload, this variable is empty.
valid In the case of VerifyJWS, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false.

In the case of DecodeJWS, this variable is not set.

錯誤參考資料

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 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。

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 其他可能的部署錯誤。

錯誤變數

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

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