查看 Apigee Edge 說明文件。
前往
Apigee X說明文件。 資訊
結果
產生已簽署的 JWT,其中含有一組可設定的憑證附加資訊。接著即可將 JWT 傳回給 傳送至後端目標,或以其他方式使用。 如需詳細的介紹,請參閱 JWS 和 JWT 政策總覽。
影片
請觀看短片,瞭解如何產生已簽署的 JWT。
範例
產生以 HS256 簽署的 JWT 演算法
這個範例政策會產生新的 JWT 並使用 HS256 演算法簽署。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 演算法簽署。產生 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 的金鑰取決於所選的演算法、 如下表所示:
演算法 | 主要元素 | |
---|---|---|
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>
|
|
*如要進一步瞭解重要規定,請參閱 關於簽名加密演算法。 |
產生 JWT 的元素參照
政策參考資料說明 JWT 政策的元素和屬性。
注意:設定可能會因加密方式而有些許不同 演算法。請參閱「範例」中的使用範例 特定用途的配置設定
具備的屬性 套用至頂層元素
<GenerateJWT name="JWT" continueOnError="false" enabled="true" async="false">
下列屬性適用於所有政策父項元素。
屬性 | 說明 | 預設 | 外觀狀態 |
---|---|---|---|
名稱 |
政策的內部名稱。名稱中可使用的字元僅限於:
A-Z0-9._\-$ % 。不過,邊緣管理 UI 會強制執行額外的
限制 (例如自動移除非英數字元的字元)。
視需要使用 |
不適用 | 必填 |
continueOnError |
如果設為「false 」,系統會在政策失敗時傳回錯誤。這是可預期的情況
大多數政策的行為
如果設為 |
false | 選用 |
已啟用 |
如要強制執行政策,請設為 true 。
將 |
true | 選用 |
非同步 | 此屬性已淘汰。 | false | 已淘汰 |
<DisplayName>
<DisplayName>Policy Display Name</DisplayName>
除了名稱屬性以外,還能在管理 UI Proxy 編輯器中為政策加上標籤 使用不同的自然語言名稱
預設 | 如果省略這個元素,則會使用政策的名稱屬性值。 |
外觀狀態 | 選用 |
類型 | 字串 |
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
指定用來簽署權杖的加密演算法。
預設 | 不適用 |
外觀狀態 | 必填 |
類型 | 字串 |
有效值 | HS256、HS384、HS512、RS256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 |
<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 - (選用) 下列其中一個:字串 (預設)、數字、布林值或地圖
- 陣列 - (選用) 設為 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 - (選用) 下列其中一個:字串 (預設)、數字、布林值或地圖
- 陣列 - (選用) 設為 true,表示值是否為類型的陣列。預設: false。
<CriticalHeaders>
<CriticalHeaders>a,b,c</CriticalHeaders> or: <CriticalHeaders ref=’variable_containing_headers’/>
將重要標頭 crit 新增至 JWT 標頭。crit 標頭 是標頭名稱陣列,JWT 接收器必須知道且可辨識其名稱。例如:
{ “typ: “...”, “alg” : “...”, “crit” : [ “a”, “b”, “c” ], }
在執行階段,VerifyJWT 政策會檢查 crit 標頭。
針對 crit 標頭列出的每個項目,它會檢查 <KnownHeaders>
元素
VerifyJWT 政策的標頭也會列出該標頭。VerifyJWT 政策可在 crit 中找到的任何標頭
沒有列在 <KnownHeaders>
中,會導致 VerifyJWT 政策失敗。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 以半形逗號分隔的字串陣列 |
有效值 | 陣列或包含陣列的變數名稱。 |
<CustomClaims>
注意:目前當您新增自訂聲明元素時,系統會插入 CustomClaims 元素 透過 UI 產生 JWT 政策。此元素無法運作,因此將遭到忽略。正確 改為使用 <AdditionalClaims>。UI 會 ,以便稍後再插入正確的元素。
<ExpiresIn>
<ExpiresIn>time-value-here</ExpiresIn>
以毫秒、秒、分鐘、小時或天為單位指定 JWT 的效期。
預設 | N/A |
外觀狀態 | 選用 |
類型 | 整數 |
有效值 |
包含值的資料值或資料流變數的參照。時間單位可以是 可以指定如下:
舉例來說, |
<Id>
<Id>explicit-jti-value-here</Id> -or- <Id ref='variable-name-here'/> -or- <Id/>
產生含有特定 jti 憑證附加資訊的 JWT。如果同時有文字值和 ref 屬性 空白,這項政策會產生包含隨機 UUID 的 jti。JWT ID (jti) 憑證附加資訊 不重複識別碼。如要進一步瞭解 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 的值。可識別 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 |
2017 年 8 月 14 日星期一 11:00:21 (太平洋夏令時間) |
RFC 850 | EEEE, dd-MMM-yy HH:mm:ss zzz |
14 月 14 日至 8 月 17 日,星期一 11:00:21 (太平洋夏令時間) |
ANCI-C | EEE MMM d HH:mm:ss yyyy |
2017 年 8 月 14 日星期一 11:00:21 |
若是相對時間值,請指定整數和時間範圍,例如:
- 10 秒
- 60 分鐘
- 12 小時
<OutputVariable>
<OutputVariable>jwt-variable</OutputVariable>
指定這項政策產生的 JWT 的位置。預設會放置於
資料流變數 jwt.POLICYNAME.generated_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 之一時。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 |
流程變數參照。
注意:您必須指定流程變數。邊緣將拒絕為無效的
政策設定 (以明文指定密碼)。流程變數
都必須包含「private」前置字串。例如: |
<PrivateKey/Value>
<PrivateKey> <Value ref="private.variable-name-here"/> </PrivateKey>
指定用於簽署 JWT 的 PEM 編碼私密金鑰。請使用 ref 屬性將 流程變數中的鍵。只有在演算法為 RS256/RS384/RS512 時才使用, PS256/PS384/PS512 或 ES256/ES384/ES512。
預設 | 不適用 |
外觀狀態 | 必須執行此操作,才能使用 RS256 演算法產生 JWT。 |
類型 | 字串 |
有效值 |
包含代表 PEM 編碼 RSA 私密金鑰值的字串流程變數。
注意:流量變數的前置字串須為「private」。例如:
|
<SecretKey/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 屬性 以流程變數的形式傳遞金鑰
Edge 會強制 HS256/HS384/HS512 演算法達到最低金鑰強度。金鑰長度下限 HS256 為 32 個位元組,HS384 為 48 個位元組,HS512 則為 64 個位元組。 使用強度較低的金鑰會導致執行階段錯誤。
預設 | 不適用 |
外觀狀態 | HMAC 演算法的必要欄位。 |
類型 | 字串 |
有效值 |
參照字串的流量變數
注意:如果資料流變數,其前置字串必須為「private」。適用對象
例如: |
<Subject>
<Subject>subject-string-here</Subject>或
<Subject ref="flow_variable" />
例如:
<Subject ref="apigee.developer.email"/>
這項政策產生含有指定 sub 憑證附加資訊的 JWT value。此聲明用於識別或發表 JWT 主體。這是 RFC7519 中提及的標準聲明組合。
預設 | 不適用 |
外觀狀態 | 選用 |
類型 | 字串 |
有效值 | 可明確識別主旨或參照值的流程變數的任何值。 |
流程變數
「Generate JWT」政策不會設定流程變數。
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 發生時機 |
---|---|---|
steps.jwt.AlgorithmInTokenNotPresentInConfiguration |
401 | 驗證政策採用多個演算法時發生。 |
steps.jwt.AlgorithmMismatch |
401 | 產生政策中指定的演算法與驗證政策中預期的演算法不符。指定的演算法必須相符。 |
steps.jwt.FailedToDecode |
401 | 政策無法解碼 JWT。JWT 可能損毀。 |
steps.jwt.GenerationFailed |
401 | 政策無法產生 JWT。 |
steps.jwt.InsufficientKeyLength |
401 | 如果金鑰在 HS256 演算法中的資料量小於 32 個位元組,HS386 演算法需少於 48 個位元組,HS512 演算法則小於 64 個位元組。 |
steps.jwt.InvalidClaim |
401 | 可能是因為缺少版權聲明或版權聲明不符,或是缺少標題或標頭不符的情形。 |
steps.jwt.InvalidCurve |
401 | 索引鍵指定的曲線不適用於橢圓曲線演算法。 |
steps.jwt.InvalidJsonFormat |
401 | 標頭或酬載含有無效的 JSON。 |
steps.jwt.InvalidToken |
401 | 如果 JWT 簽名驗證失敗,就會發生這個錯誤。 |
steps.jwt.JwtAudienceMismatch |
401 | 權杖驗證失敗,目標對象聲明失敗。 |
steps.jwt.JwtIssuerMismatch |
401 | 核發機構憑證驗證失敗。 |
steps.jwt.JwtSubjectMismatch |
401 | 驗證權杖的主體擁有權聲明失敗。 |
steps.jwt.KeyIdMissing |
401 | 驗證政策會使用 JWKS 做為公開金鑰來源,但已簽署的 JWT 不會在標頭中加入 kid 屬性。 |
steps.jwt.KeyParsingFailed |
401 | 無法從指定的金鑰資訊剖析公開金鑰。 |
steps.jwt.NoAlgorithmFoundInHeader |
401 | 發生於 JWT 未包含演算法標頭時。 |
steps.jwt.NoMatchingPublicKey |
401 | 驗證政策會使用 JWKS 做為公開金鑰來源,但已簽署 JWT 中的 kid 並未列在 JWKS 中。 |
steps.jwt.SigningFailed |
401 | 在 GenerateJWT 中,金鑰大小必須小於 HS384 或 HS512 演算法的下限 |
steps.jwt.TokenExpired |
401 | 政策會嘗試驗證過期的權杖。 |
steps.jwt.TokenNotYetValid |
401 | 憑證尚未生效。 |
steps.jwt.UnhandledCriticalHeader |
401 | 在 crit 標頭中驗證 JWT 政策找到的標頭不在 KnownHeaders 中。 |
steps.jwt.UnknownException |
401 | 發生不明例外狀況。 |
steps.jwt.WrongKeyType |
401 | 指定的金鑰類型有誤。舉例來說,如果您為橢圓曲線演算法指定 RSA 金鑰,或是為 RSA 演算法指定曲線鍵, |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 | 修正 |
---|---|---|
InvalidNameForAdditionalClaim |
如果 <AdditionalClaims> 元素的子元素 <Claim> 中使用的憑證聲明是下列任一註冊名稱,部署作業就會失敗:kid 、iss 、sub 、aud 、iat 、exp 、nbf 或 jti 。 |
build |
InvalidTypeForAdditionalClaim |
如果 <AdditionalClaims> 元素子項元素 <Claim> 中使用的憑證聲明不是 string 、number 、boolean 或 map 類型,部署作業就會失敗。
|
build |
MissingNameForAdditionalClaim |
如未在 <AdditionalClaims> 元素的子元素 <Claim> 中指定憑證附加資訊,部署作業就會失敗。
|
build |
InvalidNameForAdditionalHeader |
當 <AdditionalClaims> 元素的子元素 <Claim> 使用的聲明名稱是 alg 或 typ 時,就會發生這個錯誤。 |
build |
InvalidTypeForAdditionalHeader |
如果 <AdditionalClaims> 元素子項元素 <Claim> 中使用的聲明類型不是 string 、number 、boolean 或 map ,部署就會失敗。 |
build |
InvalidValueOfArrayAttribute |
如果 <AdditionalClaims> 元素中子元素 <Claim> 的陣列屬性值未設為 true 或 false ,就會發生這個錯誤。 |
build |
InvalidConfigurationForActionAndAlgorithm |
如果將 <PrivateKey> 元素與 HS 系列演算法搭配使用,或是將 <SecretKey> 元素與 RSA Family 演算法搭配使用,部署作業就會失敗。 |
build |
InvalidValueForElement |
如果 <Algorithm> 元素中指定的值不是支援的值,部署作業就會失敗。
|
build |
MissingConfigurationElement |
如果 <PrivateKey> 元素未與 RSA 系列演算法搭配使用,或是 <SecretKey> 元素並未與 HS 系列演算法搭配使用,就會發生這個錯誤。 |
build |
InvalidKeyConfiguration |
如果未在 <PrivateKey> 或 <SecretKey> 元素中定義子項元素 <Value> ,部署就會失敗。 |
build |
EmptyElementForKeyConfiguration |
如果 <PrivateKey> 或 <SecretKey> 元素子項元素 <Value> 的 ref 屬性為空白或未指定,則部署作業將會失敗。 |
build |
InvalidVariableNameForSecret |
如果在 <PrivateKey> 或 <SecretKey> 元素的子項元素 <Value> 的 ref 屬性中指定的流程變數名稱不含私人前置字串 (private.) ,就會發生這個錯誤。 |
build |
InvalidSecretInConfig |
如果 <PrivateKey> 或 <SecretKey> 元素的子元素 <Value> 不含私人前置字串 (private.) ,就會發生這個錯誤。 |
build |
InvalidTimeFormat |
如果 <NotBefore> 元素中指定的值未使用支援的格式,部署就會失敗。
|
build |
錯誤變數
系統會在發生執行階段錯誤時設定這些變數。詳情請參閱重要須知 政策錯誤。
變數 | 地點 | 範例 |
---|---|---|
fault.name="fault_name" |
fault_name 是錯誤的名稱,如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤程式碼的最後部分。 | fault.name Matches "TokenExpired" |
JWT.failed |
如果失敗時,所有 JWT 政策都會設定相同的變數。 | JWT.failed = true |
錯誤回應範例
針對錯誤處理,最佳做法是將錯誤的 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>