解碼 JWT 政策

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

結果

在不驗證 JWT 上簽名的情況下，將 JWT 解碼。這在 與 VerifyJWT 政策搭配使用，前提是必須得知 JWT 中的憑證附加資訊值 再驗證 JWT 簽名。

無論用來簽署 JWT 的演算法為何，JWT 解碼政策均適用。 如需詳細的介紹，請參閱 JWS 和 JWT 政策總覽。

影片

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

範例：解碼 JWT

下列政策會將流程變數 var.jwt 中找到的 JWT 解碼。這個 變數，而且必須包含一個可宣告 (可解碼) 的 JWT。這項政策可以從 任何流程變數都沒問題

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

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

解碼 JWT 的元素參照

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

具備的屬性 套用至頂層元素

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

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

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

視需要使用 <displayname></displayname> 元素 在管理 UI Proxy 編輯器中，以不同的自然語言為政策加上標籤 名稱。

 不適用 必填
continueOnError 如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

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

將 false 設為「關閉」政策。不會強制執行這項政策 即使服務仍附加於資料流

 true 選用
非同步 此屬性已淘汰。 false 已淘汰

&lt;DisplayName&gt;

<DisplayName>Policy Display Name</DisplayName>

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

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

&lt;Source&gt;

<Source>jwt-variable</Source>

如果有，則指定政策預期在哪個流程變數中找到 JWT 解碼器。

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

流程變數

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

部署錯誤

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

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

錯誤變數

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

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