驗證 JWT 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

執行這項政策時，Edge 會驗證 JWT 的簽章，並根據到期時間和生效時間 (如有) 驗證 JWT 是否有效。這項政策也可以選擇性驗證 JWT 中特定憑證附加資訊的值，例如主體、發行者、目標對象或額外憑證附加資訊的值。

如果 JWT 經過驗證且有效，系統會將 JWT 中包含的所有聲明擷取到環境變數中，供後續政策或條件使用，並允許要求繼續進行。如果無法驗證 JWT 簽章，或 JWT 因其中一個時間戳記而無效，系統會停止所有處理作業，並在回應中傳回錯誤。

如要瞭解 JWT 的各個部分，以及加密和簽署方式，請參閱 RFC7519。

影片

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

範例

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

驗證以 HS256 演算法簽署的 JWT

這個範例政策會驗證以 HS256 加密演算法簽署的 JWT，並使用 SHA-256 總和檢查碼的 HMAC。JWT 會透過名為 jwt 的表單參數，在 Proxy 要求中傳遞。金鑰包含在名為 private.secretkey 的變數中。 如需完整範例，包括如何向政策提出要求，請參閱上方影片。

政策設定包含 Edge 解碼及評估 JWT 時所需的資訊，例如 JWT 的位置 (在「來源」元素中指定的流程變數)、必要的簽署演算法、私密金鑰的位置 (儲存在 Edge 流程變數中，例如可能從 Edge KVM 擷取)，以及一組必要聲明及其值。

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

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

驗證以 RS256 演算法簽署的 JWT

這個範例政策會驗證以 RS256 演算法簽署的 JWT。如要驗證，請提供公開金鑰。JWT 會透過名為 jwt 的表單參數，在 Proxy 要求中傳遞。公開金鑰包含在名為 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 中包含的「sub」憑證附加資訊與政策設定中「Subject」元素所需的值不符。

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

設定主要元素

用來指定驗證 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>

元素參考資料

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

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

適用於頂層元素的屬性

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

所有政策父項元素都有下列屬性。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<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 中的目標對象聲明是否與設定中指定的值相符。如果沒有相符項目，政策會擲回錯誤。這項聲明會識別 JWT 的目標收件者。這是 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 - (選用) 其中一個：字串 (預設)、數字、布林值或對應
• array - (選用) 設為 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 - (選用) 其中一個：字串 (預設)、數字、布林值或對應
• array - (選用) 設為 true，表示值是否為型別陣列。預設值： false。

<CustomClaims>

注意：目前透過 UI 新增 GenerateJWT 政策時，系統會插入 CustomClaims 元素。這個元素無法運作，因此遭到忽略。請改用 <AdditionalClaims> 元素。使用者介面會在稍後更新，插入正確的元素。

<Id>

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

驗證 JWT 是否具有特定 jti 聲明。如果文字值和 ref 屬性都空白，政策會產生含有隨機 UUID 的 jti。JWT ID (jti) 聲明是 JWT 的專屬 ID。如要進一步瞭解 jti，請參閱 RFC7519。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

如果 JWT 的 crit 標頭中列出的任何標頭未列在 <KnownHeaders> 元素中，請將這項政策設為 false，讓政策擲回錯誤。設為 true，讓 VerifyJWT 政策忽略 crit 標頭。

如果處於測試環境，且尚未準備好因缺少標頭而導致失敗，則可將這個元素設為 true。

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

如果希望政策在 JWT 包含指定未來時間的「簽發時間」iat聲明時擲回錯誤，請設為 false (預設值)。設為 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 政策，將 <IgnoreCriticalHeaders> 元素設為 true，藉此忽略 crit 標頭。

<PublicKey/Certificate>

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

指定用於驗證 JWT 簽章的簽署憑證。使用 ref 屬性在流程變數中傳遞簽署的憑證，或直接指定 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 含有 JWKS 集中的金鑰 ID，政策就會使用正確的公開金鑰驗證 JWT 簽章。如要進一步瞭解這項功能，請參閱「 使用 JSON Web Key Set (JWKS) 驗證 JWT」。

如果您從公開網址擷取值，Edge 會將 JWKS 快取 300 秒。快取過期時，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 簽名的公開金鑰或公開憑證。使用 ref 屬性在流程變數中傳遞金鑰/憑證，或直接指定 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 中的主體是否與政策設定中指定的字串相符。這項聲明會識別或聲明 JWT 的主體。這是 RFC7519 中提及的一組標準聲明。

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

時間的「寬限期」。舉例來說，如果時間容許量設為 60 秒，過期的 JWT 在聲明到期後 60 秒內，仍會視為有效。系統會以類似方式評估 not-before-time。預設值為 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 提供此值)

錯誤參考資料

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤變數

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

錯誤回應範例

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