本頁內容適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
結果
產生已簽署的 JWS，並提供可設定的聲明集。然後，JWS 可以傳回給用戶端、傳輸至後端目標，或以其他方式使用。 如需詳細簡介，請參閱 JWS 和 JWT 政策總覽。
如要瞭解 JWS 的各個部分，以及加密和簽署方式，請參閱 RFC7515。
這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。
影片
觀看短片，瞭解如何產生已簽署的 JWT。雖然這部影片專門介紹如何產生 JWT，但許多概念也適用於 JWS。
範例
產生以 HS256 簽署的 JWS
這個範例政策會產生使用 HS256 演算法簽署的 JWS。HS256 簽署和驗證簽章時，都必須使用共用密鑰。這個 JWS 使用「附加」內容，也就是以點號串連編碼的標頭、酬載和簽章，產生最終的 JWS：
[header].[payload].[signature]
使用 <Payload> 元素指定未編碼的原始 JWS 酬載。
在本例中，變數包含酬載。觸發這項政策動作時，Apigee 會編碼 JWS 標頭和酬載，然後新增編碼簽章，以數位簽署 JWS。
下列政策設定會從 my-payload 變數中包含的酬載建立 JWS，並將產生的 JWS 儲存在 output-variable 變數中。
<GenerateJWS name="JWS-Generate-HS256"> <DisplayName>JWS Generate HS256</DisplayName> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> <Payload ref="my-payload"/> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
產生以 HS256 簽署的 JWT
這個範例也會產生 JWS，並附上使用 HS256 演算法簽署的內容。在本例中，酬載為 JSON。將 typ 標頭設為 JWT
會產生已簽署的 JWS，也就是已簽署的 JWT。
(參考資料)
下列政策設定會從 json-content 變數中包含的酬載建立 JWS，並將產生的 JWS 儲存在 output-variable 變數中。只有在 json-content 變數包含 JSON 酬載，且該 JSON 酬載中的屬性適用於 JWT 時，結果才會是已簽署的 JWT。舉例來說，如果存在 exp 屬性，就必須包含數值。如果存在 aud 屬性，則必須是字串或字串陣列。依此類推。如要進一步瞭解 JWT 宣告的有效值，請參閱 IETF RFC7519。
<GenerateJWS name="JWS-Generate-HS256-JWT"> <Algorithm>HS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <Payload ref="json-content"/> <AdditionalHeaders> <Claim name="typ">JWT</Claim> </AdditionalHeaders> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
產生分離式 JWS
這項範例政策會產生具有分離內容的 JWS，並使用 RS256 演算法簽署。 產生 RS256 簽章時，需要使用 RSA 私密金鑰，且必須以 PEM 編碼形式提供。
如果 JWS 含有已卸載的內容，產生的 JWS 會省略酬載：
[header]..[signature]
使用 <Payload> 元素指定未編碼的原始 JWS 酬載。
觸發這項政策時，Apigee 會編碼 JWS 標頭和酬載，然後使用這些項目產生編碼簽章。不過，產生的 JWS 會從序列化 JWS 中省略編碼的酬載。如果簽署的內容很大、是二進位檔 (例如圖片或 PDF)，或兩者皆是，這項功能就很有用。如要允許驗證，您必須將 JWS 和簽署內容中包含的酬載這兩個元素，都傳送給驗證方。如果您使用 VerifyJWS 政策驗證 JWS，可以使用 VerifyJWS 政策的 <DetachedContent> 元素指定含有酬載的變數。
<GenerateJWS name="JWS-Generate-RS256"> <DisplayName>JWS Generate RS256</DisplayName> <Algorithm>RS256</Algorithm> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey> <Payload ref="my-payload"/> <DetachContent>true</DetachContent> <OutputVariable>output-variable</OutputVariable> </GenerateJWS>
設定主要元素
用來指定產生 JWS 金鑰的元素取決於所選演算法，如下表所示：
| 演算法 | 主要元素 | |
|---|---|---|
| HS{256/384/512}* | <SecretKey> <Value ref="private.secretkey"/> <Id>1918290</Id> </SecretKey> |
|
| RS/PS/ES{256/384/512}* | <PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="private.privatekey-id"/> </PrivateKey>
|
|
| *如要進一步瞭解金鑰規定，請參閱「簽章加密演算法簡介」。 | ||
Generate JWS 的元素參考資料
政策參考資料說明「產生 JWS」政策的元素和屬性。
注意：設定會因使用的加密演算法而略有不同。如需特定用途的設定範例，請參閱「範例」。
適用於頂層元素的屬性
<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">
所有政策父項元素都有下列屬性。
| 屬性 | 說明 | 預設 | 外觀狀態 |
|---|---|---|---|
| 名稱 |
政策的內部名稱。名稱只能使用以下字元：
A-Z0-9._\-$ %。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。
(選用) 使用 |
不適用 | 必填 |
| continueOnError |
設為 false，以便在政策失敗時傳回錯誤。這是大多數政策的預期行為。
設為 |
false | 選用 |
| 已啟用 |
設為 true 即可強制執行政策。
設為 |
是 | 選用 |
| 非同步 | 這項屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性之外，您也可以使用這個屬性，在 Apigee UI 代理項目編輯器中，以其他自然語言名稱標示政策。
| 預設 | 如果省略這個元素，系統會使用政策名稱屬性的值。 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
指定用來簽署權杖的加密演算法。
| 預設 | 不適用 |
| 外觀狀態 | 必填 |
| 類型 | 字串 |
| 有效值 | HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 |
<AdditionalHeaders/Claim>
<AdditionalHeaders> <Claim name='claim1'>explicit-value-of-claim-here</Claim> <Claim name='claim2' ref='variable-name-here'/> <Claim name='claim3' ref='variable-name-here' type='boolean'/> <Claim name='claim4' ref='variable-name' type='string' array='true'/> </AdditionalHeaders>
將額外的聲明名稱/值配對放入 JWS 的標頭。
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 有效值 | 您要用於額外聲明的任何值。您可以將聲明明確指定為字串、數字、布林值、對映或陣列。 |
<Claim> 元素會採用下列屬性：
- name - (必要) 聲明名稱，也稱為參數。
- ref - (選用) 流程變數的名稱。如果存在，政策會使用這個變數的值做為聲明。如果同時指定 ref 屬性和明確的聲明值，系統會預設使用明確值，並在參照的流程變數未解析時使用該值。
- type - (選用) 其中一種：字串 (預設)、數字、布林值或對應
- array - (選用) 設為 true，表示值是否為型別陣列。預設值： false。
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref="variable_containing_headers"/>
將重要標頭 crit 新增至 JWS。crit 標頭是標頭名稱的陣列，JWS 接收者必須知道並辨識這些名稱。舉例來說，您可以使用這個設定元素產生 JWS 標頭，解碼後如下所示：
{
"typ": "...",
"alg" : "...",
"hyb" : "some-value-here",
"crit" : [ "hyb" ],
}這個 JWS 標頭會聲明 hyb 標頭參數至關重要，且 JWS 的任何接收者都必須瞭解該參數的意義和值。
根據 IETF RFC 7515，如果 JWS 收件者不瞭解 crit 參數中參照的一或多個參數，就應拒絕 JWS，視為無效。在 Apigee 中，VerifyJWS 政策符合這項行為。
針對 crit 參數中列出的每個參數，系統會檢查 VerifyJWS 政策的 <KnownHeaders> 元素是否也列出該參數。如果 VerifyJWS 政策在 crit 中找到的任何標頭未列於 <KnownHeaders>，VerifyJWS 政策就會拒絕 JWS。
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 以半形逗號分隔的一或多個字串陣列 |
| 有效值 | 陣列或包含陣列的變數參照。 |
<DetachContent>
<DetachContent>true|false</DetachContent>
指定是否要產生具有分離式酬載的 JWS，<DetachContent>true</DetachContent> 或不產生，<DetachContent>false</DetachContent>。
如果您指定 false (預設值)，產生的 JWS 格式如下：
[header].[payload].[signature]
如果您指定 true，建立的 JWS 會省略酬載，並採用以下格式：
[header]..[signature]
使用 JWS 搭配分離式酬載時，您必須將原始未編碼的酬載和序列化 JWS 一併傳送給驗證方。
| 預設 | false |
| 外觀狀態 | 選用 |
| 類型 | 布林值 |
| 有效值 | true 或 false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
如果希望政策在無法解析政策中指定的任何參照變數時擲回錯誤，請設為 false。設為 true 可將任何無法解析的變數視為空字串 (空值)。
| 預設 | false |
| 外觀狀態 | 選用 |
| 類型 | 布林值 |
| 有效值 | true 或 false |
<OutputVariable>
<OutputVariable>output-variable</OutputVariable>
指定政策將透過產生的 JWS 設定的內容變數名稱。
根據預設，這項政策會將 JWS 放入名為 jws.POLICYNAME.generated_jws 的內容變數中。
| 預設 | jws.POLICYNAME.generated_jws |
| 外觀狀態 | 選用 |
| 類型 | 字串 (流程變數名稱) |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
指定未編碼的原始 JWS 酬載。指定含有酬載的變數或字串。
| 預設 | 不適用 |
| 外觀狀態 | 必填 |
| 類型 | 未編碼 JWS 酬載的字串、位元組陣列、串流或任何其他表示法。 |
| 有效值 | 訊息範本，或包含酬載的變數參照。 |
<PrivateKey> 元素
這是選用屬性，只有在 <Algorithm> 是 RS*、PS* 或 ES* 選項時才使用。這個物件會指定用於簽署的私密金鑰，以及與私密金鑰相關的其他資訊。如果演算法為非對稱演算法，則會使用這項屬性。
<PrivateKey> <Value ref="private.privatekey"</Value> </PrivateKey>
| 預設值： | 不適用 |
| 外觀狀態： | (選用步驟) 不過，您必須只包含一個 <PrivateKey> 或 <SecretKey> 元素。如果演算法為 RS*、PS* 或 ES*，請使用 <PrivateKey> 元素；如果演算法為 HS*，請使用 <SecretKey> 元素。 |
| 類型： | 不適用 |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
指定要納入 JWS 標頭的金鑰 ID (kid)。
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
| 有效值 | 流程變數或字串 |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
視需要指定政策應使用的密碼，以解密私密金鑰。使用 ref 屬性在流程變數中傳遞金鑰。
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
| 有效值 |
流程變數參照。注意：您必須使用 ref 屬性指定流程變數。如果政策設定以純文字指定密碼，Apigee 會將其視為無效並拒絕。流程變數必須以「private」為前置字元。例如： |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
指定用於簽署 JWS 的 PEM 編碼私密金鑰。使用 ref 屬性在流程變數中傳遞鍵。
| 預設 | 不適用 |
| 外觀狀態 | 使用政策透過 RS*、PS* 或 ES* 演算法產生 JWS 時，必須提供這項資訊。 |
| 類型 | 字串 |
| 有效值 |
含有字串的流程變數，代表 PEM 編碼的私密金鑰值。
注意：流程變數必須加上「private」前置字元。例如：
|
<SecretKey>
<SecretKey encoding="base16|hex|base64|base64url" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.variable-here"/> </SecretKey>
指定產生使用對稱 (HS*) 演算法 (HS256、HS384 或 HS512) 的 JWS 時要使用的密鑰。
此元素為選用項目。不過，您必須只包含一個 <PrivateKey> 或 <SecretKey> 元素。產生以非對稱演算法 (RS*、PS* 或 ES* 其中之一) 簽署的 JWS 時，請使用 <PrivateKey> 元素；產生以對稱演算法 (例如 HS*) 簽署的 JWS 時，請使用 <SecretKey> 元素。
「<SecretKey>」的子女
下表說明 <SecretKey> 的子元素和屬性：
| 子項 | 存在必要性 | 說明 |
|---|---|---|
| 編碼 (屬性) | 選用 | 指定如何編碼參照變數中的金鑰。根據預設，如果沒有 <SecretKey encoding="hex" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 在上述範例中，由於編碼為 |
| ID (元素) | 選用 | 金鑰 ID。值可以是任何字串。您可以將值指定為常值文字值，也可以透過變數參照間接指定，並使用 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.variable-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> <Value ref="private.variable-here"/> </SecretKey> 這項政策會將這個金鑰 ID 做為產生的 JWS 標頭中的 |
| 值 (元素) | 必填 | 編碼後的密鑰。指定用於簽署酬載的密鑰。
使用 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> Apigee 會針對 HS256/HS384/HS512 演算法強制執行最低金鑰強度。HS256 的金鑰長度下限為 32 個位元組，HS384 為 48 個位元組，HS512 則為 64 個位元組。使用強度較低的金鑰會導致執行階段錯誤。 |
<Type>
<Type>type-string-here</Type>
選用元素，唯一允許的值為 Signed，指定政策會產生已簽署的 JWS。<Type> 僅用於比對 GenerateJWT 和 VerifyJWT 政策的對應元素 (其中可採用 Signed 或 Encrypted 值)。
| 預設 | 不適用 |
| 外觀狀態 | 選用 |
| 類型 | 字串 |
| 有效值 | Signed |
流程變數
產生 JWS 政策不會設定流程變數。
錯誤參考資料
本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「政策錯誤的相關資訊」和「處理錯誤」。
執行階段錯誤
政策執行時可能會發生這些錯誤。
| 錯誤代碼 | HTTP 狀態 | 發生時機 |
|---|---|---|
steps.jws.GenerationFailed |
401 |
政策無法產生 JWS。 |
steps.jws.InsufficientKeyLength |
401 |
針對 HS256 演算法，金鑰長度必須小於 32 位元組 |
steps.jws.InvalidClaim |
401 |
缺少聲明或聲明不相符，或是缺少標頭或標頭不相符。 |
steps.jws.InvalidCurve |
401 |
金鑰指定的曲線不適用於橢圓曲線演算法。 |
steps.jws.InvalidJsonFormat |
401 |
JWS 標頭中發現無效的 JSON。 |
steps.jws.InvalidPayload |
401 |
JWS 酬載無效。 |
steps.jws.InvalidSignature |
401 |
<DetachedContent> 已省略，且 JWS 具有分離的內容酬載。 |
steps.jws.KeyIdMissing |
401 |
驗證政策使用 JWKS 做為公開金鑰來源，但已簽署的 JWS 不會在標頭中加入 kid 屬性。 |
steps.jws.KeyParsingFailed |
401 |
無法從指定的金鑰資訊剖析公開金鑰。 |
steps.jws.MissingPayload |
401 |
缺少 JWS 酬載。 |
steps.jws.NoAlgorithmFoundInHeader |
401 |
發生於 JWS 省略演算法標頭時。 |
steps.jws.SigningFailed |
401 |
在 GenerateJWS 中，金鑰大小小於 HS384 或 HS512 演算法的最小大小 |
steps.jws.UnknownException |
401 |
發生不明例外狀況。 |
steps.jws.WrongKeyType |
401 |
指定的金鑰類型有誤。例如，如果您為橢圓曲線演算法指定 RSA 金鑰，或為 RSA 演算法指定曲線金鑰。 |
部署錯誤
部署含有這項政策的 Proxy 時，可能會發生這些錯誤。
| 錯誤名稱 | 發生時機 |
|---|---|
InvalidAlgorithm |
唯一有效的值為 RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512,
HS256, HS384, HS512。 |
|
|
其他可能的部署錯誤。 |
錯誤變數
系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。
| 變數 | 地點 | 範例 |
|---|---|---|
fault.name="fault_name" |
fault_name 是錯誤的名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤程式碼的最後部分。 | fault.name Matches "TokenExpired" |
JWS.failed |
如果作業失敗，所有 JWS 政策都會設定相同的變數。 | jws.JWS-Policy.failed = true |
錯誤回應範例
針對錯誤處理，最佳做法是將錯誤的 errorcode 部分加以包裝
回應。請勿參考 faultstring 中的文字，因為可能會變動。
錯誤規則範例
<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>