產生 JWT 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

優勢

產生已簽署的 JWT，其中包含可設定的憑證附加資訊。接著，我們可以將 JWT 傳回給用戶端、傳輸至後端目標，或是以其他方式使用。詳情請參閱 JWS 和 JWT 政策總覽。

影片

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

範例

• 產生使用 HS256 演算法簽署的 JWT
• 產生使用 RS256 演算法簽署的 JWT

產生使用 HS256 演算法簽署的 JWT

這個範例政策會產生新的 JWT，並使用 HS256 演算法簽署該 JWT。HS256 需要利用共用密鑰來簽署及驗證簽名。

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

這裡的政策設定將建立 JWT，其中包含 JWT 規格定義的一組標準憑證附加資訊，包括有效期限 1 小時，以及額外的憑證附加資訊。您可以視需要加入更多版權聲明，數量不限。如要進一步瞭解這個範例政策中每個元素的相關規定和選項，請參閱元素參考資料。

<GenerateJWT name="JWT-Generate-HS256">
    <DisplayName>JWT Generate HS256</DisplayName>
    <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-edge-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-edge-JWT-policy-test",
  "aud" : "show",
  "iat" : 1506553019,
  "exp" : 1506556619,
  "jti" : "BD1FF263-3D25-4593-A685-5EC1326E1F37",
  "show": "And now for something completely different."
}

iat、exp 和 jti 憑證附加的值會有所不同。

產生使用 RS256 演算法簽署的 JWT

這個範例政策會產生一個新的 JWT，並使用 RS256 演算法簽署該 JWT。產生 RS256 簽名時，需要使用 RSA 私密金鑰，須以 PEM 編碼格式提供。如需完整範例，包括如何提出政策要求，請觀看上方的影片。

觸發這項政策動作時，Edge 會將 JWT 編碼並進行數位簽署，包括憑證附加資訊。如要瞭解 JWT 的組成部分，以及這些元件的加密與簽署方式，請參閱 RFC7519。

<GenerateJWT name="JWT-Generate-RS256">
    <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-edge-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>

設定重要元素

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

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

產生 JWT 的元素參考資料

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

注意：視您使用的加密演算法而定，設定可能略有不同。如需特定用途的設定範例，請參閱範例。

套用至頂層元素的屬性

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

以下是所有政策父項元素的通用屬性。

<DisplayName>

<DisplayName>Policy Display Name</DisplayName>

除了名稱屬性，您還可以使用其他自然語言名稱，在管理 UI Proxy 編輯器中為政策加上標籤。

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

<Audience>

<Audience>audience-here</Audience>

or:

<Audience ref='variable_containing_audience'/>

政策會產生 JWT，其中含有設為指定值的 aud 憑證附加資訊。這項憑證可用來識別 JWT 適用對象的接收者。這是 RFC7519 中所述的其中一項註冊憑證附加資訊。

<其他聲明/版權聲明>

<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 - (選用) 其中之一：字串 (預設值)、數字、布林值或地圖
• 陣列 - (選用) 設為 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 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 - (選用) 其中之一：字串 (預設值)、數字、布林值或地圖
• 陣列 - (選用) 設為 true，表示該值是類型陣列。預設值：false。

<CriticalHeaders>

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

or:

<CriticalHeaders ref=’variable_containing_headers’/>

將重要標頭「條件」加入 JWT 標頭中。crit 標頭是一個標頭名稱陣列，必須可供 JWT 接收器識別及辨識。例如：

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

在執行階段，VerifyJWT 政策會檢查 crit 標頭。 針對 crit 標頭中列出的每個項目，系統會檢查 VerifyJWT 政策的 <KnownHeaders> 元素是否也會列出該標頭。凡是在 條件中未列於 <KnownHeaders> 中的標頭，皆會導致 VerifyJWT 政策失敗。

<CustomClaims>

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

<ExpiresIn>

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

以毫秒、秒、分鐘、小時或天為單位指定 JWT 的生命週期。

<編號>

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

<PrivateKey/Id>

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

or

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

指定要納入 JWT 標頭的金鑰 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 的演算法。

<PrivateKey/Value>

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

指定用來簽署 JWT 的 PEM 編碼私密金鑰。使用 ref 屬性在流程變數中傳遞鍵。僅適用於演算法為 RS256/RS384/RS512、PS256/PS384/PS512 或 ES256/ES384/ES512 的演算法。

<密鑰/ID>

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

or

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

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

<SecretKey/Value>

<SecretKey>
  <Value ref="private.your-variable-name"/>
</SecretKey>

提供透過 HMAC 演算法驗證或簽署權杖的密鑰。只有在演算法為 HS256/HS384/HS512 時才使用。使用 ref 屬性在流程變數中傳遞鍵。

邊緣會強制執行 HS256/HS384/HS512 演算法的最低按鍵強度。HS256 的索引鍵長度下限為 32 個位元組，HS384 的索引鍵長度下限為 48 個位元組，HS512 版則是 64 個位元組。使用強度較低的金鑰會導致執行階段錯誤。

<Subject>

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

<Subject ref="flow_variable" />

例如：

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

政策會產生一個 JWT 含有設為指定值的「sub」憑證附加資訊。這項聲明會識別或做出 JWT 主體的陳述。這是 RFC7519 中提及的標準憑證附加資訊組合之一。

流程變數

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

錯誤參考資料

本節說明當這項政策觸發錯誤時，傳回的錯誤代碼和錯誤訊息，以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤，請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

執行階段錯誤

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

部署錯誤

若您部署包含這項政策的 Proxy，就可能會發生這些錯誤。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

錯誤回應範例

如要處理錯誤，最佳做法是納入錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為文字可能會有所變動。

故障規則示例

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