解碼 JWT 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

解碼 JWT 時，不驗證 JWT 上的簽章。當您必須先知道 JWT 中的憑證值，才能驗證 JWT 簽名時，此做法最實用，因為這時可與 VerifyJWT 政策搭配使用。

無論用來簽署 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 中的後續政策或條件檢查這些值。如需這項政策設定的變數清單，請參閱「流程變數」。

Decode JWT 的元素參考資料

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

套用至頂層元素的屬性

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

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

屬性 說明 預設 在家狀態
名稱 政策的內部名稱。您可以在名稱中使用的字元僅限： A-Z0-9._\-$ %。不過，Apigee UI 會強制執行其他限制，例如自動移除非英數字元的字元。

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

 不適用 必填
continueOnError 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續。

 false 選用
已啟用 設為 true 即可強制執行政策。

將其設為 false 可「關閉」政策。即使政策仍附加至流程，也不會強制執行。

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了使用名稱屬性，您也可以在 Apigee UI 代理程式編輯器中使用其他自然語言名稱標示政策。

預設 如果省略這個元素，系統會使用政策的 name 屬性值。
在家狀態 選用
類型 字串

<Source>

<Source>jwt-variable</Source>

如果存在，則會指定政策預期在哪個流程中找到 JWT 進行解碼。

預設 request.header.authorization (如需預設值的相關重要資訊，請參閱上述附註)。
在家狀態 選用
類型 字串
有效值 Apigee 流程變數名稱

流程變數

成功後，「驗證 JWT」和「解碼 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 到期日期/時間，自紀元時間起算的毫秒數。
claim.issuedat 權杖核發日期，以自 Epoch 起算的毫秒為單位。
claim.issuer JWT 核發者憑證附加資訊。
claim.notbefore 如果 JWT 包含 nbf 憑證附加資訊，這個變數就會包含該值，以自紀元起算的毫秒為單位。
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 Web Key Set (JWKS)」。詳情請參閱「(Key ID) 標頭參數」。
header.type 會設為 JWT。
header.name 命名標頭的值 (標準或額外)。在 JWT 的標頭部分，每個額外標頭都會設定其中一個。
header-json 以 JSON 格式提供的標頭。
is_expired 是或否
payload-claim-names JWT 支援的陳述式陣列。
payload-json
JSON 格式的酬載。
seconds_remaining 權杖失效前的秒數。如果符記已到期，這個數字會為負數。
time_remaining_formatted 代碼到期前剩餘的時間，格式為人類可讀的字串。範例：00:59:59.926
valid 在 VerifyJWT 的情況下，如果簽名已驗證，且目前時間在權杖到期時間之前，且在權杖 notBefore 值之後 (如果有)，這個變數就會設為 true。否則為 false。

在 DecodeJWT 的情況下，這個變數不會設定。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理錯誤規則，就必須瞭解這項資訊。如需更多資訊，請參閱「政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

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

錯誤代碼 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 "InvalidToken"
JWT.failed 所有 JWT 政策在失敗的情況下都會設定相同的變數。 JWT.failed = true

錯誤回應範例

JWT 政策錯誤代碼

針對錯誤處理，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

錯誤規則範例

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>