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-he>re&quo<t; /

o>r

Payloadpay<load-val>ue/Payload

指定未編碼的原始 JWS 酬載。指定含有酬載的變數或字串。

預設 不適用
外觀狀態 必填
類型 未編碼 JWS 酬載的字串、位元組陣列、串流或任何其他表示法。

<PrivateKey/Id>

<PrivateKey>
  <Id ref="flow-variable-name-h>e<re"/
/>Privat<eKey

or

>Pri<va>teKey
  Idyour-id-<val>u<e-here/Id
/>PrivateKey

指定要納入 JWS 標頭的金鑰 ID (kid)。只有在演算法為 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 時才使用。

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

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-passw>o<rd"/
/>PrivateKey

視需要指定政策應使用的密碼，以解密私密金鑰。使用 ref 屬性在流程變數中傳遞金鑰。只有在演算法為 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 時才使用。

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

注意：您必須指定流程變數。如果政策設定以純文字指定密碼，Edge 會視為無效並拒絕。流程變數必須以「private」為前置字元。例如：private.mypassword

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-h>e<re"/
/>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-h>e<re"/
>/Secre<tKey

or
>
Se<cr>etKey
  Idyour-id-<val>u<e-here/Id
>/SecretKey

指定要納入以 HMAC 演算法簽署的 JWS 標頭中的金鑰 ID (kid)。僅在演算法為 HS256/HS384/HS512 時使用。

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-n>a<me"/
>/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。

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>