驗證 WWS 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

驗證從用戶端或其他系統收到的 JWS 上的簽章。這項政策也會將標頭擷取至內容變數，以便後續政策或條件檢查這些值，做出授權或路由決策。如需詳細介紹，請參閱「JWS 和 JWT 政策總覽」。

如果 JWS 已驗證且有效，系統就會允許要求繼續進行。如果無法驗證 JWS 簽名，或是 JWS 因某種錯誤而無效，則所有處理作業都會停止，並在回應中傳回錯誤。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

如要瞭解 JWS 的各個部分，以及如何加密及簽署，請參閱 RFC7515。

影片

請觀看短片，瞭解如何驗證 JWS 上的簽名。雖然這部影片專門說明如何驗證 JWT，但許多概念與 JWS 相同。

範例

• 驗證附加的 JWS，該 JWS 已使用 HS256 演算法簽署
• 驗證使用 RS256 演算法簽署的獨立 JWS

驗證使用 HS256 演算法簽署的附加 JWS

這個範例政策會驗證附加的 JWS，該 JWS 是使用 HS256 加密演算法 HMAC 和 SHA-256 總和檢查碼簽署。透過名為 JWS 的表單參數，在 Proxy 要求中傳遞 JWS。鍵包含在名為 private.secretkey 的變數中。

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

header.payload.signature

政策設定包含 Apigee 解碼及評估 JWS 所需的資訊，例如 JWS 所在位置 (在 <Source> 元素中指定的流程變數)、所需的簽署演算法，以及機密金鑰所在位置 (儲存在 Apigee 流程變數中，例如可從 Apigee 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>

這項政策會將輸出內容寫入內容變數，以便 API Proxy 中的後續政策或條件檢查這些值。如需這項政策設定的變數清單，請參閱「流程變數」。

驗證使用 RS256 演算法簽署的獨立 JWS

這個範例政策會驗證使用 RS256 演算法簽署的獨立 JWS。如要驗證，您必須提供公開金鑰。透過名為 JWS 的表單參數，在 Proxy 要求中傳遞 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>

這項政策會將輸出內容寫入內容變數，以便 API Proxy 中的後續政策或條件檢查這些值。如需這項政策設定的變數清單，請參閱「流程變數」。

設定關鍵元素

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

<SecretKey>
  <Value ref="private.secretkey"/>
</SecretKey>

<PublicKey>
  <Value ref="rsa_public_key"/>
</PublicKey>

<PublicKey>
  <JWKS ref="jwks_val_ref_or_url"/>
</PublicKey>

元素參照

政策參考資料說明瞭 Verify JWS 政策的元素和屬性。

注意：設定會因使用的加密演算法而有所不同。如需特定用途的設定範例，請參閱「範例」。

套用至頂層元素的屬性

<VerifyJWS name="JWS" continueOnError="false" enabled="true" async="false">

以下屬性適用於所有政策父元素。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

指定用來簽署權杖的加密演算法。RS*/PS*/ES* 演算法會採用公開/密鑰組，而 HS* 演算法則會採用共用密鑰。另請參閱「 關於簽章加密演算法」。

您可以指定多個值，並以半形逗號分隔。例如「HS256, HS512」或「RS256, PS256」。 不過，HS* 演算法和 ES* 演算法都需要特定的鍵類型，因此無法與其他演算法結合。您可以結合 RS* 和 PS* 演算法。

<AdditionalHeaders/Claim>

<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 要求項式名稱。額外聲明的值可以是字串、數字、布林值、地圖或陣列。圖是一組名稱/值組合。您可以在政策設定中明確指定任何類型的權杖值，也可以間接指定流程變數。

<Claim> 元素的屬性如下：

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

<DetachedContent>

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

產生的 JWS 包含內容酬載，格式如下：

header.payload.signature

如果您使用「GenerateJWS」政策建立未連結的酬載，系統會省略酬載，並產生以下格式的 JWS：

header..signature

如果是分離的酬載，您必須使用 <DetachedContent> 元素將酬載傳遞至 VerifyJWS 政策。指定的內容酬載必須是建立 JWS 簽章時的原始未編碼形式。

在下列情況下，政策會擲回錯誤：

• 如果 JWS 不含分離的內容酬載 (錯誤代碼為 steps.jws.ContentIsNotDetached)，就會指定 <DetachedContent>。
• <DetachedContent> 已省略，且 JWS 具有分離的內容酬載 (錯誤代碼為 steps.jws.InvalidSignature)。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

如果您希望政策在 JWS 的 crit 標頭中列出的任何標頭未列於 <KnownHeaders> 元素中時擲回錯誤，請將此屬性設為 false。設為 true 可讓 VerifyJWS 政策忽略 crit 標頭。

將這個元素設為 true 的原因之一，是如果您處於測試環境，且不希望政策因缺少標頭而失敗，

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

如果您希望政策在無法解析政策中指定的任何參照變數時擲回錯誤，請將此屬性設為 false。將其設為 true，即可將任何無法解析的變數視為空字串 (空值)。

<KnownHeaders>

<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。

<PublicKey/JWKS>

<!-- 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 包含在 JWKS 組合中的金鑰 ID，政策就會使用正確的公開金鑰驗證 JWS 簽名。如要進一步瞭解這項功能，請參閱「 使用 JSON Web 金鑰集合 (JWKS) 驗證 JWS」一文。

如果您從公開網址擷取值，Apigee 會將 JWKS 快取 300 秒。快取過期後，Apigee 會再次擷取 JWKS。

<PublicKey/Value>

<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 簽名的公開金鑰。使用 ref 屬性在流程變數中傳遞金鑰，或直接指定 PEM 編碼金鑰。僅在演算法為 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 時使用。

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Value ref="private.your-variable-name"/>
</SecretKey>
  

指定驗證使用對稱 (HS*) 演算法 (HS256、HS384 或 HS512 其中之一) 的 JWS 時要使用的秘密金鑰。

此元素為選用元素。不過，您必須包含 <PublicKey> 或 <SecretKey> 元素。驗證演算法為 RS*、PS* 或 ES* 的 JWS 時，請使用 <PublicKey> 元素；驗證演算法為 HS* 的 JWS 時，請使用 <SecretKey> 元素。

<SecretKey> 的子項

下表說明 <SecretKey> 的子元素和屬性：

<SecretKey encoding="base64" >
  <Value ref="private.secretkey"/>
</SecretKey>

<SecretKey>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

<Source>

<Source>JWS-variable</Source>

如果存在，則會指定流程變數，政策會在該變數中尋找要驗證的 JWS。

<Type>

<Type>type-string-here</Type>

選用元素，其唯一允許的值為 Signed，可指定政策驗證已簽署的 JWS。<Type> 只是為了與 GenerateJWT 和 VerifyJWT 政策的對應元素相符 (可採用 Signed 或 Encrypted 的任一值)。

流程變數

成功後，「Verify JWS」和「Decode JWS」政策會根據以下模式設定內容變數：

jws.{policy_name}.{variable_name}

舉例來說，如果政策名稱為 verify-jws，則政策會將 JWS 中指定的演算法儲存至這個內容變數：jws.verify-jws.header.algorithm

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤變數

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

錯誤回應範例

針對錯誤處理，最佳做法是將錯誤的 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>