產生 JWT 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

結果

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

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

做法

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

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

影片

觀看這部短片，瞭解如何產生已簽署的 JWT。

產生已簽署的 JWT

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

已簽署 JWT 的範例

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

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

{
  "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."
}

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

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

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

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

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

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

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

<PublicKey>
  <Value ref="rsa_publickey"/>
</PublicKey>

<PublicKey>
  <Value ref="ec_publickey"/>
</PublicKey>

<SecretKey>
  <Id>optional key identifier here</Id>
  <Value ref="private.secretkey"/>
</SecretKey>

<PasswordKey>
  <Id>optional key identifier here</Id>
  <Value ref="private.passwordkey"/>
  <SaltLength>
  <PBKDF2Iterations>
</PasswordKey>

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

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

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<Algorithms>

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

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

<Algorithms> 的子元素

下表概略說明 <Algorithms> 的子元素：

金鑰加密演算法

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

請參閱「產生已加密的 JWT」一文，瞭解金鑰加密演算法為 RSA-OAEP-256 的範例，這樣您就可以使用 <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 的酬載中指定其他憑證名稱/值組合。您可以明確將聲明指定為字串、數字、布林值、地圖或陣列。地圖只是一組名稱/值組合。

<Claim> 元素的屬性如下：

• name - (必填) 聲明的名稱。
• 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 物件中的所有權杖。

<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 的標頭中。

<Claim> 元素的屬性如下：

• name - (必填) 聲明的名稱。
• 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 政策失敗。

<CustomClaims>

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

<DirectKey>

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

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

<DirectKey> 的子元素

下表概略說明 <DirectKey> 的子元素：

透過直接金鑰加密功能，您可以直接提供一系列位元組，做為內容加密金鑰 (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。

以下說明所需的鍵長度：

注意：透過 <DirectKey> 元素提供的內容加密金鑰，必須與指定的內容加密演算法完全相同長度。對於 dir 以外的任何金鑰加密演算法，政策會產生長度正確的隨機 CEK，但對於 dir，設定必須明確提供正確大小的金鑰。

<ExpiresIn>

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

or:

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

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

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

<IgnoreUnresolvedVariables>

<IgnoreUnresolvedVariables>true|false</IgnoreUnresolvedVariables>

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

<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 元素的有效時間值 (絕對時間值)

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

• 10 秒
• 60 公尺
• 12 小時

<OutputVariable>

<OutputVariable>jwt-variable</OutputVariable>

指定要放置由這項政策產生的 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> 的子元素：

<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> 的子元素：

<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> 的這些子元素：

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

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

<PublicKey>
  <JWKS uri="uri-that-returns-a-jwks"/>
  <Id ref="variable-containing-a-kid">literal-value-here</Id>
</PublicKey>

<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 元素為選用元素。在產生使用對稱 (HS*) 演算法的已簽署 JWT 或使用對稱 (AES) 演算法進行金鑰加密的加密 JWT 時，會指定要使用的密鑰。

<SecretKey> 的子項

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

<SecretKey encoding="VALUE_HERE" >
 <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>

<Subject>

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

<Subject ref="flow_variable" />

例如：

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

這項政策會產生 JWT，其中包含設定為指定值的 sub 憑證附加資訊。此憑證附加資訊會識別 JWT 的使用者主體或發出陳述式。這是 IETF RFC 7519 中提到的標準宣告集之一。

<Type>

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

說明政策會產生已簽署的 JWT 還是已加密的 JWT。<Type> 元素為選用元素。您可以使用它向讀者說明政策是產生已簽署的 JWT 還是已加密的 JWT。

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

流程變數

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

錯誤參考資料

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

執行階段錯誤

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

部署錯誤

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

錯誤變數

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

錯誤回應範例

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