本頁面由 Cloud Translation API 翻譯而成。

驗證 JWT 政策

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

結果

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

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

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

影片

請觀看短片，瞭解如何驗證 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 演算法

注意： 請使用同一個範例來驗證 PS256 或 ES256 演算法。只需變更 <Algorithm>RS256</Algorithm> 的值即可至 PS256 或 ES256。對於 ES256，您也需要指定索引鍵並與演算法相容如要進一步瞭解重要規定，請參閱關於簽名加密演算法。

這個範例政策會驗證使用 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 驗證金鑰的元素，取決於所選的演算法。如下表所示：

演算法	主要元素
HS*	<SecretKey encoding="base16\|hex\|base64\|base64url"> <Value ref="private.secretkey"/> </SecretKey>
RS、ES、PS*	<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>
^*如要進一步瞭解重要規定，請參閱關於簽名加密演算法。

演算法

主要元素

HS*

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

RS*、ES*、PS*

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

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

屬性	說明	預設	外觀狀態
名稱	政策的內部名稱。名稱中可使用的字元僅限於： `A-Z0-9._\-$ %`。不過，邊緣管理 UI 會強制執行額外的限制 (例如自動移除非英數字元的字元)。視需要使用 `<displayname></displayname>` 元素在管理 UI Proxy 編輯器中，以不同的自然語言為政策加上標籤名稱。	不適用	必填
continueOnError	如果設為「`false`」，系統會在政策失敗時傳回錯誤。這是可預期的情況大多數政策的行為如果設為 `true`，即使政策已發生，流程執行作業仍會繼續執行失敗。	false	選用
已啟用	如要強制執行政策，請設為 `true`。將 `false` 設為「關閉」政策。不會強制執行這項政策即使服務仍附加於資料流	true	選用
非同步	此屬性已淘汰。	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* 演算法。

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

<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 酬載是否包含指定的額外憑證附加資訊，且並確認聲明的著作權聲明值一致。

<Claim> 元素支援呼叫的動態字串替換功能訊息範本。

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

預設	不適用
外觀狀態	選用
類型	字串、數字、布林值或地圖
陣列	設為 true，表示值是否為類型的陣列。預設：否
有效值	你想要用於其他版權聲明的任何值。

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

name - (必填) 著作權聲明的名稱。
注意：請勿在這個元素中使用任何已註冊的著作權聲明名稱。已註冊的聲明會在 RFC7519 中指定。包括：「iss」、「sub」、「aud」、「iat」、「exp」、「nbf」和「jti」。
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 標頭是否包含指定的額外的憑證附加資訊名稱/值組合，以及聲明的值是否相符。

<Claim> 元素支援呼叫的動態字串替換功能訊息範本。

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

預設	不適用
外觀狀態	選用
類型	字串 (預設)、數字、布林值或地圖。如果沒有指定類型，則類型會預設為 String。
陣列	設為 true，表示值是否為類型的陣列。預設：否
有效值	你想要用於其他版權聲明的任何值。

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

name - (必填) 著作權聲明的名稱。
注意：請勿在這個元素中使用任何已註冊的著作權聲明名稱。已註冊的聲明會在 RFC7519 中指定。包括：「iss」、「sub」、「aud」、「iat」、「exp」、「nbf」和「jti」。
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。

預設	不適用
外觀狀態	選用
類型	字串或參照。
有效值	包含 ID 的字串或流程變數名稱。

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

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

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

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

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

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

注意： VerifyJWT 政策實際上不會處理或處理 <KnownHeaders> 元素列出的標頭。之後可在 Proxy 中使用或後端處理這些標頭

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

<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 之一時才使用。

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

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

預設	不適用
外觀狀態	如要使用 RSA 演算法驗證 JWT，您必須使用憑證、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 其中之一。

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

<SecretKey/Value>

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

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

預設	不適用
外觀狀態	HMAC 演算法的必要欄位。
類型	字串
有效值	`encoding` 的有效值為 `hex`、`base16`、`base64`、或 `base64url`。`hex` 和 `base16` 編碼值是同義詞。使用 ref 屬性以流程變數的形式傳遞金鑰注意：如果資料流變數，其前置字串必須為「private」。例如： `private.mysecret`

<Source>

<Source>jwt-variable</Source>

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

注意：根據預設，系統會從變數中擷取 JWT request.header.authorization.在此情況下，Edge 會在要求 Authorization 標頭。若您透過 Authorization 標頭傳遞 JWT，就不需要將來源元素納入政策；但您「必須」包括驗證標頭中的「Bearer」。舉例來說，您可以透過 Authorization 標頭如下所示：

curl -v http://52.200.92.187:9001/doctest-jwt/verify-rs256 -H "Authorization: Bearer <your JWT>"

您可以設定政策，從表單或查詢參數變數中擷取 JWT，或是其他任何變數都沒問題如果變數不存在，或是政策找不到 JWT 傳回錯誤。

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

<Subject>

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

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

預設	不適用
外觀狀態	選用
類型	字串
有效值	可明確識別主旨的任何值。

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

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

預設	0 秒 (無寬限期)
外觀狀態	選用
類型	字串
有效值	包含值的資料值或資料流變數的參照。時間範圍可以是可以指定如下： s = 秒公尺 = 分鐘 h = 小時 d = 天

流程變數

成功執行時，已設定 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 提供此值)

變數名稱	說明
`claim.audience`	JWT 目標對象憑證附加資訊。這個值可以是字串或字串陣列。
`claim.expiry`	到期日/時間，以 Epoch 紀元時間起算的毫秒數表示。
`claim.issuedat`	權杖的核發日期，以 Epoch 紀元時間起算的毫秒數表示。
`claim.issuer`	JWT 核發者憑證附加資訊。
`claim.notbefore`	如果 JWT 包含 nbf 憑證附加資訊，則這個變數會包含值。以毫秒為單位，自 Epoch 紀元時間起算。
`claim.subject`	JWT 主體憑證附加資訊。
`claim.name`	酬載中指定聲明的值 (標準或額外值)，系統會在以下情況下設定中的所有憑證附加資訊
`decoded.claim.name`	酬載中已命名聲明 (標準或其他額外) 的可剖析值 (JSON 可剖析)。針對以下項目設定一個變數：設定中的所有憑證附加資訊舉例來說，您可以使用 `decoded.claim.iat` 執行下列操作：擷取 JWT 的核發時間，從 Epoch 紀元時間起算，以秒為單位。當您時也可以使用 `claim.name` 流程變數，這就是我們推薦的變數，用於存取聲明。
`decoded.header.name`	酬載中標頭的 JSON 可剖析值。針對以下項目設定一個變數：。雖然您也可以使用 `header.name` 流程變數，這是存取標頭的建議變數。
`expiry_formatted`	到期日/時間，格式為使用者可理解的字串。範例： 2017-09-28T21:30:45.000+0000
`header.algorithm`	JWT 使用的簽署演算法。例如 RS256、HS384 等。詳情請參閱「(演算法) 標頭參數」。
`header.kid`	金鑰 ID (如果已在產生 JWT 時新增)。另請參閱「使用 JSON 網路金鑰組 (JWKS)。」位於 JWT 政策總覽，以便驗證 JWT。詳情請參閱(金鑰 ID) 標頭參數。
`header.type`	將設為 `JWT`。
`header.name`	命名標頭的值 (標準或其他)。系統會在以下情況下 JWT 的標頭部分
`header-json`	JSON 格式的標頭。
`is_expired`	true 或 false
`payload-claim-names`	JWT 支援的憑證附加資訊陣列。
`payload-json`	採用 JSON 格式的酬載。
`seconds_remaining`	權杖過期前的秒數。如果權杖已過期，將會是負數
`time_remaining_formatted`	權杖過期前的時間長度，格式為使用者可理解的字串。範例：00:59:59.926
`valid`	以 VerifyJWT 來說，簽名已驗證後，這個變數就會是 true。目前時間是在權杖到期前，以及符記 notBefore 值之後 (如果有的話) 。否則為 false。如果是 DecodeJWT 則未設定此變數。

錯誤參考資料

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

執行階段錯誤

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

錯誤代碼	HTTP 狀態	發生時機
`steps.jwt.AlgorithmInTokenNotPresentInConfiguration`	401	驗證政策採用多個演算法時發生。
`steps.jwt.AlgorithmMismatch`	401	產生政策中指定的演算法與驗證政策中預期的演算法不符。指定的演算法必須相符。
`steps.jwt.FailedToDecode`	401	政策無法解碼 JWT。JWT 可能損毀。
`steps.jwt.GenerationFailed`	401	政策無法產生 JWT。
`steps.jwt.InsufficientKeyLength`	401	如果金鑰在 HS256 演算法中的資料量小於 32 個位元組，HS386 演算法需少於 48 個位元組，HS512 演算法則小於 64 個位元組。
`steps.jwt.InvalidClaim`	401	可能是因為缺少版權聲明或版權聲明不符，或是缺少標題或標頭不符的情形。
`steps.jwt.InvalidCurve`	401	索引鍵指定的曲線不適用於橢圓曲線演算法。
`steps.jwt.InvalidJsonFormat`	401	標頭或酬載含有無效的 JSON。
`steps.jwt.InvalidToken`	401	如果 JWT 簽名驗證失敗，就會發生這個錯誤。
`steps.jwt.JwtAudienceMismatch`	401	權杖驗證失敗，目標對象聲明失敗。
`steps.jwt.JwtIssuerMismatch`	401	核發機構憑證驗證失敗。
`steps.jwt.JwtSubjectMismatch`	401	驗證權杖的主體擁有權聲明失敗。
`steps.jwt.KeyIdMissing`	401	驗證政策會使用 JWKS 做為公開金鑰來源，但已簽署的 JWT 不會在標頭中加入 `kid` 屬性。
`steps.jwt.KeyParsingFailed`	401	無法從指定的金鑰資訊剖析公開金鑰。
`steps.jwt.NoAlgorithmFoundInHeader`	401	發生於 JWT 未包含演算法標頭時。
`steps.jwt.NoMatchingPublicKey`	401	驗證政策會使用 JWKS 做為公開金鑰來源，但已簽署 JWT 中的 `kid` 並未列在 JWKS 中。
`steps.jwt.SigningFailed`	401	在 GenerateJWT 中，金鑰大小必須小於 HS384 或 HS512 演算法的下限
`steps.jwt.TokenExpired`	401	政策會嘗試驗證過期的權杖。
`steps.jwt.TokenNotYetValid`	401	憑證尚未生效。
`steps.jwt.UnhandledCriticalHeader`	401	在 `crit` 標頭中驗證 JWT 政策找到的標頭不在 `KnownHeaders` 中。
`steps.jwt.UnknownException`	401	發生不明例外狀況。
`steps.jwt.WrongKeyType`	401	指定的金鑰類型有誤。舉例來說，如果您為橢圓曲線演算法指定 RSA 金鑰，或是為 RSA 演算法指定曲線鍵，

部署錯誤

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

錯誤名稱	原因	修正
`InvalidNameForAdditionalClaim`	如果 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中使用的憑證聲明是下列任一註冊名稱，部署作業就會失敗：`kid`、`iss`、`sub`、`aud`、`iat`、`exp`、`nbf` 或 `jti`。
`InvalidTypeForAdditionalClaim`	如果 `<AdditionalClaims>` 元素子項元素 `<Claim>` 中使用的憑證聲明不是 `string`、`number`、`boolean` 或 `map` 類型，部署作業就會失敗。
`MissingNameForAdditionalClaim`	如未在 `<AdditionalClaims>` 元素的子元素 `<Claim>` 中指定憑證附加資訊，部署作業就會失敗。
`InvalidNameForAdditionalHeader`	當 `<AdditionalClaims>` 元素的子元素 `<Claim>` 使用的聲明名稱是 `alg` 或 `typ` 時，就會發生這個錯誤。
`InvalidTypeForAdditionalHeader`	如果 `<AdditionalClaims>` 元素子項元素 `<Claim>` 中使用的聲明類型不是 `string`、`number`、`boolean` 或 `map`，部署就會失敗。
`InvalidValueOfArrayAttribute`	如果 `<AdditionalClaims>` 元素中子元素 `<Claim>` 的陣列屬性值未設為 `true` 或 `false`，就會發生這個錯誤。
`InvalidValueForElement`	如果 `<Algorithm>` 元素中指定的值不是支援的值，部署作業就會失敗。
`MissingConfigurationElement`	如果 `<PrivateKey>` 元素未與 RSA 系列演算法搭配使用，或是 `<SecretKey>` 元素並未與 HS 系列演算法搭配使用，就會發生這個錯誤。
`InvalidKeyConfiguration`	如果未在 `<PrivateKey>` 或 `<SecretKey>` 元素中定義子項元素 `<Value>`，部署就會失敗。
`EmptyElementForKeyConfiguration`	如果 `<PrivateKey>` 或 `<SecretKey>` 元素子項元素 `<Value>` 的 ref 屬性為空白或未指定，則部署作業將會失敗。
`InvalidConfigurationForVerify`	如果在 `<SecretKey>` 元素中定義 `<Id>` 元素，就會發生這個錯誤。
`InvalidEmptyElement`	如果驗證 JWT 政策的 `<Source>` 元素為空白，就會發生這個錯誤。如果有，則必須以 Edge 流程變數名稱定義。
`InvalidPublicKeyValue`	如果 `<PublicKey>` 元素子項元素 `<JWKS>` 中使用的值未使用 RFC 7517 中指定的有效格式，部署作業就會失敗。
`InvalidConfigurationForActionAndAlgorithm`	如果將 `<PrivateKey>` 元素與 HS 系列演算法搭配使用，或是將 `<SecretKey>` 元素與 RSA Family 演算法搭配使用，部署作業就會失敗。

錯誤變數

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

變數	地點	範例
`fault.name="fault_name"`	`fault_name` 是錯誤的名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤程式碼的最後部分。	`fault.name Matches "TokenExpired"`
`JWT.failed`	如果失敗時，所有 JWT 政策都會設定相同的變數。	`JWT.failed = true`

錯誤回應範例

JWT 政策錯誤代碼

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

驗證 JWT 政策

結果

影片

範例

驗證以 HS256 簽署的 JWT 演算法

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

設定主要元素

元素參照

適用於 頂層元素

&lt;DisplayName&gt;

&lt;Algorithm&gt;

&lt;Audience&gt;

&lt;AdditionalClaims/Claim&gt;

&lt;AdditionalHeaders/Claim&gt;

&lt;CustomClaims&gt;

&lt;Id&gt;

&lt;IgnoreCriticalHeaders&gt;

&lt;IgnoreIssuedAt&gt;

&lt;IgnoreUnresolvedVariables&gt;

&lt;Issuer&gt;

&lt;KnownHeaders&gt;

&lt;PublicKey/Certificate&gt;

&lt;PublicKey/JWKS&gt;

&lt;PublicKey/Value&gt;

&lt;SecretKey/Value&gt;

&lt;Source&gt;

&lt;Subject&gt;

&lt;TimeAllowance&gt;

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

適用於頂層元素

<DisplayName>

<Algorithm>

<Audience>

<AdditionalClaims/Claim>

<AdditionalHeaders/Claim>

<CustomClaims>

<Id>

<IgnoreCriticalHeaders>

<IgnoreIssuedAt>

<IgnoreUnresolvedVariables>

<Issuer>

<KnownHeaders>

<PublicKey/Certificate>

<PublicKey/JWKS>

<PublicKey/Value>

<SecretKey/Value>

<Source>

<Subject>

<TimeAllowance>