GenerateJWS 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

產生已簽署的 JWS，並提供可設定的聲明集。然後，JWS 可以傳回給用戶端、傳輸至後端目標，或以其他方式使用。如需詳細簡介，請參閱 JWS 和 JWT 政策總覽。

如要瞭解 JWS 的各個部分，以及加密和簽署方式，請參閱 RFC7515。

影片

請觀看這部短片，瞭解如何產生已簽署的 JWT。雖然這部影片專門介紹如何產生 JWT，但許多概念也適用於 JWS。

範例

產生以 HS256 演算法簽署的附加 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> 元素為選用項目。
*如要進一步瞭解金鑰規定，請參閱「簽章加密演算法簡介」。

Generate JWS 的元素參考資料

政策參考資料說明 Generate JWS 政策的元素和屬性。

注意：設定會因使用的加密演算法而略有不同。如需特定用途的設定範例，請參閱「範例」。

適用於頂層元素的屬性

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

所有政策父項元素都有下列屬性。

屬性 說明 預設 外觀狀態
名稱 政策的內部名稱。名稱只能使用以下字元： A-Z0-9._\-$ %。不過，Edge 管理使用者介面會強制執行額外限制，例如自動移除非英數的字元。

視需要使用 <displayname></displayname> 元素，在管理 UI 代理編輯器中，以其他自然語言名稱標示政策。

 不適用 必填
continueOnError 設為 false，在政策失敗時傳回錯誤。這是大多數政策的預期行為。

設為 true，即使政策失敗，流程執行作業仍會繼續。

 false 選用
已啟用 設為 true 即可強制執行政策。

設為 false 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。

 true 選用
非同步 這項屬性已淘汰。 false 已淘汰

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了名稱屬性之外，您也可以使用這個屬性，在管理 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 接收者必須知道並辨識這些名稱。例如：

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

在執行階段，VerifyJWS 政策會檢查 crit 標頭。 針對 crit 標頭中列出的每個標頭，系統會檢查 VerifyJWS 政策的 <KnownHeaders> 元素是否也列出該標頭。如果 VerifyJWS 政策在 crit 中找到任何標頭，但該標頭未列在 <KnownHeaders> 中，VerifyJWS 政策就會失敗。

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

<DetachContent>

<DetachContent>true|false</DetachContent>

指定是否要產生具有分離式酬載的 JWS，即 <DetachContent>true</DetachContent>，或不產生，即 <DetachContent>false</DetachContent>。

如果您指定預設值 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

<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 政策不會設定流程變數。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.GenerationFailed 401 The policy was unable to generate the JWS.
steps.jws.InsufficientKeyLength 401 For a key less than 32 bytes for the HS256 algorithm
steps.jws.InvalidClaim 401 For a missing claim or claim mismatch, or a missing header or header mismatch.
steps.jws.InvalidCurve 401 The curve specified by the key is not valid for the Elliptic Curve algorithm.
steps.jws.InvalidJsonFormat 401 Invalid JSON found in the JWS header.
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.KeyIdMissing 401 The Verify policy uses a JWKS as a source for public keys, but the signed JWS does not include a kid property in the header.
steps.jws.KeyParsingFailed 401 The public key could not be parsed from the given key information.
steps.jws.MissingPayload 401 The JWS payload is missing.
steps.jws.NoAlgorithmFoundInHeader 401 Occurs when the JWS omits the algorithm header.
steps.jws.SigningFailed 401 In GenerateJWS, for a key less than the minimum size for the HS384 or HS512 algorithms
steps.jws.UnknownException 401 An unknown exception occurred.
steps.jws.WrongKeyType 401 Wrong type of key specified. For example, if you specify an RSA key for an Elliptic Curve algorithm, or a curve key for an RSA algorithm.

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.

EmptyElementForKeyConfiguration

FailedToResolveVariable

InvalidConfigurationForActionAndAlgorithmFamily

InvalidConfigurationForVerify

InvalidEmptyElement

InvalidFamiliesForAlgorithm

InvalidKeyConfiguration

InvalidNameForAdditionalClaim

InvalidNameForAdditionalHeader

InvalidPublicKeyId

InvalidPublicKeyValue

InvalidSecretInConfig

InvalidTypeForAdditionalClaim

InvalidTypeForAdditionalHeader

InvalidValueForElement

InvalidValueOfArrayAttribute

InvalidVariableNameForSecret

MissingConfigurationElement

MissingElementForKeyConfiguration

MissingNameForAdditionalClaim

MissingNameForAdditionalHeader

 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>