產生 JWT 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

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

政策是否產生已簽署或加密的 JWT，取決於您用來指定 JWT 生成演算法的元素：

如果您使用 <Algorithm> 元素，政策會產生已簽署的 JWT。
如果您使用 <Algorithms> 元素，政策會產生加密的 JWT。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

產生已簽署的 JWT

本節說明如何產生已簽署的 JWT。如為已簽署的 JWT，請使用 <Algorithm> 元素指定金鑰簽署演算法。

已簽署的 JWT 範例

下列範例說明如何產生已簽署的 JWT。

HS256 演算法

這項範例政策會產生新的 JWT，並使用 HS256 演算法簽署。HS256 依賴共用密鑰來簽署及驗證簽章。

觸發這項政策動作時，Apigee 會編碼 JWT 標頭和酬載，然後以數位方式簽署 JWT。如需完整範例，包括如何向政策提出要求，請觀看上方影片。

這裡的政策設定會建立一組 JWT，其中包含 JWT 規格定義的一組標準附加資訊，包括 1 小時的效期，以及額外的附加資訊。你可以視需要加入多項額外聲明。如要進一步瞭解本範例政策中各項元素的需求和選項，請參閱元素參考資料。

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <Type>Signed</Type>
    <Algorithm>HS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <SecretKey>
        <Value ref="private.secretkey"/>
        <Id>1918290</Id>
    </SecretKey>
    <ExpiresIn>1h</ExpiresIn>
    <Subject>monty-pythons-flying-circus</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>fans</Audience>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

產生的 JWT 會包含這個標頭：

{
  "typ" : "JWT",
  "alg" : "HS256",
  "kid" : "1918290"
}

…，且酬載內容如下：

{
  "sub" : "monty-pythons-flying-circus",
  "iss" : "urn://apigee-JWT-policy-test",
  "aud" : "fans",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

iat、exp 和 jti 聲明的值會有所不同。

RS256 演算法

注意： 使用這個範例，為 PS256 或 ES256 演算法產生 JWT。只要將 <Algorithm>RS256</Algorithm> 的值變更為 PS256 或 ES256 即可。對於 ES256，您也必須指定與演算法相容的金鑰。如要進一步瞭解金鑰規定，請參閱「關於簽章加密演算法」一文。

這項範例政策會產生新的 JWT，並使用 RS256 演算法簽署。產生 RS256 簽章時，需要使用 RSA 私密金鑰 (必須以 PEM 編碼形式提供)，且金鑰可能經過密碼加密。如需完整範例，包括如何向政策提出要求，請觀看上方影片。

觸發這項政策動作時，Apigee 會編碼並以數位方式簽署 JWT，包括宣告。如要瞭解 JWT 的各個部分，以及加密和簽署方式，請參閱 RFC7519。

<GenerateJWT name="JWT-Generate-RS256">
    <Type>Signed</Type>
    <Algorithm>RS256</Algorithm>
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <PrivateKey>
        <Value ref="private.privatekey"/>
        <Password ref="private.privatekey-password"/>
        <Id ref="private.privatekey-id"/>
    </PrivateKey>
    <Subject>apigee-seattle-hatrack-montage</Subject>
    <Issuer>urn://apigee-JWT-policy-test</Issuer>
    <Audience>urn://c60511c0-12a2-473c-80fd-42528eb65a6a</Audience>
    <ExpiresIn>60m</ExpiresIn>
    <Id/>
    <AdditionalClaims>
        <Claim name="show">And now for something completely different.</Claim>
    </AdditionalClaims>
    <OutputVariable>jwt-variable</OutputVariable>
</GenerateJWT>

上述範例使用 <Algorithm> 元素，因此會產生已簽署的 JWT。<PrivateKey> 元素會指定用於簽署 JWT 的加密金鑰。此外，還有其他重要元素。您使用的演算法取決於 <Algorithm> 值指定的演算法，詳情請見下一節。

設定已簽署 JWT 的重要元素

請使用下列其中一個元素，指定用於產生已簽署 JWT 的金鑰：

<SecretKey>
<PrivateKey>

使用的元素取決於所選演算法，如下表所示：

演算法	重要元素
HS{256/384/512}^*	<SecretKey> <Value ref="private.secretkey"/> <Id ref="secretkey-id">key-1918290</Id> </SecretKey>
RS/PS/ES{256/384/512}^*	<PrivateKey> <Value ref="private.privatekey"/> <Password ref="private.privatekey-password"/> <Id ref="privatekey-id">key-1918290</Id> </PrivateKey>

演算法

重要元素

HS{256/384/512}^*

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

RS/PS/ES{256/384/512}^*

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

在上述範例中，<Password> 和 <Id> 元素為選用項目。

如要進一步瞭解金鑰規定，請參閱「關於簽章加密演算法」。

產生加密的 JWT

本節說明如何產生加密的 JWT。如果是加密的 JWT，請使用 <Algorithms> 元素，指定簽署金鑰和內容的演算法。

加密 JWT 的範例

下列範例顯示如何產生加密的 JWT。範例使用 <Algorithms> 元素，因此會產生加密的 JWT。

RSA-OAEP-256

在下列範例中：

金鑰會以 RSA-OAEP-256 演算法加密。
內容會以 A128GCM 演算法加密。

<PublicKey> 元素會指定用於金鑰加密的金鑰。

<GenerateJWT name="gjwt-1">
  <Type>Encrypted</Type>
  <Algorithms>
    <Key>RSA-OAEP-256</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <PublicKey>
    <Value ref="rsa_publickey"/>
  </PublicKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <AdditionalHeaders>
    <Claim name="moniker">Harvey</Claim>
  </AdditionalHeaders>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

A128KW

在下列範例中：

金鑰會以 A128KW 演算法加密。
內容會以 A128GCM 演算法加密。

<SecretKey> 元素會指定用於金鑰加密的金鑰。

<GenerateJWT name='gjwt-2'>
  <Algorithms>
    <Key>A128KW</Key>
    <Content>A128GCM</Content>
  </Algorithms>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <SecretKey>
    <Value ref='private.secretkey'/>
  </SecretKey>
  <Subject>subject@example.com</Subject>
  <Issuer>urn://apigee</Issuer>
  <ExpiresIn>1h</ExpiresIn>
  <OutputVariable>output_var</OutputVariable>
</GenerateJWT>

設定加密 JWT 的重要元素

如要產生加密的 JWT，請使用下列其中一個元素，指定 GenerateJWT 的加密金鑰：

<PublicKey>
<SecretKey>
<PasswordKey>
<DirectKey>

您使用的元素取決於所選的金鑰加密演算法，如下表所示：

金鑰加密演算法	重要元素
RSA-OAEP-256	<PublicKey> <Value ref="rsa_publickey"/> </PublicKey> 注意：金鑰必須解析為 RSA 公開金鑰。
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	<PublicKey> <Value ref="ec_publickey"/> </PublicKey> 注意：金鑰必須解析為橢圓曲線公開金鑰。
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	<SecretKey> <Id>optional key identifier here</Id> <Value ref="private.secretkey"/> </SecretKey>
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	<PasswordKey> <Id>optional key identifier here</Id> <Value ref="private.passwordkey"/> <SaltLength> <PBKDF2Iterations> </PasswordKey>
dir	<DirectKey> <Id>optional key identifier here</Id> <Value encoding="base16\|hex\|base64\|base64url" ref="private.directkey"/> </DirectKey>

如要進一步瞭解金鑰規定，請參閱「關於簽章加密演算法」。

產生 JWT 的元素參考資料

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

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

適用於頂層元素的屬性

<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">

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

屬性	說明	預設	外觀狀態
名稱	政策的內部名稱。名稱只能使用以下字元： `A-Z0-9._\-$ %`。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。您可以視需要使用 `<displayname></displayname>` 元素，在 Apigee UI 代理項目編輯器中，以其他自然語言名稱標示政策。	不適用	必填
continueOnError	設為 `false`，在政策失敗時傳回錯誤。這是大多數政策的預期行為。設為 `true`，即使政策失敗，流程執行作業仍會繼續。	false	選用
已啟用	設為 `true` 即可強制執行政策。設為 `false` 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。	true	選用
非同步	這項屬性已淘汰。	false	已淘汰

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了名稱屬性之外，您也可以使用這個屬性，在 Apigee UI 代理項目編輯器中，以其他自然語言名稱標記政策。

預設	如果省略這個元素，系統會使用政策名稱屬性的值。
外觀狀態	選用
類型	字串

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

指定用來簽署權杖的加密演算法。使用 <Algorithm> 元素產生已簽署的 JWT。

注意：請使用 <Algorithm> 和 <Algorithms> 元素中的其中一個。

預設	不適用
外觀狀態	(選用) 請提供 `<Algorithm>` 或 `<Algorithms>`。
類型	字串
有效值	HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512

<Algorithms>

<Algorithms>
    <Key>key-algorithm</Key>
    <Content>content-algorithm</Content>
</Algorithms>

指定金鑰和內容加密的加密演算法。使用 <Algorithms> 元素產生加密的 JWT。

注意：請使用 <Algorithm> 和 <Algorithms> 元素中的其中一個。

預設	不適用
(選用) 請提供 `<Algorithm>` 或 `<Algorithms>`。	必填
類型	字串

`<Algorithms>` 的子元素

下表簡要說明 <Algorithms> 的子元素：

子元素	是否必要	說明
`<Key>`	必填	指定金鑰的加密演算法。
`<Content>`	必填	指定內容的加密演算法。

金鑰加密演算法

下表列出可用的金鑰加密演算法。

`<Key>` 的值 (金鑰加密演算法)	必須提供索引鍵元素
dir	`<DirectKey>`
RSA-OAEP-256	`<PublicKey>` (必須解析為 RSA 公開金鑰)
A128KW A192KW A256KW A128GCMKW A192GCMKW A256GCMKW	`<SecretKey>`
PBES2-HS256+A128KW PBES2-HS384+A192KW PBES2-HS512+A256KW	`<PasswordKey>`
ECDH-ES ECDH-ES+A128KW ECDH-ES+A192KW ECDH-ES+A256KW	`<PublicKey>` (必須解析為橢圓曲線公開金鑰)

如需金鑰加密演算法為 RSA-OAEP-256 的範例，請參閱「產生加密的 JWT」，因此您會使用 <PublicKey> 元素，其值會解析為 RSA 公開金鑰。

內容加密演算法

下列演算法 (對稱式、以 AES 為基礎) 可用於加密內容：

A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
A128GCM
A192GCM
A256GCM

如要進一步瞭解所有這些演算法，請參閱 RFC7518。

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

這項政策會產生 JWT，其中包含設為指定值的 aud 憑證附加資訊。這項聲明會識別 JWT 的目標收件者。這是 RFC7519 中提及的已註冊聲明之一。

預設	不適用
外觀狀態	選用
類型	陣列 (以半形逗號分隔的值清單)
有效值	任何可識別目標對象的資訊。

<AdditionalClaims/Claim>

<AdditionalClaims>
    <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'/>
</AdditionalClaims>

or:

<AdditionalClaims ref='claim_payload'/>

您可以在 JWT 的酬載中指定其他憑證附加資訊名稱/值組。您可以將聲明明確指定為字串、數字、布林值、對應或陣列。對應只是名稱/值組合的集合。

當 type=map 時，<Claim> 元素支援稱為「訊息範本」的動態字串替代功能。

預設	不適用
外觀狀態	選用
有效值	您要用於額外聲明的任何值。您可以將聲明明確指定為字串、數字、布林值、對應或陣列。

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

name - (必填) 聲明名稱。
注意：請勿在這個元素中使用任何已註冊的聲明名稱。註冊的聲明定義於 RFC7519。包括：「iss」、「sub」、「aud」、「iat」、「exp」、「nbf」和「jti」。
ref - (選用) 流程變數的名稱。如果存在，政策會使用這個變數的值做為聲明。如果同時指定 ref 屬性和明確的聲明值，系統會預設使用明確值，並在參照的流程變數未解析時使用該值。
type - (選用) 其中一個值：字串 (預設)、數字、布林值或對應
array - (選用) 設為 true，表示值是否為型別陣列。預設值： false。

加入 <Claim> 元素後，您可以在設定政策時靜態設定聲明名稱。或者，您也可以傳遞 JSON 物件來指定聲明名稱。由於 JSON 物件是以變數形式傳遞，因此產生的 JWT 中的聲明名稱是在執行階段決定。

例如：

<AdditionalClaims ref='json_claims'/>

其中，變數 json_claims 包含 JSON 物件，格式如下：

{
  "sub" : "person@example.com",
  "iss" : "urn://secure-issuer@example.com",
  "non-registered-claim" : {
    "This-is-a-thing" : 817,
    "https://example.com/foobar" : { "p": 42, "q": false }
  }
}

產生的 JWT 會包含 JSON 物件中的所有聲明。

請注意，在 Claim 元素中同時使用變數參照和明確聲明值時，會出現下列行為：

在下列情況下，Apigee 不會產生聲明：

如果存在變數參照，但未解析，且
如未指定明確值 (預設值)，且
如果 IgnoreUnresolvedVariables 政策屬性為 true。

如果 IgnoreUnresolvedVariables 為 false，Apigee 會在上述條件下擲回錯誤。

在下列情況下，Apigee 會產生聲明：

如果存在變數參照，但未解析，且
如果您指定明確值 (預設值)，且
如果 IgnoreUnresolvedVariables 是 true 或 false

<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>

將額外的憑證附加資訊名稱/值配對放入 JWT 的標頭中。

當 type=map 時，<Claim> 元素支援稱為「訊息範本」的動態字串替代功能。

預設	不適用
外觀狀態	選用
有效值	您要用於額外聲明的任何值。您可以將聲明明確指定為字串、數字、布林值、對應或陣列。

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

name - (必填) 聲明名稱。
注意：請勿在這個元素中使用任何已註冊的聲明名稱。註冊的聲明定義於 RFC7519。包括：「iss」、「sub」、「aud」、「iat」、「exp」、「nbf」和「jti」。
ref - (選用) 流程變數的名稱。如果存在，政策會使用這個變數的值做為聲明。如果同時指定 ref 屬性和明確的聲明值，系統會預設使用明確值，並在參照的流程變數未解析時使用該值。
type - (選用) 其中一個值：字串 (預設)、數字、布林值或對應
array - (選用) 設為 true，表示值是否為型別陣列。預設值： false。

<Compress>

<Compress>true</Compress>

指定是否要在加密前壓縮文字。這個元素僅在產生加密的 JWT 時有效。

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

將重要標頭 crit 新增至 JWT 標頭。crit 標頭是標頭名稱的陣列，JWT 接收者必須知道並辨識這些名稱。例如：

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

根據規格，驗證方必須檢查 crit 標頭，並確認瞭解每個標頭。舉例來說，VerifyJWT 政策會檢查 crit 標頭。針對 crit 標頭中列出的每個項目，系統會檢查 VerifyJWT 政策的 <KnownHeaders> 元素是否也列出該標頭。如果 VerifyJWT 政策在 crit 中找到任何標頭，但該標頭未列在 <KnownHeaders> 中，VerifyJWT 政策就會失敗。

注意： <CriticalHeaders> 實際上不會將標頭新增至 JWT。它只會定義 crit 標頭的內容。您可以使用 <AdditionalHeader/Claims> 新增標頭。

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

<CustomClaims>

注意：目前透過 UI 新增 GenerateJWT 政策時，系統會插入 CustomClaims 元素。這個元素無法運作，因此遭到忽略。請改用 <AdditionalClaims> 元素。使用者介面會在稍後更新，插入正確的元素。

<DirectKey>

<DirectKey>
  <Id>A12345</Id>
  <Value encoding="base16|hex|base64|base64url" ref="private.directkey"/>
</DirectKey>

指定加密演算法為 dir (「直接加密」) 時，用於加密 JWT 的直接金鑰。

`<DirectKey>` 的子元素

下表簡要說明 <DirectKey> 的子元素：

子元素	是否必要	說明
ID	選用	金鑰 ID
值	必填	使用 `ref` 屬性指定變數的參照。參照變數的內容必須是位元組陣列的字串編碼，並透過十六進位 (base16)、base64 或 base64url 編碼。

使用直接金鑰加密時，您可以直接提供一系列位元組，做為內容加密金鑰 (CEK)。您必須將位元組陣列指定為編碼字串。位元組陣列的長度取決於所選內容加密演算法的強度。舉例來說，如果是 A256CBC-HS512，您必須提供 512 位元 (或 64 位元組) 的金鑰。

變數 private.directkey 的內容必須是經過編碼的字串，編碼方式可以是十六進位 (base16)、base64 或 base64url。舉例來說，以下是經過十六進位編碼的 32 位元組金鑰：

96 4b e1 71 15 71 5f 87 11 0e 13 52 4c ec 1e ba df 47 62 1a 9d 3b f5 ad d2 7b b2 35 e7 d6 17 11

如果是十六進位編碼，可接受空白字元，但並非必要，且可接受大寫或小寫 (B7 與 b7 相同)。

上述內容的 base64url 編碼等效值為：

lkvhcRVxX4cRDhNSTOweut9HYhqdO/Wt0nuyNefWFxE

對於 base64* 變體，系統不接受空白字元，且會區分大小寫。如未指定編碼方式，政策會假設編碼方式為 Base64。

以下說明金鑰長度規定：

內容加密演算法	金鑰長度規定
A128CBC-HS256	256 位元 (32 個位元組)
A192CBC-HS384	384 (48)
A256CBC-HS512	512 (64)
A128GCM	128 (16)
A192GCM	192 (24)
A256GCM	256 (32)

注意：透過 <DirectKey> 元素提供的內容加密金鑰，長度必須完全符合指定的內容加密演算法。如果金鑰加密演算法不是 dir，政策會產生長度正確的隨機 CEK，但如果是 dir，設定必須明確提供大小正確的金鑰。

<ExpiresIn>

<ExpiresIn>time-value-here</ExpiresIn>

or:

<ExpiresIn ref='time-value-here'/>

以毫秒、秒、分鐘、小時或天為單位，指定 JWT 的生命週期。使用 XML 元素或 ref 屬性指定到期時間，但不能同時使用兩者。

預設	`N/A`
外觀狀態	選用
類型	整數
有效值	值或含有該值的流程變數參照。時間單位可指定如下： ms = 毫秒 (預設值) s = 秒 m = 分鐘 h = 小時 d = 天舉例來說，`ExpiresIn`=10d 相當於 `ExpiresIn` 為 864000s。

<Id>

<Id>explicit-jti-value-here</Id>
 -or-
<Id ref='variable-name-here'/>
 -or-
<Id/>

產生具有特定 jti 聲明的 JWT。如果文字值和 ref 屬性都空白，政策會產生含有隨機 UUID 的 jti。JWT ID (jti) 聲明是 JWT 的專屬 ID。如要進一步瞭解 jti，請參閱 RFC7519。

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

預設	否
外觀狀態	選用
類型	布林值
有效值	true 或 false

<Issuer>

<Issuer ref='variable-name-here'/>
<Issuer>issuer-string-here</Issuer>

這項政策會產生 JWT，其中包含名為 iss 的憑證附加資訊，且值會設為指定值。用於識別 JWT 核發者的憑證附加資訊。這是 RFC7519 中提及的已註冊聲明集之一。

預設	不適用
外觀狀態	選用
類型	字串或參照
有效值	不限

<NotBefore>

<!-- Specify an absolute time. -->
<NotBefore>2017-08-14T11:00:21-07:00</NotBefore>
 -or-
<!-- Specify a time relative to when the token is generated. -->
<NotBefore>6h</NotBefore>

指定權杖生效的時間。權杖在指定時間前無效。您可以指定絕對時間值，也可以指定相對於權杖產生時間的時間。

預設	不適用
外觀狀態	選用
類型	字串
有效值	如下所示。

NotBefore 元素適用於絕對時間值的有效時間值

名稱	格式	範例
可排序	`yyyy-MM-dd'T'HH:mm:ss.SSSZ`	2017-08-14T11:00:21.269-0700
RFC 1123	`EEE, dd MMM yyyy HH:mm:ss zzz`	Mon, 14 Aug 2017 11:00:21 PDT
RFC 850	`EEEE, dd-MMM-yy HH:mm:ss zzz`	2017 年 8 月 14 日星期一 11:00:21 PDT
ANCI-C	`EEE MMM d HH:mm:ss yyyy`	Mon Aug 14 11:00:21 2017

如為相對時間值，請指定整數和時間範圍，例如：

10 秒
60 公尺
12 小時

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

指定要放置這項政策產生的 JWT 的位置。預設會放入流程變數 jwt.POLICYNAME.generated_jwt。

預設	`jwt.POLICYNAME.generated_jwt`
外觀狀態	選用
類型	字串 (流程變數名稱)

<PasswordKey>

<PasswordKey>
  <Id>abcdefg</Id>
  <Value ref="private.password"/>
  <SaltLength>8</SaltLength>
  <PBKDF2Iterations>10000</PBKDF2>
</PasswordKey>

指定加密演算法為下列其中一種時，用來加密 JWT 的金鑰：

PBES2-HS256+A128KW
PBES2-HS384+A192KW
PBES2-HS512+A256KW

針對每個金鑰演算法，您都必須透過元素 <Value ref="private.password"/> 中的變數 private.password 提供密碼，藉此衍生金鑰加密金鑰。

`<PasswordKey>` 的子元素

下表簡要說明 <PasswordKey> 的子元素：

子元素	狀態	說明
ID	選用	金鑰 ID
值	必填	指定用來產生金鑰加密金鑰的密碼。使用 `ref` 屬性，並指定變數，例如 `private.password`。
SaltLength	選用	鹽的長度。預設值：8 個位元組。
PBKDF2Iterations	選用	PBKDF2 疊代次數：預設值為 10000。

<PrivateKey>

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

指定產生已簽署 JWT 時要使用的私密金鑰，且 Algorithm 是 RSA 或橢圓曲線 (EC) 變體，例如 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512。

`<PrivateKey>` 的子元素

下表說明 <PrivateKey> 的子元素：

子元素狀態說明

選用

子元素	狀態	說明
ID	選用	金鑰 ID。此值可以是任何字串。您可以將值指定為常值文字值，也可以透過變數參照間接指定，並使用 `ref` 屬性。這項政策會將這個金鑰 ID 做為 `kid` 聲明，加入產生的 JWT 標頭中。
值	必填	PEM 編碼的私密金鑰。指定用於簽署酬載的私密金鑰。使用 `ref` 屬性，並指定變數，例如 `private.private-key`。如果 `<Algorithm>` 元素包含 RSA 變體 (RS256/RS384/RS512 或 PS256/PS384/PS512)，則必須提供編碼的 RSA 私密金鑰。如果 `<Algorithm>` 元素包含 EC 變體 (ES256/ES384/ES512 其中之一)，您必須提供適當曲線的橢圓曲線私密金鑰。
密碼	選用	如果需要，政策應使用此密碼解密私密金鑰。使用 `ref` 屬性透過流程變數傳遞密碼。注意：您必須指定流程變數。如果政策設定以純文字指定密碼，Apigee 會拒絕這項設定，視為無效。流程變數必須以「private」為前置字元。例如：`private.mypassword`

金鑰 ID。此值可以是任何字串。您可以將值指定為常值文字值，也可以透過變數參照間接指定，並使用 ref 屬性。

這項政策會將這個金鑰 ID 做為 kid 聲明，加入產生的 JWT 標頭中。

值

必填

PEM 編碼的私密金鑰。指定用於簽署酬載的私密金鑰。使用 ref 屬性，並指定變數，例如 private.private-key。

如果 <Algorithm> 元素包含 RSA 變體 (RS256/RS384/RS512 或 PS256/PS384/PS512)，則必須提供編碼的 RSA 私密金鑰。如果 <Algorithm> 元素包含 EC 變體 (ES256/ES384/ES512 其中之一)，您必須提供適當曲線的橢圓曲線私密金鑰。

密碼

選用

如果需要，政策應使用此密碼解密私密金鑰。使用 ref 屬性透過流程變數傳遞密碼。

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

<PublicKey>

<PublicKey>
  <!-- specify exactly one of the following -->
  <Value ref="variable-containing-encoded-publickey"/>
  <Value>PEM encoded public key</Value>
  <Certificate ref="variable-containing-encoded-x509-certificate"/>
  <Certificate>PEM encoded X509 certificate</Certificate>
  <JWKS>jwks-content</JWKS>
  <JWKS ref="variable-containing-jwks-content"/>
  <JWKS uri="variable-containing-jwks-content"/>
  <JWKS uriRef="variable-containing-uri"/>
</PublicKey>

指定產生加密 JWT 時要使用的公開金鑰，且 Key 演算法是 RSA 或橢圓曲線 (EC) 變體，例如 RSA-OAEP-256、ECDH-ES、ECDH-ES+A128KW、ECDH-ES+A192KW 或 ECDH-ES+A256KW。

`<PublicKey>` 的子元素

請提供 Value、Certificate 或 JWKS 其中一個。如果指定 JWKS，就必須一併指定 Id。下表說明 <PublicKey> 的子元素：

子元素	說明
值	PEM 編碼的公開金鑰。指定政策應使用的公開金鑰，用來加密內容加密金鑰。您可以直接指定鍵，也可以透過變數參照間接指定。 <PublicKey> <Value ref="public.publickey"/> </PublicKey> 或 <PublicKey> <Value> -----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw2kPrRzcufvUNHvTH/WW 2F73IyN....your key will vary....1jC0dwUD1lHV8MfUyRXmpmnNxJHACof C5TBtXMORc+us7A2cTtC4gZV256bT4h3sIEMsDl0Joz9K9MPzVPFxa1i0RgNt06n ZmkDb/DRW5onclGzxQITBFP3S6JXd4LNESJcTp705ec1cQ9Wp2Kl+nKrKyv1E5Xx DQIDAQAB -----END PUBLIC KEY----- </Value> </PublicKey> 如果您使用 RSA-OAEP-256 演算法，編碼後的公開金鑰必須表示 RSA 金鑰；如果您使用 EC 演算法，則必須表示適當曲線的 EC 金鑰。
憑證	PEM 編碼的 X.509 憑證，用於包裝公開金鑰。Apigee 會從憑證中擷取公開金鑰，然後使用該金鑰加密內容加密金鑰。您可以直接指定憑證，也可以透過變數參照間接指定。 <PublicKey> <Certificate ref="public.pem-encoded-certificate"/> </PublicKey> 或 <PublicKey> <Certificate> -----BEGIN CERTIFICATE----- MIIDqDCCApACCQCG/xVb7Yzw3zANBgkqhkiG9w0BAQUFADCBlTELMAkGA1UEBhMC 2F73IyN....your certificate data will vary....1jC0dwUD1lHV8MfUyR VQQKDAZHb29nbGUxDzANBgNVBAsMBkFwaWdlZTEaMBgGA1UEAwwRYXBpZ2VlLmdv ... YjBaZuNUDVLGvbTSRgWG5lwm85Jar2zeCBcxFDwqyZFvVNV9SfoWF/LgVVpK54n8 rknZ17USb0ob51ckxPTENmF2DUHBzgptiw10Yw== -----END CERTIFICATE----- </Certificate> </PublicKey> 如果您使用 RSA-OAEP-256 演算法，編碼後的公開金鑰必須表示 RSA 金鑰；如果您使用 EC 演算法，則必須表示適當曲線的 EC 金鑰。注意：Apigee 不會驗證您提供的憑證效期，也不會驗證憑證的信任鏈結。Apigee 會將您使用這個元素指定的所有憑證視為有效且可信任。
JWKS	公開金鑰的 JWKS 來源。這份清單會列出符合 IETF RFC 7517 - JSON Web Key (JWK) 格式的金鑰。您可以透過下列四種方式之一指定 JWKS：以文字值形式： <PublicKey> <JWKS>jwks-content-here</JWKS> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 間接指定流程變數，使用 `ref` 屬性： <PublicKey> <JWKS ref="variable-containing-jwks-content"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 參照的變數應包含代表 JWKS 的字串。透過靜態 URI 間接存取，並使用 `uri` 屬性： <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 透過動態決定的 URI 間接設定，並使用 `uriRef` 屬性： <PublicKey> <JWKS uriRef="variable-containing-a-uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey> 在所有情況下，於 GenerateJWT 中指定 `JWKS` 元素來產生加密 JWT 時，您也必須指定 `PublicKey/Id` 元素。 <PublicKey> <JWKS uri="uri-that-returns-a-jwks"/> <Id ref="variable-containing-a-kid">literal-value-here</Id> </PublicKey>
ID	代表金鑰 ID 的字串。在執行階段，Apigee 會從 JWKS 擷取具有與這個值相符的 `kid` 欄位的金鑰。如果您在 GenerateJWT 中使用 `JWKS` 元素，就必須使用 `Id` 元素。

<SecretKey>

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

SecretKey 元素為選用項目。指定產生已簽署 JWT 時要使用的密鑰，該 JWT 使用對稱 (HS*) 演算法；或指定產生已加密 JWT 時要使用的密鑰，該 JWT 使用對稱 (AES) 演算法進行金鑰加密。

「`<SecretKey>`」的子女

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

子項狀態說明

編碼 (屬性)

選用

子項	狀態	說明
編碼 (屬性)	選用	指定如何編碼參照變數中的金鑰。根據預設，如果沒有 `encoding` 屬性，系統會將鍵的編碼視為 UTF-8。這個屬性的有效值為：十六進位、base16、base64 或 base64url。編碼值 hex 和 base16 是同義詞。 <SecretKey encoding="VALUE_HERE" > <Id ref="variable-containing-key-id-here">secret-key-id</Id> <Value ref="private.secretkey"/> </SecretKey> 在上述範例中，如果編碼屬性為 `hex`，且變數 `private.secretkey` 的內容為 `494c6f766541504973`，則金鑰會解碼為一組 9 個位元組，以十六進位表示則為 `49 4c 6f 76 65 41 50 49 73`。反之，如果編碼屬性為 `base64`，且變數 `private.secretkey` 的內容為 `VGhpcy1pcy1hLXNlY3JldA`，則金鑰會解碼為一組 16 個位元組 (十六進位)：`54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74`。注意：Apigee 會強制執行最低金鑰強度。詳情請參閱 `Value` 元素說明文件。
ID (元素)	選用	金鑰 ID。此值可以是任何字串。您可以將值指定為常值文字值，也可以透過變數參照間接指定，並使用 `ref` 屬性。 <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> 這項政策會將這個金鑰 ID 做為 `kid` 聲明，加入產生的 JWT 標頭中。
值 (元素)	必填	經過編碼的密鑰。指定用於簽署酬載的密鑰。使用 `ref` 屬性透過變數 (例如 `private.secret-key`) 間接提供金鑰。 <SecretKey> <Id ref="flow-variable-name-here"/> <Value ref="private.my-secret-variable"/> </SecretKey> 注意：變數名稱必須包含 private 前置字元，如上例所示。 Apigee 會針對 HS256/HS384/HS512 演算法強制執行最低金鑰強度。HS256 的金鑰長度下限為 32 個位元組，HS384 為 48 個位元組，HS512 則為 64 個位元組。使用強度較低的金鑰會導致執行階段錯誤。

指定如何編碼參照變數中的金鑰。根據預設，如果沒有 encoding 屬性，系統會將鍵的編碼視為 UTF-8。這個屬性的有效值為：十六進位、base16、base64 或 base64url。編碼值 hex 和 base16 是同義詞。

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

在上述範例中，如果編碼屬性為 hex，且變數 private.secretkey 的內容為 494c6f766541504973，則金鑰會解碼為一組 9 個位元組，以十六進位表示則為 49 4c 6f 76 65 41 50 49 73。反之，如果編碼屬性為 base64，且變數 private.secretkey 的內容為 VGhpcy1pcy1hLXNlY3JldA，則金鑰會解碼為一組 16 個位元組 (十六進位)：54 68 69 73 2d 69 73 2d 61 2d 73 65 63 72 65 74。

注意：Apigee 會強制執行最低金鑰強度。詳情請參閱 Value 元素說明文件

。

ID (元素)

選用

金鑰 ID。此值可以是任何字串。您可以將值指定為常值文字值，也可以透過變數參照間接指定，並使用 ref 屬性。

<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>

這項政策會將這個金鑰 ID 做為 kid 聲明，加入產生的 JWT 標頭中。

值 (元素)

必填

經過編碼的密鑰。指定用於簽署酬載的密鑰。使用 ref 屬性透過變數 (例如 private.secret-key) 間接提供金鑰。

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

Apigee 會針對 HS256/HS384/HS512 演算法強制執行最低金鑰強度。HS256 的金鑰長度下限為 32 個位元組，HS384 為 48 個位元組，HS512 則為 64 個位元組。使用強度較低的金鑰會導致執行階段錯誤。

<Subject>

<Subject>subject-string-here</Subject>

或

<Subject ref="flow_variable" />

例如：

<Subject ref="apigee.developer.email"/>

這項政策會產生含有 sub 憑證附加資訊的 JWT，並設為指定值。這項憑證附加資訊會識別 JWT 的主體或做出相關陳述。這是 IETF RFC 7519 中提及的標準聲明集之一。

預設	不適用
外觀狀態	選用
類型	字串
有效值	任何可明確識別主體的值，或參照值的流程變數。

<Type>

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

說明政策是否會產生已簽署或加密的 JWT。<Type> 元素為選用項目。您可以使用這項屬性，向讀者說明政策是否會產生已簽署或加密的 JWT。

如果存在 <Type> 元素：
- 如果 <Type> 的值為 Signed，政策會產生已簽署的 JWT，且必須存在 <Algorithm> 元素。
- 如果 <Type> 的值為 Encrypted，政策會產生加密的 JWT，且必須有 <Algorithms> 元素。
如果沒有 <Type> 元素：
- 如果存在 <Algorithm> 元素，政策會假設 <Type> 為 Signed。
- 如果存在 <Algorithms> 元素，政策會假設 <Type> 為 Encrypted。
如果沒有 <Algorithm> 或 <Algorithms>，設定無效。

預設	不適用
外觀狀態	選用
類型	字串
有效值	`Signed` 或 `Encrypted`

流程變數

產生 JWT 政策不會設定流程變數。

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.jwt.AlgorithmInTokenNotPresentInConfiguration`	`401`	Occurs when the verification policy has multiple algorithms.
`steps.jwt.AlgorithmMismatch`	`401`	The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.
`steps.jwt.EncryptionFailed`	`401`	Creation of an encrypted JWT failed for a non-specific reason
`steps.jwt.FailedToDecode`	`401`	The policy was unable to decode the JWT. The JWT is possibly corrupted.
`steps.jwt.GenerationFailed`	`401`	The policy was unable to generate the JWT.
`steps.jwt.InsufficientKeyLength`	`401`	For a key less than 32 bytes for the HS256 algorithm, less than 48 bytes for the HS386 algortithm, and less than 64 bytes for the HS512 algorithm.
`steps.jwt.InvalidClaim`	`401`	For a missing claim or claim mismatch, or a missing header or header mismatch.
`steps.jwt.InvalidConfiguration`	`401`	Both the `<Algorithm>` and `<Algorithms>` elements are present.
`steps.jwt.InvalidCurve`	`401`	The curve specified by the key is not valid for the Elliptic Curve algorithm.
`steps.jwt.InvalidJsonFormat`	`401`	Invalid JSON found in the header or payload.
`steps.jwt.InvalidPasswordKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidPrivateKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidPublicKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidSecretKey`	`401`	The specified key specified did not meet the requirements.
`steps.jwt.InvalidToken`	`401`	This error occurs when the JWT signature verification fails.
`steps.jwt.JwtAudienceMismatch`	`401`	The audience claim failed on token verification.
`steps.jwt.JwtIssuerMismatch`	`401`	The issuer claim failed on token verification.
`steps.jwt.JwtSubjectMismatch`	`401`	The subject claim failed on token verification.
`steps.jwt.KeyIdMissing`	`401`	The Verify policy uses a JWKS as a source for public keys, but the signed JWT does not include a `kid` property in the header.
`steps.jwt.KeyParsingFailed`	`401`	The public key could not be parsed from the given key information.
`steps.jwt.NoAlgorithmFoundInHeader`	`401`	Occurs when the JWT contains no algorithm header.
`steps.jwt.NoMatchingPublicKey`	`401`	The Verify policy uses a JWKS as a source for public keys, but the `kid` in the signed JWT is not listed in the JWKS.
`steps.jwt.SigningFailed`	`401`	In `GenerateJWT`, for a key less than the minimum size for the HS384 or HS512 algorithms
`steps.jwt.TokenExpired`	`401`	The policy attempts to verify an expired token.
`steps.jwt.TokenNotYetValid`	`401`	The token is not yet valid.
`steps.jwt.UnhandledCriticalHeader`	`401`	A header found by the Verify JWT policy in the `crit` header is not listed in `KnownHeaders`.
`steps.jwt.UnknownException`	`401`	An unknown exception occurred.
`steps.jwt.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	Cause	Fix
`InvalidNameForAdditionalClaim`	The deployment will fail if the claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is one of the following registered names: `kid`, `iss`, `sub`, `aud`, `iat`, `exp`, `nbf`, or `jti`.
`InvalidTypeForAdditionalClaim`	If the claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is not of type `string`, `number`, `boolean`, or `map`, the deployment will fail.
`MissingNameForAdditionalClaim`	If the name of the claim is not specified in the child element `<Claim>` of the `<AdditionalClaims>` element, the deployment will fail.
`InvalidNameForAdditionalHeader`	This error ccurs when the name of the claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is either `alg` or `typ`.
`InvalidTypeForAdditionalHeader`	If the type of claim used in the child element `<Claim>` of the `<AdditionalClaims>` element is not of type `string`, `number`, `boolean`, or `map`, the deployment will fail.
`InvalidValueOfArrayAttribute`	This error occurs when the value of the array attribute in the child element `<Claim>` of the `<AdditionalClaims>` element is not set to `true` or `false`.
`InvalidConfigurationForActionAndAlgorithm`	If the `<PrivateKey>` element is used with HS Family algorithms or the `<SecretKey>` element is used with RSA Family algorithms, the deployment will fail.
`InvalidValueForElement`	If the value specified in the `<Algorithm>` element is not a supported value, the deployment will fail.
`MissingConfigurationElement`	This error will occur if the `<PrivateKey>` element is not used with RSA family algorithms or the `<SecretKey>` element is not used with HS Family algorithms.
`InvalidKeyConfiguration`	If the child element `<Value>` is not defined in the `<PrivateKey>` or `<SecretKey>` elements, the deployment will fail.
`EmptyElementForKeyConfiguration`	If the ref attribute of the child element `<Value>` of the `<PrivateKey>` or `<SecretKey>` elements is empty or unspecified, the deployment will fail.
`InvalidVariableNameForSecret`	This error occurs if the flow variable name specified in the ref attribute of the child element `<Value>` of the `<PrivateKey>` or `<SecretKey>` elements does not contain the private prefix `(private.)`.
`InvalidSecretInConfig`	This error occurs if the child element `<Value>` of the `<PrivateKey>` or `<SecretKey>` elements does not contain the private prefix `(private.)`.
`InvalidTimeFormat`	If the value specified in the`<NotBefore>` element does not use a supported format, the deployment will fail.

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
`fault.name="fault_name"`	`fault_name` 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。	`fault.name Matches "InvalidToken"`
`JWT.failed`	所有 JWT 政策在失敗的情況下都會設定相同的變數。	`JWT.failed = true`

錯誤回應範例

JWT 政策錯誤代碼

針對錯誤處理，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

錯誤規則範例

    <FaultRules>
        <FaultRule name="JWT Policy Errors">
            <Step>
                <Name>JavaScript-1</Name>
                <Condition>(fault.name Matches "InvalidToken")</Condition>
            </Step>
            <Condition>JWT.failed=true</Condition>
        </FaultRule>
    </FaultRules>

產生 JWT 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

產生已簽署的 JWT

已簽署的 JWT 範例

HS256 演算法

RS256 演算法

設定已簽署 JWT 的重要元素

產生加密的 JWT

加密 JWT 的範例

RSA-OAEP-256

A128KW

設定加密 JWT 的重要元素

產生 JWT 的元素參考資料

適用於頂層元素的屬性

<DisplayName>

<Algorithm>

<Algorithms>

<Algorithms> 的子元素

金鑰加密演算法

內容加密演算法

<Audience>

<AdditionalClaims/Claim>

<AdditionalHeaders/Claim>

<Compress>

<CriticalHeaders>

<CustomClaims>

<DirectKey>

<DirectKey> 的子元素

<ExpiresIn>

<Id>

<IgnoreUnresolvedVariables>

<Issuer>

<NotBefore>

<OutputVariable>

<PasswordKey>

<PasswordKey> 的子元素

<PrivateKey>

<PrivateKey> 的子元素

<PublicKey>

<PublicKey> 的子元素

<SecretKey>

「<SecretKey>」的子女

<Subject>

<Type>

流程變數

錯誤參考資料

Runtime errors

Deployment errors

錯誤變數

錯誤回應範例

錯誤規則範例

產生 JWT 政策

`<Algorithms>` 的子元素

`<DirectKey>` 的子元素

`<PasswordKey>` 的子元素

`<PrivateKey>` 的子元素

`<PublicKey>` 的子元素

「`<SecretKey>`」的子女