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

GenerateJWS 政策

查看 Apigee Edge 說明文件。
前往 Apigee X說明文件。資訊

結果

產生已簽署的 JWS，其中包含一組可設定的聲明。隨後 JWS 便能傳送至後端目標，或以其他方式使用。如需詳細的介紹，請參閱 JWS 和 JWT 政策總覽。

如要進一步瞭解 JWS 的組成部分，以及這些元件的加密與簽署方式，請參閱 RFC7515。

影片

請觀看短片，瞭解如何產生已簽署的 JWT。這部影片許多概念都與 JWS 相同。

範例

產生一個附加的 JWS， HS256 演算法
產生卸離的 JWS，並簽署 RS256 演算法

產生以 HS256 簽署的 JWS 演算法

這個範例政策會產生附加的 JWS，並使用 HS256 演算法進行簽署。HS256 仰賴一起進行簽署及驗證簽名的共用密鑰。

附加的 JWS 包含經過編碼的標頭、酬載和簽章：

header.payload.signature

將 <DetachContent> 設為 true，即可產生卸離的內容。如要進一步瞭解，請參閱 JWS/JWT 的組成部分。建立了 JWS 的結構和格式

使用 <Payload> 元素指定未經編碼的原始 JWS 酬載。本例中的變數包含酬載。觸發這項政策動作時 Edge 會對 JWS 標頭和酬載進行編碼，然後將編碼簽章加入 JWS 數位簽署。

下列政策設定會從變數中的酬載建立 JWS。 private.payload。

<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 演算法

注意： 請使用相同的範例為 PS256 或 ES256 演算法。只需變更 <Algorithm>RS256</Algorithm> 的值即可至 PS256 或 ES256。對於 ES256，您也需要指定索引鍵並與演算法相容如要進一步瞭解重要規定，請參閱關於簽名加密演算法。

這個範例政策會產生卸離的 JWS，並使用 RS256 演算法簽署。產生 RS256 簽名需要使用 RSA 私密金鑰，而且必須以 PEM 編碼格式提供。

卸離的 JWS 會省略 JWS 中的酬載：

header..signature

使用 <Payload> 元素指定未經編碼的原始 JWS 酬載。觸發這項政策時，Edge 會編碼 JWS 標頭和酬載，然後用這些摘要產生編碼的簽章然而，產生的 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="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>` 是選用元素。
^*如要進一步瞭解重要規定，請參閱關於簽名加密演算法。

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._\-$ %`。不過，邊緣管理 UI 會強制執行額外的限制 (例如自動移除非英數字元的字元)。視需要使用 `<displayname></displayname>` 元素在管理 UI Proxy 編輯器中，以不同的自然語言為政策加上標籤名稱。	不適用	必填
continueOnError	如果設為「`false`」，系統會在政策失敗時傳回錯誤。這是可預期的情況大多數政策的行為如果設為 `true`，即使政策已發生，流程執行作業仍會繼續執行失敗。	false	選用
已啟用	如要強制執行政策，請設為 `true`。將 `false` 設為「關閉」政策。不會強制執行這項政策即使服務仍附加於資料流	true	選用
非同步	此屬性已淘汰。	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>

<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> 元素支援呼叫的動態字串替換功能訊息範本 (type=map 時)。

預設	不適用
外觀狀態	選用
有效值	你想要用於其他版權聲明的任何值。您可以宣告為字串、數字、布林值、地圖或陣列。

<Claim> 元素會採用下列屬性：

name - (必填) 著作權聲明的名稱。
注意：請勿在這個元素中使用任何已註冊的著作權聲明名稱。已註冊的聲明會在 RFC7519 中指定。包括：「iss」、「sub」、「aud」、「iat」、「exp」、「nbf」和「jti」。
ref - (選填) 流程變數名稱。如有的話，政策會使用變數為宣告。如果同時指定了 ref 屬性和明確的聲明值，此為預設值，如果所參照的流程變數未解析，就會使用這個值。
type - (選用) 下列其中一個：字串 (預設)、數字、布林值或地圖
陣列 - (選用) 設為 true，表示值是否為類型的陣列。預設： false。

<CriticalHeaders>

<CriticalHeaders>a,b,c</CriticalHeaders>

or:

<CriticalHeaders ref=’variable_containing_headers’/>

將重要標頭 crit 新增至 JWS。crit 標頭是標頭名稱陣列，JWS 接收器必須知道且可辨識其名稱。例如：

{
  “typ: “...”,
  “alg” : “...”,
  “crit” : [ “a”, “b”, “c” ],
}

在執行階段，VerifyJWS 政策會檢查 crit 標頭。針對 crit 標頭所列的每個標頭，它會檢查 <KnownHeaders> 元素。的 VerifyJWS 政策也會列出該標頭。VerifyJWS 政策在 crit 中發現的任何標頭也未列在 <KnownHeaders> 中，會導致 VerifyJWS 政策失敗。

注意： <CriticalHeaders> 實際上並非將標頭新增至 JWS。只會定義 crit 標頭的內容。您可以使用 <AdditionalHeader/Claims> 新增著作權聲明。

預設	不適用
外觀狀態	選用
類型	以半形逗號分隔的字串陣列
有效值	陣列或包含陣列的變數名稱。

<DetachContent>

<DetachContent>true|false</DetachContent>

指定是否要使用卸離酬載 <DetachContent>true</DetachContent> 產生 JWS。是否採用 <DetachContent>false</DetachContent>

如果指定 false，產生的 JWS 將採用以下格式：

header.payload.signature

如果指定 true 建立卸離酬載，產生的 JWS 會省略酬載，並採用以下格式：

header..signature

使用卸離酬載時，您可以選擇將原始的未編碼酬載傳送至 VerifyJWS 政策使用 VerifyJWS 政策的 <DetachedContent> 元素。

預設	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 酬載。指定包含酬載的變數，或是字串。

<Payload> 元素支援呼叫的動態字串替換功能訊息範本。訊息範本允許您在 payload-value 字串中執行變數字串替換。在以下範例中，酬載包含在要求的表單參數中：

<Payload>A JWS payload from a variable: {request.formparam.payload}</Payload>

預設	不適用
外觀狀態	必填
類型	字串、位元組陣列、串流，或任何其他未編碼 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 之一時。

預設	不適用
外觀狀態	選用
類型	字串
有效值	流程變數參照。注意：您必須指定流程變數。邊緣將拒絕為無效的政策設定 (以明文指定密碼)。流程變數都必須包含「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`

<SecretKey/Id>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
</SecretKey>

or

<SecretKey>
  <Id>your-id-value-here</Id>
</SecretKey>

針對以 HMAC 簽署的 JWS 標頭，指定要加入的金鑰 ID (kid)。演算法。只有在演算法為 HS256/HS384/HS512 之一時才能使用。

預設	不適用
外觀狀態	選用
類型	字串
有效值	流程變數或字串

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

提供透過 HMAC 演算法驗證或簽署權杖的密鑰。僅使用是 HS256/HS384/HS512 之一使用 ref 屬性以流程變數的形式傳遞金鑰

Edge 會強制 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。

錯誤名稱	發生時機
`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`	其他可能的部署錯誤。

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

其他可能的部署錯誤。

錯誤變數

系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知政策錯誤。

變數	地點	範例
`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>

GenerateJWS 政策

結果

影片

範例

產生以 HS256 簽署的 JWS 演算法

產生使用 RS256 簽署的卸離 JWS 演算法

設定主要元素

產生 JWS 的元素參照

具備的屬性 套用至頂層元素

&lt;DisplayName&gt;

&lt;Algorithm&gt;

&lt;AdditionalHeaders/Claim&gt;

&lt;CriticalHeaders&gt;

&lt;DetachContent&gt;

&lt;IgnoreUnresolvedVariables&gt;

&lt;OutputVariable&gt;

&lt;Payload&gt;

&lt;PrivateKey/Id&gt;

&lt;PrivateKey/Password&gt;

&lt;PrivateKey/Value&gt;

&lt;SecretKey/Id&gt;

&lt;SecretKey/Value&gt;

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

具備的屬性套用至頂層元素

<DisplayName>

<Algorithm>

<AdditionalHeaders/Claim>

<CriticalHeaders>

<DetachContent>

<IgnoreUnresolvedVariables>

<OutputVariable>

<Payload>

<PrivateKey/Id>

<PrivateKey/Password>

<PrivateKey/Value>

<SecretKey/Id>

<SecretKey/Value>