解碼 JWT 政策

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

優勢

解碼 JWT,而不驗證 JWT 上的簽名。與 Verify JWT 政策搭配使用時,尤其在驗證 JWT 的簽名之前,必須先得知 JWT 中的憑證附加資訊,這一點非常有用。

無論使用何種演算法簽署 JWT,JWT 解碼政策皆可運作。詳情請參閱 JWS 和 JWT 政策總覽

影片

請觀看短片,瞭解如何解碼 JWT。

範例:解碼 JWT

下列政策會將在流程變數 var.jwt 中找到的 JWT 解碼。這個變數必須存在,且包含可以 (可解碼) 的 JWT。政策可從任何流程變數取得 JWT。

<DecodeJWT name="JWT-Decode-HS256">
    <DisplayName>JWT Verify HS256</DisplayName>
    <Source>var.jwt</Source>
</DecodeJWT>

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

解碼 JWT 的元素參考資料

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

套用至頂層元素的屬性

<DecodeJWT 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 編輯器中為政策加上標籤。

預設 如果省略這個元素,則會使用政策名稱屬性的值。
外觀狀態 選用
類型 字串

<來源>

<Source>jwt-variable</Source>

如有顯示,則指定政策預期會尋找要解碼的 JWT 的流程變數。

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

流程變數

成功執行後,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.FailedToDecode 401 當政策無法解碼 JWT 時發生。JWT 可能格式錯誤、無效或無法解密。
steps.jwt.FailedToResolveVariable 401 發生於政策 <Source> 元素中指定的資料流變數不存在時產生的。
steps.jwt.InvalidToken 401 當政策的 <Source> 元素中指定的流程變數超出範圍,或是無法解析時,就會發生這個錯誤。

部署錯誤

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

錯誤名稱 原因 修正
InvalidEmptyElement 系統會在政策的 <Source> 元素中未指定包含要解碼的 JWT 的流程變數。

錯誤變數

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

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>