驗證 JWT 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

驗證從用戶端或其他系統接收的 JWT 簽名。這項政策也會將憑證附加資訊擷取到內容變數中,以便後續的政策或條件檢查這些值,以便進行授權或轉送決策。詳情請參閱 JWS 和 JWT 政策總覽

執行這項政策時,Edge 會驗證 JWT 的簽名,並依據到期時間驗證 JWT 是否有效 (如有到期)。政策也可以選擇驗證 JWT 上特定憑證附加資訊的值,例如主體、核發者、目標對像或其他憑證附加資訊的值。

如果 JWT 已通過驗證且有效,系統會將 JWT 中包含的所有憑證附加資訊擷取至內容變數,供後續政策或條件使用,而要求可以繼續進行。如果無法驗證 JWT 簽名,或是 JWT 因其中一個時間戳記而無效,則所有處理程序都會停止,回應中也會傳回錯誤。

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

影片

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

範例

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

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

政策設定包括 Edge 解碼及評估 JWT 所需的資訊,例如在 Source 元素中指定的流程變數中該尋找 JWT 的位置、必要的簽署演算法、哪裡可以找到密鑰 (儲存於 Edge KVM 中,該變數可能可從 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」憑證附加資訊與政策設定中指定的「主旨」值不符,因此即使簽名可通過驗證,... 也會被判定為無效。

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

設定重要元素

您用來驗證 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>
*如要進一步瞭解金鑰相關規定,請參閱「關於簽名加密演算法」一文。

元素參照

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

注意:視您使用的加密演算法而定,設定可能略有不同。如需特定用途的設定範例,請參閱範例

套用至頂層元素的屬性

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

以下是所有政策父項元素的通用屬性。

屬性 說明 預設 外觀狀態
名稱 政策的內部名稱。名稱中使用的字元僅限 A-Z0-9._\-$ %。不過,Edge 管理 UI 會強制執行其他限制,例如自動移除非英數字元。

您也可以選擇使用 <displayname></displayname> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 必要
continueOnError 如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
已啟用 如要強制執行政策,請設為 true

設為 false 即可「停用」政策。即使政策仍附加在流程中,系統也不會強制執行政策。

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* 演算法。

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

<Audience>

<Audience>audience-here</Audience>

or:

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

政策會驗證 JWT 中的目標對象憑證附加資訊與設定中指定的值是否相符。如果找不到相符項目,政策會擲回錯誤。這項憑證聲明會識別 JWT 適用的收件者。這是 RFC7519 中所述的其中一項註冊憑證附加資訊。

預設 不適用
外觀狀態 選用
類型 字串
有效值 用來識別目標對象的流程變數或字串。

<其他聲明/版權聲明>

<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 憑證附加資訊的任何名稱。其他憑證附加資訊的值可以是字串、數字、布林值、地圖或陣列。地圖只是一組名稱/值組合。這類聲明的值可在政策設定中明確指定,也可以透過流程變數參照間接指定。

預設 不適用
外觀狀態 選用
類型 字串、數字、布林值或地圖
陣列 設為 true,表示該值是類型的陣列。預設值:false
有效值 你要用於額外聲明的任何值。

<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 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 憑證附加資訊的任何名稱。其他聲明的值可以是字串、數字、布林值、地圖或陣列。地圖只是一組名稱/值組合。這類聲明的值可在政策設定中明確指定,也可以透過流程變數參照間接指定。

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

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

如果未指定類型,則類型會預設為「字串」。

陣列 設為 true,表示該值是類型的陣列。預設值:false
有效值 你要用於額外聲明的任何值。

<Claim> 元素採用以下屬性:

  • name - (必填) 版權聲明的名稱。
  • ref - (選用) 流程變數的名稱。如果存在,政策會使用這個變數的值做為聲明。如果同時指定 ref 屬性和明確的憑證附加資訊值,系統預設會使用明確的值,並在參照流程變數未解析時使用。
  • type - (選用) 其中之一:字串 (預設值)、數字、布林值或地圖
  • 陣列 - (選用) 設為 true,表示該值是類型陣列。預設值:false。

<CustomClaims>

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

<編號>

<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

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

<IgnoreCriticalHeaders>

<IgnoreCriticalHeaders>true|false</IgnoreCriticalHeaders>

如果 <KnownHeaders> 元素中未列出 JWT 的 crit 標頭中列出的任何標頭,請設為 false。設為 true 即可讓 VerifyJWT 政策忽略 crit 標頭。

將這個元素設為 true 的一個原因,是您目前在測試環境中,但尚未準備好在缺少標頭時發生失敗問題。

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

<IgnoreIssuedAt>

<IgnoreIssuedAt>true|false</IgnoreIssuedAt>

如果希望政策在 JWT 包含指定了未來時間的 iat (核發時) 憑證附加資訊時擲回錯誤,請設為 false (預設)。如果設為 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> 元素可包含條件所列項目的超集。只有在 條件 中列出的所有標頭都必須列在 <KnownHeaders> 元素中即可。凡是在 條件中找到且未列於 <KnownHeaders> 的標頭,都會導致 VerifyJWT 政策失敗。

您可以選擇將 <IgnoreCriticalHeaders> 元素設為 true,藉此將 VerifyJWT 政策設為忽略 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 的演算法。

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

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

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

<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 的演算法。

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

<SecretKey/Value>

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

提供透過 HMAC 演算法驗證或簽署權杖的密鑰。只有在演算法為 HS256、HS384 或 HS512 時才使用。

預設 不適用
外觀狀態 HMAC 演算法的必填屬性。
類型 字串
有效值

對於 encoding,有效值為 hexbase16base64base64url。編碼值 hexbase16 是同義詞。

使用 ref 屬性在流程變數中傳遞鍵。

注意:如果是流程變數,則必須包含「private」前置字串。例如:private.mysecret

<來源>

<Source>jwt-variable</Source>

如有顯示,則指定政策預期會找到要驗證的 JWT 的流程變數。

預設 request.header.authorization (如需有關預設值的重要資訊,請參閱上述注意事項)。
外觀狀態 選用
類型 字串
有效值 邊緣流程變數名稱。

<Subject>

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

政策會驗證 JWT 中的主體是否與政策設定中指定的字串相符。這項請求會識別或做出 JWT 主體的陳述式。這是 RFC7519 中提及的標準憑證附加資訊組合之一。

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

<TimeAllowance>

<TimeAllowance>120s</TimeAllowance>

時間的「寬限期」。舉例來說,如果將時間允許設為 60 秒,則在宣告的到期時間過後,系統會將過期的 JWT 視為仍然有效 (效期為 60 秒)。而系統會以類似的方式評估非早於時間。預設值為 0 秒 (無寬限期)。

預設 0 秒 (無寬限期)
外觀狀態 選用
類型 字串
有效值 包含值之流程變數的值或參照。可以按照下列方式指定時間範圍:
  • s = 秒
  • m = 分鐘
  • h = 小時
  • d = 天

流程變數

成功執行後,Verify JWTDecode 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 時新增)。如要驗證 JWT,另請參閱 JWT 政策總覽的「使用 JSON 網路金鑰組 (JWKS)」一節。詳情請參閱「(金鑰 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 來說,這個變數在簽章通過驗證時,且目前時間早於權杖到期之前,以及權杖 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> 中使用的憑證聲明是下列任一註冊名稱,部署作業就會失敗:kidisssubaudiatexpnbfjti
InvalidTypeForAdditionalClaim 如果 <AdditionalClaims> 元素子項元素 <Claim> 中使用的憑證聲明不是 stringnumberbooleanmap 類型,部署作業就會失敗。
MissingNameForAdditionalClaim 如未在 <AdditionalClaims> 元素的子元素 <Claim> 中指定憑證附加資訊,部署作業就會失敗。
InvalidNameForAdditionalHeader <AdditionalClaims> 元素的子元素 <Claim> 使用的聲明名稱是 algtyp 時,就會發生這個錯誤。
InvalidTypeForAdditionalHeader 如果 <AdditionalClaims> 元素子項元素 <Claim> 中使用的聲明類型不是 stringnumberbooleanmap,部署就會失敗。
InvalidValueOfArrayAttribute 如果 <AdditionalClaims> 元素中子元素 <Claim> 的陣列屬性值未設為 truefalse,就會發生這個錯誤。
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 演算法搭配使用,部署作業就會失敗。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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>