本頁面由 Cloud Translation API 翻譯而成。

解碼 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	已淘汰

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

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

<Source>

<Source>jwt-variable</Source>

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

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

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.

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
`steps.jwt.FailedToDecode`	401	Occurs when the policy is unable to decode the JWT. The JWT may be malformed, invalid or otherwise not decodable.
`steps.jwt.FailedToResolveVariable`	401	Occurs when the flow variable specified in the `<Source>` element of the policy does not exist.
`steps.jwt.InvalidToken`	401	Occurs when the flow variable specified in the `<Source>` element of the policy is out of scope or can't be resolved.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause	Fix
`InvalidEmptyElement`	Occurs when the flow variable containing the JWT to be decoded is not specified in the `<Source>` element of the policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "TokenExpired"`
`JWT.failed`	All JWT policies set the same variable in the case of a failure.	`JWT.failed = true`

Example error response

JWT Policy Fault Codes

For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

Example fault rule

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