本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
結果
解碼 JWS 標頭，但不驗證 JWS 的簽章，並將每個標頭寫入流程變數。與 VerifyJWS 政策搭配使用時，這項政策最為實用，因為在驗證 JWS 的簽名之前，必須先知道 JWS 內標頭的值。
JWS 可以有附加酬載，格式如下：
header.payload.signature
或者，JWS 可以省略酬載 (稱為「分離式」酬載)，格式如下：
header..signature
DecodeJWS 政策適用於這兩種形式，因為它只會解碼 JWS 的標頭部分。 無論用來簽署 JWS 的演算法為何，DecodeJWS 政策都能正常運作。
如需詳細介紹和 JWS 格式總覽，請參閱 JWS 和 JWT 政策總覽。
這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。
影片
請觀看短片，瞭解如何解碼 JWT。雖然這部影片專門介紹 JWT，但許多概念也適用於 JWS。
範例：解碼 JWS
下方的政策會解碼流程變數 var.JWS 中的 JWS。這個變數必須存在，且包含可行的 (可解碼) JWS。政策可以從任何流程變數取得 JWS。
<DecodeJWS name="JWS-Decode-HS256"> <DisplayName>JWS Verify HS256</DisplayName> <Source>var.JWS</Source> </DecodeJWS>
對於 JWS 標題部分的每個標題，政策會設定名為下列項目的流程變數：
jws.policy-name.header.header-name
如果 JWS 附加了酬載，則會將 jws.policy-name.header.payload 流程變數設為酬載。如果是已卸離的酬載，payload 為空白。
如需這項政策設定的變數完整清單，請參閱「流程變數」。
Decode JWS 的元素參考資料
政策參考資料說明瞭「解碼 JWS」政策的元素和屬性。
適用於頂層元素的屬性
<DecodeJWS name="JWS" continueOnError="false" enabled="true" async="false">
所有政策父項元素都有下列屬性。
| 屬性 | 說明 | 預設 | 外觀狀態 |
|---|---|---|---|
| 名稱 |
政策的內部名稱。名稱只能使用以下字元：
A-Z0-9._\-$ %。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。
視需要使用 |
不適用 | 必填 |
| continueOnError |
設為 false，以便在政策失敗時傳回錯誤。這是大多數政策的預期行為。
設為 |
false | 選用 |
| 已啟用 |
設為 true 即可強制執行政策。
設為 |
是 | 選用 |
| 非同步 | 這項屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性外，您還可以使用這個屬性，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。
| 預設 | 如果省略這個元素，系統會使用政策名稱屬性的值。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
<Source>
<Source>JWS-variable</Source>
如果存在，則指定政策預期會找到要解碼的 JWS 的流程變數。
| 預設 | request.header.authorization (請參閱上方的附註，瞭解預設值的重要資訊)。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
| 有效值 | Apigee 流程變數名稱 |
Flow variables
Upon success, the Verify JWS and Decode JWS policies set context variables according to this pattern:
jws.{policy_name}.{variable_name}
For example, if the policy name is verify-jws, then the policy will store
the algorithm specified in the JWS to this context variable:
jws.verify-jws.header.algorithm
| Variable name | Description |
|---|---|
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. |
header.algorithm |
The signing algorithm used on the JWS. For example, RS256, HS384, and so on. See (Algorithm) Header Parameter for more. |
header.kid |
The Key ID, if added when the JWS was generated. See also "Using a JSON Web Key Set (JWKS)" at JWT and JWS policies overview to verify a JWS. See (Key ID) Header Parameter for more. |
header.type |
The header type value. See (Type) Header Parameter for more. |
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 JWS. |
header-json |
The header in JSON format. |
payload |
The JWS payload if the JWS has an attached payload. For a detached paylod, this variable is empty. |
valid |
In the case of VerifyJWS, 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 DecodeJWS, this variable is not set. |
錯誤參考資料
This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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 | Occurs when |
|---|---|---|
steps.jws.FailedToDecode |
401 |
The policy was unable to decode the JWS. The JWS is possibly corrupted. |
steps.jws.FailedToResolveVariable |
401 |
Occurs when the flow variable specified in the <Source> element of
the policy does not exist. |
steps.jws.InvalidClaim |
401 |
For a missing claim or claim mismatch, or a missing header or header mismatch. |
steps.jws.InvalidJsonFormat |
401 |
Invalid JSON found in the JWS header. |
steps.jws.InvalidJws |
401 |
This error occurs when the JWS signature verification fails. |
steps.jws.InvalidPayload |
401 |
The JWS payload is invalid. |
steps.jws.InvalidSignature |
401 |
<DetachedContent> is omitted and the JWS has a detached content payload. |
steps.jws.MissingPayload |
401 |
The JWS payload is missing. |
steps.jws.NoAlgorithmFoundInHeader |
401 |
Occurs when the JWS omits the algorithm header. |
steps.jws.UnknownException |
401 |
An unknown exception occurred. |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
| Error name | Occurs when |
|---|---|
InvalidAlgorithm |
The only valid values are: RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512. |
|
|
Other possible deployment errors. |
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" |
JWS.failed |
All JWS policies set the same variable in the case of a failure. | jws.JWS-Policy.failed = true |
Example error response
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="JWS Policy Errors">
<Step>
<Name>JavaScript-1</Name>
<Condition>(fault.name Matches "TokenExpired")</Condition>
</Step>
<Condition>JWS.failed=true</Condition>
</FaultRule>
</FaultRules>