驗證 WWS 政策

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

結果

在從用戶端或其他系統接收的 JWS 上驗證簽章。這項政策也 將標頭擷取至內容變數，以便之後檢查政策或條件 並做出授權或轉送決策 如需詳細的介紹，請參閱 JWS 和 JWT 政策總覽。

如果 JWS 已通過驗證且有效， 才能繼續操作如果無法驗證 JWS 簽章，或因 某些類型的錯誤，所有處理作業都會停止，而回應中會傳回錯誤。

如要進一步瞭解 JWS 的組成部分，以及這些元件的加密與簽署方式，請參閱 RFC7515。

影片

觀看短片，瞭解如何驗證 JWS 上的簽名。這部影片 而 JWS 的許多概念都與 JWT 相同。

範例

確認已隨 HS256 簽署的 JWS 演算法

這個範例政策會驗證以 HS256 加密演算法 HMAC 簽署的附加 JWS 透過 SHA-256 核對和檢查碼系統會使用名稱為 JWS。金鑰包含在名為 private.secretkey 的變數中。

附加的 JWS 包含經過編碼的標頭、酬載和簽章：

header.payload.signature

政策設定包括 Edge 需要解碼及評估 JWS 的資訊。 例如，要在哪裡找到 JWS (在 <Source> 元素中指定的資料流變數中) 必要的簽署演算法，以及密鑰 (儲存在 Edge 流程變數中， 已從 Edge KVM 擷取出來)。

<VerifyJWS name="JWS-Verify-HS256">
    <DisplayName>JWS Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
</VerifyJWS>

政策會將輸出內容寫入結構定義變數，以供後續的政策或條件 都能檢查這些值。請參閱流程變數以瞭解 政策設定的變數清單。

驗證與 RS256 簽署的卸離的 JWS 演算法

這個範例政策會驗證使用 RS256 演算法簽署的卸離 JWS。方法如下 您需要提供公開金鑰系統會使用表單參數，在 Proxy 要求中傳遞 JWS 名為 JWS。公開金鑰包含在名為 public.publickey 的變數中。

卸離的 JWS 會省略 JWS 中的酬載：

header..signature

您可決定將酬載傳送至 VerifyJWS 政策，方法是將包含酬載的變數名稱指定至 <DetachedContent> 元素。「<DetachedContent>」中的指定內容 需採用 JWS 簽名建立時的原始未編碼格式。

<VerifyJWS name="JWS-Verify-RS256">
    <DisplayName>JWS Verify RS256</DisplayName>
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.JWS</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <DetachedContent>private.payload</DetachedContent>
</VerifyJWS>

政策會將輸出內容寫入結構定義變數，以供後續的政策或條件 都能檢查這些值。請參閱流程變數以瞭解 政策設定的變數清單。

設定主要元素

您用於指定用於驗證 JWS 金鑰的元素，取決於您選擇的演算法。 如下表所示：

演算法 主要元素
HS* 
<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>
RS*、ES*、PS* 
<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

或是：

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>
*如要進一步瞭解重要規定，請參閱 關於簽名加密演算法。

元素參照

政策參考資料說明「驗證 JWS」政策的元素和屬性。

注意：設定可能會因加密方式而有些許不同 演算法。請參閱「範例」中的使用範例 特定用途的配置設定

適用於 頂層元素

<VerifyJWS 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;Algorithm&gt;

<Algorithm>HS256</Algorithm>

指定用來簽署權杖的加密演算法。RS*/PS*/ES* 演算法採用公開/密鑰金鑰組 而 HS* 演算法則是共用機密另請參閱 關於簽名加密演算法。

如要指定多個值，請以半形逗號分隔。例如「HS256, HS512」或「RS256, PS256」 不過，您無法將 HS* 演算法與任何其他演算法或 ES* 演算法結合在一起，因為 需要特定金鑰類型您可以結合使用 RS* 和 PS* 演算法。

預設 不適用
外觀狀態 必填
類型 逗號分隔值的字串
有效值 HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512

&lt;AdditionalHeaders/Claim&gt;

<AdditionalHeaders>
    <Claim name='claim1'>explicit-value-of-claim-here</Claim>
    <Claim name='claim2' ref='variable-name-here'/>
    <Claim name='claim3' ref='variable-name-here' type='boolean'/>
    <Claim name='claim4' ref='variable-name' type='string' array='true'/>
 </AdditionalHeaders>

驗證 JWS 標頭是否包含指定的其他聲明名稱/值組，且聲明的聲明值相符。

額外聲明所用的名稱不是標準已註冊的 JWS 聲明名稱。 其他憑證附加資訊的值可以是字串、數字、布林值、地圖或陣列。地圖 就是一組名稱/值的組合您可以為上述任一類型的聲明指定值 在政策設定中明確指定，或透過流量變數的參照間接。

預設 不適用
外觀狀態 選用
類型

字串 (預設)、數字、布林值或地圖。

如果沒有指定類型，則類型會預設為 String。
陣列 設為 true，表示值是否為類型的陣列。預設： 否
有效值 你想要用於其他版權聲明的任何值。

<Claim> 元素會採用下列屬性：

  • name - (必填) 著作權聲明的名稱。
  • ref - (選填) 流程變數名稱。如有的話，政策會使用 變數為宣告。如果同時指定了 ref 屬性和明確的聲明值， 此為預設值，如果所參照的流程變數未解析，就會使用這個值。
  • type - (選用) 下列其中一個：字串 (預設)、數字、布林值或地圖
  • 陣列 - (選用) 設為 true，表示值是否為類型的陣列。預設： false。

&lt;DetachedContent&gt;

<DetachedContent>variable-name-here</DetachedContent>

內含內容酬載的 JWS 格式如下：

header.payload.signature

如果您使用 GenerateJWS 政策來建立卸離酬載，則產生的 JWS 會省略酬載， 格式：

header..signature

如果是卸離的酬載，則您必須使用 <DetachedContent> 元素。指定的內容酬載必須位於 原始的未編碼形式。

下列情況會擲回錯誤：

  • 如果 JWS 不含卸離的內容，系統會指定 <DetachedContent> 酬載 (錯誤程式碼為 steps.jws.ContentIsNotDetached)。
  • <DetachedContent> 遭到省略，且 JWS 具有卸離的內容酬載 (錯誤程式碼為 steps.jws.InvalidSignature)。
預設 N/A
外觀狀態 選用
類型 變數參照

&lt;IgnoreCriticalHeaders&gt;

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

如果您希望政策在 JWS 的 crit 標頭不會列在 <KnownHeaders> 元素中。 設為 true 會導致 VerifyJWS 政策忽略 crit 標頭。

如果您位在測試環境中，要將這個元素設為 True 您不希望政策因缺少標頭而失效。

預設 false
外觀狀態 選用
類型 布林值
有效值 true 或 false

&lt;IgnoreUnresolvedVariables&gt;

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

如果您希望政策在指定的參照變數時擲回錯誤，請設為 false 無法解析政策如果設為 true，系統會將任何無法解析的變數視為空白字串 (空值)。

預設 false
外觀狀態 選用
類型 布林值
有效值 true 或 false

&lt;KnownHeaders&gt;

<KnownHeaders>a,b,c</KnownHeaders>

or:

<KnownHeaders ref=’variable_containing_headers’/>

GenerateJWS 政策會使用 <CriticalHeaders> 元素填入 crit 標頭。例如：

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

VerifyJWS 政策會檢查 JWS 中的 crit 標頭 (如果有的話)，以及每個列出的項目 會檢查 <KnownHeaders> 元素是否也會列出該標頭。 <KnownHeaders> 元素可包含 crit 所列項目的超集。 您只需要確認 crit 中列出的所有標頭都要列在 <KnownHeaders> 元素。政策在 crit 中找到的任何標頭 也未列在 <KnownHeaders> 中，會導致 VerifyJWS 政策失敗。

您可以選擇設定 VerifyJWS 政策，以忽略 crit 標頭，方法是： 將 <IgnoreCriticalHeaders> 元素設為 true。

預設 不適用
外觀狀態 選用
類型 以半形逗號分隔的字串陣列
有效值 陣列或包含陣列的變數名稱。

&lt;PublicKey/JWKS&gt;

<!-- Specify the JWKS. -->
<PublicKey>
   <JWKS>jwks-value-here</JWKS>
</PublicKey>

or:

<!-- Specify a variable containing the JWKS. -->
<PublicKey>
   <JWKS ref="public.jwks"/>
</PublicKey>

or:

<!-- Specify a public URL that returns the JWKS.
The URL is static, meaning you cannot set it using a variable. -->
<PublicKey>
   <JWKS uri="jwks-url"/>
</PublicKey>

以 JWKS 格式 (RFC 7517) 指定值 包含一組公開金鑰只有在演算法為 RS256/RS384/RS512 時才使用， PS256/PS384/PS512 或 ES256/ES384/ES512。

如果傳入的 JWS 含有金鑰 ID，這組 ID 會位於 JWKS，政策會使用正確的公開金鑰驗證 JWS 簽章。瞭解詳情 如要進一步瞭解這項功能，請參閱 使用 JSON Web 金鑰組 (JWKS) 驗證 JWS。

如果從公開網址擷取這個值，Edge 會在 300 秒內快取 JWKS。 快取到期時，Edge 會再次擷取 JWKS。

預設 不適用
外觀狀態 如要使用 RSA 演算法驗證 JWS，請務必使用 JWKS 或 Value 元素。
類型 字串
有效值 流程變數、字串值或網址。

&lt;PublicKey/Value&gt;

<PublicKey>
   <Value ref="public.publickey"/>
</PublicKey>
-or-
<PublicKey>
    <Value>
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW
    Q0UrCw5c0+Y707KX3PpXkZGbtTT4nvU1jC0d1lHV8MfUyRXmpmnNxJHAC2F73IyN
    C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n
    Xn/Bs2UbbLlKP5Q1HPxewUDEh0gVMqz9wdIGwH1pPxKvd3NltYGfPsUQovlof3l2
    ALvO7i5Yrm96kknfFEWf1EjmCCKvz2vjVbBb6mp1ZpYfc9MOTZVpQcXSbzb/BWUo
    ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx
    DQIDAQAB
    -----END PUBLIC KEY-----
    </Value>
</PublicKey>

指定用來驗證 JWS 上簽章的公開金鑰。使用參照屬性 以流程變數的形式傳送金鑰，或直接指定 PEM 編碼的金鑰。僅適用於 是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 其中之一。

預設 不適用
外觀狀態 如要驗證以 RSA 演算法簽署的 JWS，您必須使用 JWKS 或 值元素。
類型 字串
有效值 流程變數或字串。

&lt;SecretKey/Value&gt;

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

提供透過 HMAC 演算法驗證或簽署權杖的密鑰。僅使用 當演算法為 HS256、HS384、HS512 之一使用 ref 屬性 以流程變數的形式傳遞金鑰

預設 不適用
外觀狀態 HMAC 演算法的必要欄位。
類型 字串
有效值 參照字串的流量變數。

注意：如果資料流變數，其前置字串必須為「private」。例如： private.mysecret

&lt;Source&gt;

<Source>JWS-variable</Source>

如果有，請指定政策預期在哪個流程變數中找出 JWS 進行驗證

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

流程變數

成功時，已設定「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.AlgorithmInTokenNotPresentInConfiguration 401 驗證政策採用多個演算法時發生
steps.jws.AlgorithmMismatch 401 產生政策在標頭中指定的演算法與驗證政策中預期的演算法不符。指定的演算法必須相符。
steps.jws.ContentIsNotDetached 401 當 JWS 不包含已卸離的內容酬載時，系統會指定 <DetachedContent>。
steps.jws.FailedToDecode 401 政策無法解碼 JWS。JWS 可能已損毀。
steps.jws.InsufficientKeyLength 401 適用於小於 32 個位元組的 HS256 演算法
steps.jws.InvalidClaim 401 可能是因為缺少版權聲明或版權聲明不符，或是缺少標題或標頭不符的情形。
steps.jws.InvalidCurve 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.KeyIdMissing 401 驗證政策會使用 JWKS 做為公開金鑰來源，但已簽署的 JWS 不會在標頭中加入 kid 屬性。
steps.jws.KeyParsingFailed 401 無法從指定的金鑰資訊剖析公開金鑰。
steps.jws.MissingPayload 401 缺少 JWS 酬載。
steps.jws.NoAlgorithmFoundInHeader 401 JWS 省略演算法標頭時發生。
steps.jws.NoMatchingPublicKey 401 驗證政策會使用 JWKS 做為公開金鑰來源，但已簽署 JWS 中的 kid 並未列在 JWKS 中。
steps.jws.UnhandledCriticalHeader 401 透過驗證 JWS 政策在 crit 標頭中找到的標頭未列於 KnownHeaders 中。
steps.jws.UnknownException 401 發生不明例外狀況。
steps.jws.WrongKeyType 401 指定的金鑰類型有誤。舉例來說，如果您為橢圓曲線演算法指定 RSA 金鑰，或是為 RSA 演算法指定曲線鍵，

部署錯誤

若您部署包含這項政策的 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>