驗證 JWT 政策

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

結果

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

執行這項政策時，Edge 會驗證 JWT 的簽名，並驗證 JWT 是否為 是否到期，依據是否過期。您可以選擇是否使用這項政策 也會驗證 JWT 的特定憑證附加資訊值，例如主體、發行者、 或額外版權聲明帶來的價值

如果 JWT 經過驗證且有效，則 JWT 中包含的所有憑證附加資訊都會 擷取到結構定義變數中，以供後續政策或條件使用，而要求 才能繼續操作如果無法驗證 JWT 簽名，或由於 JWT 因 其中一個時間戳記的處理程序會停止，回應中也會傳回錯誤。

如要瞭解 JWT 的組成部分，以及這些部分的加密與簽署方式，請參閱 RFC7519 文件。

影片

請觀看短片，瞭解如何驗證 JWT 上的簽名。

範例

• 驗證以 HS256 簽署的 JWT 演算法
• 驗證使用 RS256 簽署的 JWT 演算法

驗證以 HS256 簽署的 JWT 演算法

這個範例政策會驗證使用 HS256 加密演算法 HMAC 簽署的 JWT 透過 SHA-256 核對和檢查碼系統會使用名稱為 jwt。金鑰包含在名為 private.secretkey 的變數中。 如需完整範例，包括如何提出政策申請，請觀看上方影片。

政策設定包括 Edge 需要解碼及評估 JWT 所需的資訊。 例如可以在哪裡找到 JWT (在 Source 元素中指定的資料流變數中)，必要時 簽署演算法，找出密鑰 (儲存在 Edge 流程變數中， 以及一組必要的憑證附加資訊 輕鬆分配獎金

<VerifyJWT name="JWT-Verify-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Algorithm>HS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey encoding="base64">
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
</VerifyJWT>

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

驗證使用 RS256 簽署的 JWT 演算法

這個範例政策會驗證使用 RS256 演算法簽署的 JWT。方法如下 您需要提供公開金鑰系統會使用表單參數，透過 Proxy 要求傳遞 JWT 名為 jwt。公開金鑰包含在名為 public.publickey 的變數中。 如需完整範例，包括如何提出政策申請，請觀看上方影片。

如要進一步瞭解此元素中各元素的需求條件和選項，請參閱 元素 參考資料 範例政策。

<VerifyJWT name="JWT-Verify-RS256">
    <Algorithm>RS256</Algorithm>
    <Source>request.formparam.jwt</Source>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PublicKey>
        <Value ref="public.publickey"/>
    </PublicKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-edge-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>    
    </AdditionalClaims>
</VerifyJWT>

在上述設定中，一個含有此標頭的 JWT...

{
  "typ" : "JWT", 
  "alg" : "RS256"
}

而這個有效負載...

{ 
  "sub" : "apigee-seattle-hatrack-montage",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

如果能以提供的公開簽名驗證 ...，則 ... 將視為有效 鍵。

具有相同標頭，但具有此酬載的 JWT...

{ 
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-edge-JWT-policy-test",
  "aud" : "urn://c60511c0-12a2-473c-80fd-42528eb65a6a",
  "show": "And now for something completely different."
}

即使簽名可以驗證，... 也會判定為無效，因為 「訂閱」JWT 內含之憑證附加資訊與「Subject」的所需值不符元素為 政策設定所指定的內容。

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

設定主要元素

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

<SecretKey encoding="base16|hex|base64|base64url">
  <Value ref="private.secretkey"/>
</SecretKey>

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

<PublicKey>
  <Certificate ref="signed_cert_val_ref"/>
</PublicKey>

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

元素參照

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

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

適用於 頂層元素

<VerifyJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>HS256</Algorithm>

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

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable-name-here'/>

這項政策會驗證 JWT 中的目標對象憑證附加資訊是否與 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定如果沒有任何相符項目，這項政策會擲回錯誤。這項著作權聲明可識別 適用對象。這是前述的登記聲明之一 RFC7519。

<AdditionalClaims/Claim>

<AdditionalClaims>
    <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'/>
 </AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

驗證 JWT 酬載是否包含指定的額外憑證附加資訊，且 並確認聲明的著作權聲明值一致。

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

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

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

加入 <Claim> 元素後，系統會在您回應 設定政策。或者，您可以傳遞 JSON 物件來指定憑證附加資訊名稱。 由於 JSON 物件是以變數的形式傳遞，因此憑證名稱會在執行階段決定。

例如：

<AdditionalClaims ref='json_claims'/>

其中 json_claims 變數包含下列格式的 JSON 物件：

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

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

驗證 JWT 標頭是否包含指定的額外的憑證附加資訊名稱/值組合，以及聲明的值是否相符。

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

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

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

<CustomClaims>

注意：目前當您新增自訂聲明元素時，系統會插入 CustomClaims 元素 透過 UI 產生 JWT 政策。此元素無法運作，因此將遭到忽略。正確 改為使用 <AdditionalClaims>。使用者介面 ，日後就會更新，插入正確的元素。

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

驗證 JWT 是否有特定的 jti 憑證附加資訊。當文字值和參照 屬性都留空，這項政策會產生包含隨機 UUID 的 jti。JWT ID (jti) 憑證附加資訊是 JWT 的唯一識別碼。如要進一步瞭解 jti，請參閱 RFC7519。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

如果您希望政策在 JWT 的 crit 標頭並未列在 <KnownHeaders> 元素中。 設為 true 時，VerifyJWT 政策會忽略 crit 標頭。

之所以必須設定此元素為 True，可能是因為您位於測試環境中且尚未使用 可能引發缺少標頭的狀況。

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

如要在 JWT 含有 iat (核發時) 聲明，指出期限為未來的時間。 如果設為 true，政策在驗證期間就會忽略 iat。

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

這項政策會驗證 JWT 中的核發者是否與 設定元素可識別 JWT 核發者的要求。這是 RFC7519 中提及的一組已註冊聲明。

<KnownHeaders>

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

or:

<KnownHeaders ref=’variable_containing_headers’/>

GenerateJWT 政策會使用 <CriticalHeaders> 元素填入 JWT 中的 crit 標頭。例如：

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

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

您可以選擇設定 VerifyJWT 政策，藉此忽略 crit 標頭 將 <IgnoreCriticalHeaders> 元素設為 true。

<PublicKey/Certificate>

<PublicKey>
   <Certificate ref="signed_public.cert"/>
</PublicKey>
-or-
<PublicKey>
    <Certificate>
    -----BEGIN CERTIFICATE-----
    cert data
    -----END CERTIFICATE-----
    </Certificate>
</PublicKey>

指定用於驗證 JWT 簽名的已簽署憑證。使用參照屬性 以流程變數傳送已簽署的憑證，或直接指定 PEM 編碼憑證。 只有在演算法是 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 之一時才使用。

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

如果傳入的 JWT 具有金鑰 ID，且該 ID 的金鑰集中 JWKS，政策就會使用正確的公開金鑰來驗證 JWT 簽名。瞭解詳情 如要進一步瞭解這項功能，請參閱 使用 JSON Web Key Set (JWKS) 驗證 JWT。

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

<PublicKey/Value>

<PublicKey>
   <Value ref="public.publickeyorcert"/>
</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>

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

<SecretKey/Value>

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

提供透過 HMAC 演算法驗證或簽署權杖的密鑰。僅使用 (輸出值為 HS256、HS384、HS512)

<Source>

<Source>jwt-variable</Source>

如果有，則指定政策預期在哪個流程變數中找到 JWT 進行驗證

<Subject>

<Subject>subject-string-here</Subject>

這項政策會驗證 JWT 中的主體是否與政策中指定的字串相符 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定此憑證附加資訊會識別或發表 JWT 主體。這是 RFC7519 中提及的一組標準憑證附加資訊。

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

「寬限期」時間。舉例來說，如果時間允許設為 60 秒， 在聲明的到期時間過後 60 秒內，過期的 JWT 將視為仍有效。 這類規則同樣會視為同樣有效預設值為 0 秒 (無寬限期)。

流程變數

成功執行時，已設定 Verify JWT 和 Decode JWT 政策 結構定義變數：

jwt.{policy_name}.{variable_name}

舉例來說，如果政策名稱為「jwt-parse-token」，則政策會儲存 在 JWT 中指定的主體傳送至名為 jwt.jwt-parse-token.decoded.claim.sub 的內容變數。 (為顧及回溯相容性，您也可以使用 jwt.jwt-parse-token.claim.subject 提供此值)

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

錯誤變數

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

錯誤回應範例

針對錯誤處理，最佳做法是將錯誤的 errorcode 部分加以包裝 回應。請勿參考 faultstring 中的文字，因為可能會變動。

錯誤規則範例

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "TokenExpired")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>