GenerateJWS 政策

您正在查看 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>

<Password><Id> 為選用元素。

*如要進一步瞭解金鑰相關規定,請參閱「關於簽名加密演算法」一文。

產生 JWS 的元素參照

政策參考資料說明瞭「產生 JWS」政策的元素和屬性。

注意:視您使用的加密演算法而定,設定可能略有不同。如需特定用途的設定範例,請參閱範例

套用至頂層元素的屬性

<GenerateJWS name="JWS" continueOnError="false" enabled="true" async="false">

以下是所有政策父項元素的通用屬性。

屬性 說明 預設 外觀狀態
名稱 政策的內部名稱。名稱中使用的字元僅限 A-Z0-9._\-$ %。不過,Edge 管理 UI 會強制執行其他限制,例如自動移除非英數字元。

您也可以選擇使用 <displayname></displayname> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 必要
continueOnError 如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
已啟用 如要強制執行政策,請設為 true

設為 false 即可「停用」政策。即使政策仍附加在流程中,系統也不會強制執行政策。

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 中加入重要標頭 critcrit 標頭是一組標頭名稱的陣列,必須由 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」。例如,private.mypassword

<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」。例如:private.mykey

<密鑰/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」前置字串。例如:private.mysecret

流程變數

產生 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。

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

其他可能的部署錯誤。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

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>