解碼 JWT 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

解碼 JWT，但不驗證 JWT 的簽章。與 VerifyJWT 政策搭配使用時，這項功能最實用，因為在驗證 JWT 的簽名之前，必須先知道 JWT 內附加資訊的值。

無論簽署 JWT 時使用的演算法為何，JWT 解碼政策都能正常運作。 如需詳細簡介，請參閱 JWS 和 JWT 政策總覽。

這項政策屬於標準政策，可部署至任何環境類型。如要瞭解各環境類型適用的政策類型和可用性，請參閱「政策類型」。

影片

注意：以下影片顯示 Apigee 使用者介面中的傳統 Proxy 編輯器。Apigee 即將推出新版 Proxy 編輯器，設計與影片中顯示的傳統版不同。

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

範例：解碼 JWT

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

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

這項政策會將輸出內容寫入環境變數，以便 API 代理程式中的後續政策或條件檢查這些值。如需這項政策設定的變數清單，請參閱「流程變數」。

「解碼 JWT」的元素參考資料

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

適用於頂層元素的屬性

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

所有政策父項元素都有下列屬性。

屬性	說明	預設	外觀狀態
名稱	政策的內部名稱。名稱只能使用以下字元： A-Z0-9._\-$ %。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。 (選用) 使用 <displayname></displayname> 元素，在 Apigee UI 代理程式編輯器中，以其他自然語言名稱標示政策。	不適用	必填
continueOnError	設為 false，以便在政策失敗時傳回錯誤。這是大多數政策的預期行為。 設為 true，即使政策失敗，流程執行作業仍會繼續。	false	選用
已啟用	設為 true 即可強制執行政策。 設為 false 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。	是	選用
非同步	這項屬性已淘汰。	false	已淘汰

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

如有，則指定政策預期會找到要解碼的 JWT 的流程變數。

注意：系統預設會從 request.header.authorization 變數擷取 JWT。在本例中，Apigee 會在要求授權標頭中尋找 JWT。如果您在 Authorization 標頭中傳遞 JWT，則不需要在政策中加入 Source 元素；不過，您必須在 auth 標頭中加入 Bearer。舉例來說，您會像這樣在 Authorization 標頭中傳遞 JWT：

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

您可以設定政策，從表單、查詢參數變數或其他任何變數中擷取 JWT。如果變數不存在，或政策無法找到 JWT，政策就會傳回錯誤。

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

Flow variables

Upon success, the Verify JWT and Decode JWT policies set context variables according to this pattern:

jwt.{policy_name}.{variable_name}

For example, if the policy name is jwt-parse-token , then the policy will store the subject specified in the JWT to the context variable named jwt.jwt-parse-token.decoded.claim.sub. (For backward compatibility, it will also be available in jwt.jwt-parse-token.claim.subject)

Variable name	Description
claim.audience	The JWT audience claim. This value may be a string, or an array of strings.
claim.expiry	The expiration date/time, expressed in milliseconds since epoch.
claim.issuedat	The Date the token was issued, expressed in milliseconds since epoch.
claim.issuer	The JWT issuer claim.
claim.notbefore	If the JWT includes a nbf claim, this variable will contain the value, expressed in milliseconds since epoch.
claim.subject	The JWT subject claim.
claim.name	The value of the named claim (standard or additional) in the payload. One of these will be set for every claim in the payload.
decoded.claim.name	The JSON-parsable value of the named claim (standard or additional) in the payload. One variable is set for every claim in the payload. For example, you can use decoded.claim.iat to retrieve the issued-at time of the JWT, expressed in seconds since epoch. While you can also use the claim.name flow variables, this is the recommended variable to use to access a claim.
decoded.header.name	The JSON-parsable value of a header in the payload. One variable is set for every header in the payload. While you can also use the header.name flow variables, this is the recommended variable to use to access a header.
expiry_formatted	The expiration date/time, formatted as a human-readable string. Example: 2017-09-28T21:30:45.000+0000
header.algorithm	The signing algorithm used on the JWT. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more.
header.kid	The Key ID, if added when the JWT was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT policies overview to verify a JWT. See (Key ID) Header Parameter for more.
header.type	Will be set to JWT.
header.name	The value of the named header (standard or additional). One of these will be set for every additional header in the header portion of the JWT.
header-json	The header in JSON format.
is_expired	true or false
payload-claim-names	An array of claims supported by the JWT.
payload-json	The payload in JSON format.
seconds_remaining	The number of seconds before the token will expire. If the token is expired, this number will be negative.
time_remaining_formatted	The time remaining before the token will expire, formatted as a human-readable string. Example: 00:59:59.926
valid	In the case of VerifyJWT, this variable will be true when the signature is verified, and the current time is before the token expiry, and after the token notBefore value, if they are present. Otherwise false. In the case of DecodeJWT, this variable is not set.

錯誤參考資料

本節說明這項政策觸發錯誤時，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

錯誤回應範例

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