GenerateJWS 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

產生已簽署的 JWS，並提供可設定的陳述式集。接著，JSW 可傳回至用戶端、傳輸至後端目標，或以其他方式使用。如需詳細介紹，請參閱「JWS 和 JWT 政策總覽」。

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

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

影片

請觀看這部短片，瞭解如何產生已簽署的 JWT。雖然這部影片專門說明如何產生 JWT，但許多概念與 JWS 相同。

範例

[header].[payload].[signature]

<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="my-payload"/>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

<GenerateJWS name="JWS-Generate-HS256-JWT">
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
    </SecretKey>
    <Payload ref="json-content"/>
    <AdditionalHeaders>
        <Claim name="typ">JWT</Claim>
    </AdditionalHeaders>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

[header]..[signature]

<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="my-payload"/>
    <DetachContent>true</DetachContent>
    <OutputVariable>output-variable</OutputVariable>
</GenerateJWS>

設定關鍵元素

您用來指定用於產生 JWS 的金鑰的元素取決於所選演算法，如以下表格所示：

<SecretKey>
  <Value ref="private.secretkey"/>
  <Id>1918290</Id>
</SecretKey>

<PrivateKey>
  <Value ref="private.privatekey"/>
  <Password ref="private.privatekey-password"/>
  <Id ref="private.privatekey-id"/>
</PrivateKey>

Generate JWS 的元素參考

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

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

套用至頂層元素的屬性

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

以下屬性適用於所有政策父元素。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了使用名稱屬性，您也可以在 Apigee UI 代理程式編輯器中使用其他自然語言名稱標示政策。

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

指定用來簽署權杖的加密演算法。

<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 接收器知曉及辨識。舉例來說，您可以使用這個設定元素產生 JWS 標頭，在解碼後會如下所示：

{
  "typ": "...",
  "alg" : "...",
  "hyb" : "some-value-here",
  "crit" : [ "hyb" ],
}

這個 JWS 標頭會斷言 hyb 標頭參數的重要性，且 JWS 的任何收件者都必須瞭解該參數的意義和值。

根據 IETF RFC 7515 的規定，如果收件者無法理解 crit 參數中參照的一或多個參數，就應將 JWS 視為無效並拒絕。在 Apigee 中，VerifyJWS 政策符合此行為。 針對 crit 參數中列出的每個參數，檢查 VerifyJWS 政策的 <KnownHeaders> 元素是否也列出該參數。如果 VerifyJWS 政策在 crit 中找到的標頭未列於 <KnownHeaders> 中，就會導致 VerifyJWS 政策拒絕 JWS。

<DetachContent>

<DetachContent>true|false</DetachContent>

指定是否要使用已分離的酬載 (<DetachContent>true</DetachContent>) 或不使用 (<DetachContent>false</DetachContent>) 來產生 JWS。

如果您指定預設值 false，系統產生的 JWS 會採用以下格式：

[header].[payload].[signature]

如果您指定為 true 來建立含有分離酬載的 JWS，系統會省略酬載，並產生以下格式的 JWS：

[header]..[signature]

如果 JWS 使用的是分離酬載，您必須將原始未編碼酬載，連同序列化的 JWS 傳遞給驗證方。

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

如果您希望政策在無法解析政策中指定的任何參照變數時擲回錯誤，請將此屬性設為 false。將其設為 true，即可將任何無法解析的變數視為空字串 (空值)。

<OutputVariable>

<OutputVariable>output-variable</OutputVariable>

指定政策會使用產生的 JWS 設定的內容變數名稱。根據預設，政策會將 JWS 放入名為 jws.POLICYNAME.generated_jws 的內容變數中。

<Payload>

<Payload ref="flow-variable-name-here" />

or

<Payload>payload-value</Payload>

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

<PrivateKey> 元素

這是選用項目，只有在 <Algorithm> 為 RS*、PS* 或 ES* 選項時才會使用。它會指定用於簽署的私密金鑰，以及與私密金鑰相關的其他資訊。此值會在演算法為非對稱演算法時使用。

<PrivateKey>
   <Value ref="private.privatekey"</Value>
</PrivateKey>

<PrivateKey/Id>

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

or

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

指定要納入 JWS 標頭的金鑰 ID (kid)。

<PrivateKey/Password>

<PrivateKey>
  <Password ref="private.privatekey-password"/>
</PrivateKey>

視需要指定政策應使用的密碼，用於解密私密金鑰。使用 ref 屬性，在流程變數中傳遞鍵。

<PrivateKey/Value>

<PrivateKey>
  <Value ref="private.variable-name-here"/>
</PrivateKey>

指定用於簽署 JWS 的 PEM 編碼私密金鑰。使用 ref 屬性，在流程變數中傳遞鍵。

<SecretKey>

<SecretKey encoding="base16|hex|base64|base64url" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

指定產生使用對稱 (HS*) 演算法 (HS256、HS384 或 HS512 其中之一) 的 JWS 時要使用的秘密金鑰。

此元素為選用元素。不過，您必須加入 <PrivateKey> 或 <SecretKey> 元素。產生使用非對稱演算法 (RS*、PS* 或 ES*) 簽署的 JWS 時，請使用 <PrivateKey> 元素；產生使用對稱演算法 (HS* 等演算法) 簽署的 JWS 時，請使用 <SecretKey> 元素。

<SecretKey> 的子項

下表說明 <SecretKey> 的子元素和屬性：

<SecretKey encoding="hex" >
  <Id ref="variable-containing-key-id-here">secret-key-id</Id>
  <Value ref="private.secretkey"/>
</SecretKey>

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

or

<SecretKey>
  <Id>your-id-value-here</Id>
  <Value ref="private.variable-here"/>
</SecretKey>

<SecretKey>
  <Id ref="flow-variable-name-here"/>
  <Value ref="private.my-secret-variable"/>
</SecretKey>

<Type>

<Type>type-string-here</Type>

選用元素，其唯一允許的值為 Signed，可指定政策產生已簽署的 JWS。<Type> 只是為了與 GenerateJWT 和 VerifyJWT 政策的對應元素相符 (可採用 Signed 或 Encrypted 的任一值)。

流程變數

「產生 JWS」政策不會設定流程變數。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤變數

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

錯誤回應範例

針對錯誤處理，最佳做法是將錯誤的 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>