您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
產生已簽署的 JWS,並透過一組可設定的憑證附加資訊。接著,您可以將 JWS 傳回給用戶端、傳輸到後端目標,或以其他方式使用。詳情請參閱 JWS 和 JWT 政策總覽。
如要瞭解 JWS 的幾個部分,以及其加密與簽署的方式,請參閱 RFC7515。
影片
請觀看短片,瞭解如何產生已簽署的 JWT。雖然這部影片主要用於產生 JWT,但許多概念都與 JWS 相同。
範例
產生以 HS256 演算法簽署的 JWS 附加 JWS
這個範例政策會產生附加的 JWS,並使用 HS256 演算法簽署。HS256 需要利用共用密鑰來簽署及驗證簽名。
隨附的 JWS 包含經過編碼的標頭、酬載和簽名:
header.payload.signature
將 <DetachContent>
設為 true,即可產生卸離的內容。如要進一步瞭解 JWS 的結構和格式,請參閱 JWS/JWT 的組成部分。
使用 <Payload>
元素指定未編碼的原始 JWS 酬載。在此範例中,變數包含酬載。觸發這項政策動作時,Edge 會將 JWS 標頭和酬載編碼,然後新增編碼的簽名來對 JWS 進行數位簽署。
下列政策設定會從 private.payload
變數中的酬載建立 JWS。
<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="private.payload" /> <OutputVariable>jws-variable</OutputVariable> </GenerateJWS>
產生使用 RS256 演算法簽署的卸離 JWS
這個範例政策會產生卸離的 JWS,並使用 RS256 演算法簽署。產生 RS256 簽名時,需要使用 RSA 私密金鑰,須以 PEM 編碼格式提供。
卸離的 JWS 會從 JWS 省略酬載:
header..signature
使用 <Payload>
元素指定未編碼的原始 JWS 酬載。觸發這項政策時,Edge 會將 JWS 標頭和酬載編碼,然後使用這些標頭和酬載產生編碼後的簽章。不過,產生的 JWS 會省略酬載。您必須使用 VerifyJWS 政策的 <DetachedContent>
元素,將酬載傳送至 VerifyJWS 政策。
<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="private.payload" /> <DetachContent>true</DetachContent> <OutputVariable>jws-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>
|
|
*如要進一步瞭解金鑰相關規定,請參閱「關於簽名加密演算法」一文。 |
產生 JWS 的元素參照
政策參考資料說明瞭「產生 JWS」政策的元素和屬性。
注意:視您使用的加密演算法而定,設定可能略有不同。如需特定用途的設定範例,請參閱範例。
套用至頂層元素的屬性
<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">
以下是所有政策父項元素的通用屬性。
屬性 | 說明 | 預設 | 外觀狀態 |
---|---|---|---|
名稱 |
政策的內部名稱。名稱中使用的字元僅限 A-Z0-9._\-$ % 。不過,Edge 管理 UI 會強制執行其他限制,例如自動移除非英數字元。您也可以選擇使用 |
不適用 | 必要 |
continueOnError |
如果設為 false ,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。
設為 |
false | 選用 |
已啟用 |
如要強制執行政策,請設為 true 。
設為 |
true | 選用 |
async | 此屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性,您還可以使用其他自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
預設 | 如果省略這個元素,則會使用政策名稱屬性的值。 |
外觀狀態 | 選用 |
類型 | 字串 |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
指定要簽署權杖的加密演算法。
預設 | 不適用 |
外觀狀態 | 必要 |
類型 | 字串 |
有效值 | HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 |
<其他標頭/聲明>
<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 - (選用) 其中之一:字串 (預設值)、數字、布林值或地圖
- 陣列 - (選用) 設為 true,表示該值是類型陣列。預設值:false。
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref=’variable_containing_headers’/>
在 JWS 中加入重要標頭 crit。crit 標頭是一組標頭名稱的陣列,必須由 JWS 接收端識別並辨識。例如:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
在執行階段,VerifyJWS 政策會檢查「條件」標頭。
針對 crit 標頭中列出的每個標頭,系統會檢查 VerifyJWS 政策的 <KnownHeaders>
元素是否也會列出該標頭。如果 VerifyJWS 政策在 crit 中找到且未列於 <KnownHeaders>
中,會導致 VerifyJWS 政策失敗。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 以半形逗號分隔的字串陣列 |
有效值 | 包含陣列的陣列或變數名稱。 |
<DetachContent>
<DetachContent>true|false</DetachContent>
指定是否要使用已卸離酬載 (<DetachContent>true</DetachContent>
或並非 <DetachContent>false</DetachContent>
) 產生 JWS。
如果您指定 false,系統預設會以下列格式產生 JWS:
header.payload.signature
如果您指定 true 來建立卸離的酬載,則產生的 JWS 會省略酬載,並採用下列格式:
header..signature
卸離酬載後,您必須使用 VerifyJWS 政策的 <DetachedContent>
元素,將原始未編碼的酬載傳送至 VerifyJWS 政策。
預設 | false |
外觀狀態 | 選用 |
類型 | 布林值 |
有效值 | true 或 false |
<IgnoreUnresolvedVariables>
<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>
如要讓政策在政策中指定的任何參照變數無法解析時擲回錯誤,請設為 false。設為 true 會將任何無法解析的變數視為空字串 (空值)。
預設 | false |
外觀狀態 | 選用 |
類型 | 布林值 |
有效值 | true 或 false |
<OutputVariable>
<OutputVariable>JWS-variable</OutputVariable>
指定這項政策產生的 JWS 應放置的位置。根據預設,系統會將此資料置於資料流變數 jws.POLICYNAME.generated_jws
中。
預設 | jws.POLICYNAME.generated_jws |
外觀狀態 | 選用 |
類型 | 字串 (流程變數名稱) |
<Payload>
<Payload ref="flow-variable-name-here" /> or <Payload>payload-value</Payload>
指定未編碼的原始 JWS 酬載。指定內含酬載或字串的變數。
預設 | 不適用 |
外觀狀態 | 必要 |
類型 | 未編碼 JWS 酬載的字串、位元組陣列、串流或任何其他表示法。 |
<PrivateKey/Id>
<PrivateKey> <Id ref="flow-variable-name-here"/> </PrivateKey> or <PrivateKey> <Id>your-id-value-here</Id> </PrivateKey>
指定要包含在 JWS 標頭中的金鑰 ID (kid)。僅適用於 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 的演算法。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 | 流程變數或字串 |
<PrivateKey/Password>
<PrivateKey> <Password ref="private.privatekey-password"/> </PrivateKey>
視需要指定政策應用來解密私密金鑰的密碼。使用 ref 屬性在流程變數中傳遞鍵。僅適用於 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 的演算法。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 |
流程變數參考資料。 注意:您必須指定流程變數。因為政策設定無效,Edge 將拒絕為無效的政策設定,而該政策設定是以明文形式指定。流程變數的前置字串須為「private」。例如, |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
指定用來簽署 JWS 的 PEM 編碼私密金鑰。使用 ref 屬性在流程變數中傳遞鍵。僅適用於演算法為 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 的演算法。
預設 | 不適用 |
外觀狀態 | 必須使用 RS256 演算法產生 JWS。 |
類型 | 字串 |
有效值 |
流程變數,其中包含代表 PEM 編碼 RSA 私密金鑰值的字串。 注意:流程變數的前置字串須為「private」。例如: |
<密鑰/ID>
<SecretKey> <Id ref="flow-variable-name-here"/> </SecretKey> or <SecretKey> <Id>your-id-value-here</Id> </SecretKey>
指定要加入使用 HMAC 演算法簽署的 JWS JWS 標頭中的金鑰 ID (kid)。只有在演算法為 HS256/HS384/HS512 時才使用。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 | 流程變數或字串 |
<SecretKey/Value>
<SecretKey> <Value ref="private.your-variable-name"/> </SecretKey>
提供透過 HMAC 演算法驗證或簽署權杖的密鑰。只有在演算法為 HS256/HS384/HS512 時才使用。使用 ref 屬性在流程變數中傳遞鍵。
邊緣會強制執行 HS256/HS384/HS512 演算法的最低按鍵強度。HS256 的索引鍵長度下限為 32 個位元組,HS384 的索引鍵長度下限為 48 個位元組,HS512 版則是 64 個位元組。使用強度較低的金鑰會導致執行階段錯誤。
預設 | 不適用 |
外觀狀態 | HMAC 演算法的必填屬性。 |
類型 | 字串 |
有效值 |
參照字串的流程變數 注意:如果是流程變數,則必須包含「private」前置字串。例如: |
流程變數
產生 JWS 政策未設定流程變數。
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 請務必瞭解您是否正在開發錯誤規則來處理錯誤。詳情請參閱政策錯誤須知和處理錯誤。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 發生時機 |
---|---|---|
steps.jws.GenerationFailed |
401 | 政策無法產生 JWS。 |
steps.jws.InsufficientKeyLength |
401 | 適用於小於 32 個位元組的 HS256 演算法 |
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。 |
|
其他可能的部署錯誤。 |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
Variables | 地點 | 範例 |
---|---|---|
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>