您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
OAuthV2 是在執行 OAuth 2.0 授權類型作業的多面向政策。這是用來在 Apigee Edge 上設定 OAuth 2.0 端點的主要政策。
提示:如要進一步瞭解 Apigee Edge 的 OAuth,請參閱 OAuth 首頁。提供資源、範例、影片和其他內容的連結。請參閱 GitHub 上的進階 OAuth 範例,清楚示範如何在可正常運作的應用程式中使用這項政策。
範例
VerifyAccessToken
VerifyAccessToken
這項 OAuthV2 政策設定 (包含 VerifyAccessToken 作業) 會驗證提交至 Apigee Edge 的存取權杖是否有效。觸發這項政策作業時,Edge 會在要求中尋找有效的存取權杖。如果存取權杖有效,要求就能繼續進行。如果無效,所有處理作業都會停止,回應中也會傳回錯誤。
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2"> <DisplayName>OAuth v2.0 2</DisplayName> <Operation>VerifyAccessToken</Operation> <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer --> </OAuthV2>
注意:僅支援 OAuth 2.0 不記名權杖。不支援訊息驗證碼 (MAC) 權杖。
例如:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
根據預設,Edge 會接受 Authorization
標頭中含有 Bearer
前置字串的存取權杖。您可以透過 <AccessToken>
元素變更這項預設值。
GenerateAccessToken
產生存取權杖
如需如何為各個支援的授權類型要求存取權杖的範例,請參閱要求存取權杖和授權碼。本主題包含下列作業的範例:
GenerateAuthorizationCode
產生授權碼
如需索取授權碼的範例,請參閱要求授權碼。
RefreshAccessToken
重新整理存取權杖
如需使用更新權杖要求存取權杖的範例,請參閱重新整理存取權杖。
回應流程權杖
在回應流程中產生存取權杖
您有時可能需要在回應流程中產生存取權杖。舉例來說,如要回應您在後端服務中完成的部分自訂驗證,您就可以這麼做。在此範例中,用途需要存取權杖和更新權杖,才能執行隱含授權類型。在這種情況下,我們會使用密碼授權類型來產生權杖。如您所見,要執行這項作業的秘訣就是傳入含有 JavaScript 政策的「授權要求」標頭。
首先,讓我們看範例政策:
<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken"> <Operation>GenerateAccessToken</Operation> <AppEndUser>Doe</AppEndUser> <UserName>jdoe</UserName> <PassWord>jdoe</PassWord> <GrantType>grant_type</GrantType> <ClientId>a_valid_client_id</ClientId> <SupportedGrantTypes> <GrantType>password</GrantType> </SupportedGrantTypes> </OAuthV2>
如果您在回應流程中加入這項政策,即使政策中指定正確的登入參數,這項政策仍會失敗並顯示 401 UnAuthorized 錯誤。如要解決這個問題,您必須設定授權要求標頭。
授權標頭必須包含採用 Base64 編碼的 client_id:client_secret。
透過將 JavaScript 政策放在 OAuthV2 政策之前,您就能新增這個標頭,就像這樣。「local_clientid」和「local_secret」變數必須先前已設定,並於流程中使用:
var client_id = context.getVariable("local_clientid"); var client_secret = context.getVariable("local_secret"); context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1 .parse(client_id + ':' + client_secret)));
另請參閱「編碼基本驗證憑證」一文。
元素參考資料
政策參考資料說明 OAuthV2 政策的元素和屬性。
下方顯示的範例政策是眾多可能的設定選項之一。這個範例顯示的是 GenerateAccessToken 作業設定的 OAuthV2 政策。當中包含必要和選用元素。詳情請參閱本節中的元素說明。
<OAuthV2 name="GenerateAccessToken"> <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type --> <Operation>GenerateAccessToken</Operation> <!-- This is in millseconds, so expire in an hour --> <ExpiresIn>3600000</ExpiresIn> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GrantType>request.queryparam.grant_type</GrantType> <GenerateResponse/> </OAuthV2>
<OAuthV2> 屬性
<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">
下表說明所有政策父項元素的通用屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<AccessToken> 元素
<AccessToken>request.header.access_token</AccessToken>
根據預設,VerifyAccessToken 預期存取權杖是以 Authorization
標頭傳送。
您可以使用這個元素變更預設值。舉例來說,request.queryparam.access_token
表示存取權杖應以名為 access_token
的查詢參數形式呈現。
<AccessToken>request.header.access_token</AccessToken>
的範例:
curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"指定
<AccessToken>request.queryparam.access_token</AccessToken>
的範例:
curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"
預設: |
不適用 |
所在地: |
選用 |
類型: | 字串 |
用於操作: |
|
<AccessTokenPrefix> 元素
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
根據預設,VerifyAccessToken 預期將存取權杖以「授權」標頭中做為不記名權杖傳送。例如:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
目前只支援 Bearer 這個前置字元。
預設: |
承載系統 |
所在地: |
選用 |
類型: | 字串 |
有效值: |
承載系統 |
用於操作: |
|
<AppEndUser> 元素
<AppEndUser>request.queryparam.app_enduser</AppEndUser>
如果必須將應用程式使用者 ID 傳送至授權伺服器,這個元素可讓您指定 Edge 尋找使用者 ID 的位置。舉例來說,該呼叫能以查詢參數或 HTTP 標頭的形式傳送。
舉例來說,request.queryparam.app_enduser
表示 AppEndUser 應存在查詢參數,例如 ?app_enduser=ntesla@theramin.com
。例如,如果您需要在 HTTP 標頭中要求 AppEndUser,請將此值設為 request.header.app_enduser
。
啟用這項設定後,您就能在存取權杖中加入應用程式使用者 ID。如果您想能夠依據使用者 ID 擷取或撤銷 OAuth 2.0 存取權杖,這項功能就能派上用場。詳情請參閱「 依使用者 ID、應用程式 ID 或同時啟用及撤銷 OAuth 2.0 存取權杖的擷取及撤銷功能」。
預設: |
不適用 |
所在地: |
選用 |
類型: | 字串 |
有效值: |
可在執行階段存取政策的任何流程變數。 |
搭配授權類型使用: |
|
<屬性/屬性>
<Attributes> <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute> <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute> </Attributes>
使用這個元素將自訂屬性新增至存取權杖或授權碼。舉例來說,您可能想在執行階段擷取和檢查存取權杖,嵌入使用者 ID 或工作階段 ID。
這個元素可以讓您在流程變數或常值字串中指定值。如果您同時指定變數和字串,系統會使用流程變數中指定的值。如果無法解析變數,則字串為預設值。
如要進一步瞭解如何使用這個元素,請參閱「自訂權杖和授權碼」。
在回應中顯示或隱藏自訂屬性
請注意,如果您將這項政策的 GenerateResponse 元素設為 true,回應中就會傳回符記的完整 JSON 表示法,包括您設定的任何自訂屬性。在某些情況下,您可能想要隱藏回應中的部分或所有自訂屬性,導致用戶端應用程式看不到這些屬性。
根據預設,自訂屬性會顯示在回應中。如要隱藏,您可以將 display 參數設為 false。例如:
<Attributes> <Attribute name="employee_id" ref="employee.id" display="false"/> <Attribute name="employee_name" ref="employee.name" display="false"/> </Attributes>
display
屬性的值不會保留。假設您產生了含有自訂屬性的存取權杖,您希望在產生的回應中隱藏該屬性。設定 display=false
即可達成該目標。不過,如果之後使用更新權杖產生新的存取權杖,則存取權杖的原始自訂屬性會顯示在更新權杖回應中。這是因為 Edge 不記得在產生存取權杖政策中,display
屬性原先設為 false
,而自訂屬性只是存取權杖中繼資料的一部分。
同樣的,如果您在授權碼中加入自訂屬性,也會遇到相同的行為:使用這組代碼產生的存取權杖時,這些自訂屬性會顯示在存取權杖回應中。再次提醒您,這可能不是您想要的行為。
在這種情況下,您可以透過下列選項隱藏自訂屬性:
- 在更新權杖政策中明確重設自訂屬性,並將其顯示設定為 false。在這種情況下,您可能需要使用 GetOAuthV2Info 政策,從原始存取權杖擷取原始自訂值。
- 請使用後續處理 JavaScript 政策,手動擷取不想在回應中看到的自訂屬性。
另請參閱自訂權杖與授權碼。
預設: |
|
所在地: |
選用 |
有效值: |
|
搭配授權類型使用: |
|
<ClientId> 元素
<ClientId>request.formparam.client_id</ClientId>
在某些情況下,用戶端應用程式必須將用戶端 ID 傳送至授權伺服器。這個元素可讓您指定 Edge 尋找用戶端 ID 的位置。唯一可以設定的有效位置是預設位置,也就是資料流變數 request.formparam.client_id
。系統不支援將 ClientId
設為任何其他變數。另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.client_id (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 流程變數:request.formparam.client_id |
搭配授權類型使用: |
也可以與 GenerateAuthorizationCode 作業搭配使用。 |
<Code> 元素
<Code>request.queryparam.code</Code>
在授權類型流程中,用戶端必須將授權碼提交至授權伺服器 (Apigee Edge)。這個元素可讓您指定 Edge 尋找授權碼的位置。舉例來說,資料可以做為查詢參數、HTTP 標頭或表單參數 (預設) 傳送。
變數 request.queryparam.auth_code
表示授權碼應以查詢參數的形式呈現,例如 ?auth_code=AfGlvs9
。如要要求 HTTP 標頭中的授權碼,請將這個值設為 request.header.auth_code
。另請參閱「要求存取權杖和授權碼」。
預設: |
request.formparam.code (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選填 |
類型: | 字串 |
有效值: | 可在執行階段存取政策的任何流程變數 |
搭配授權類型使用: | authorization_code |
<ExpirationIn> 元素
<ExpiresIn>10000</ExpiresIn>
強制要求存取權杖和授權碼的到期時間 (以毫秒為單位)。(如需更新權杖,請使用 <RefreshTokenExpiresIn>
)。到期時間值是系統產生的值加上 <ExpiresIn>
值。如果將 <ExpiresIn>
設為 -1,權杖或代碼就會根據OAuth 存取權杖到期時間上限到期。如未指定 <ExpiresIn>
,系統會套用在系統層級設定的預設值。
您也可以在執行階段使用硬式編碼、預設值或參照流程變數來設定到期時間。例如,您可以將權杖效期值儲存在鍵/值對應中、擷取該值、指派給變數,以及在政策中參照。例如:kvm.oauth.expires_in
。
有了 Apigee Edge for Public Cloud,Edge 能在存取實體後,將下列實體保留在快取中至少 180 秒。
- OAuth 存取權杖。這表示撤銷的權杖可能仍有最多三分鐘的成功,直到快取限製到期為止。
- Key Management Service (KMS) 實體 (應用程式、開發人員、API 產品)。
- OAuth 權杖和 KMS 實體的自訂屬性。
下列段落也會指定流程變數和預設值。請注意,資料流變數值的優先順序高於指定預設值。
<ExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </ExpiresIn>
Edge 不支援在權杖建立後強制過期的方法。如果您需要強制權杖過期 (例如根據條件),請參閱 這篇 Apigee 社群貼文,瞭解可能的解決方案。
根據預設,過期的存取權杖會在到期後 3 天自動從 Apigee Edge 系統清除。另請參閱「清除存取權杖」一文。
Private Cloud:如為 Edge for Private Cloud 安裝作業,預設值為 conf_keymanagement_oauth_auth_code_expiry_time_in_millis
屬性。如要設定這項屬性,請按照下列指示操作:
- 在編輯器中開啟
message-processor.properties
檔案。如果檔案不存在,請建立檔案:vi /opt/apigee/customer/application/message-processor.properties
- 視需要設定屬性:
conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
- 確認屬性檔案為「apigee」使用者擁有:
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- 重新啟動訊息處理器。
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
預設: |
如未指定,系統會套用在系統層級設定的預設值。 |
所在地: |
選用 |
類型: | 整數 |
有效值: |
|
搭配授權類型使用: |
也適用於 GenerateAuthorizationCode 作業。 |
<ExternalAccessToken> 元素
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
告知 Apigee Edge 可在哪裡找到外部存取權杖 (API Edge 不產生存取權杖)。
變數 request.queryparam.external_access_token
表示外部存取權杖應以查詢參數的形式呈現,例如 ?external_access_token=12345678
。如需 HTTP 標頭中的外部存取權杖,例如將這個值設為 request.header.external_access_token
即可。另請參閱使用第三方 OAuth 權杖。
<ExternalAuthorization> 元素
<ExternalAuthorization>true</ExternalAuthorization>
如果這個元素為 false 或不存在,Edge 會對照 Apigee Edge 授權存放區正常驗證 client_id 和 client_secret。當您要使用第三方 OAuth 權杖時,請使用這個元素。如要進一步瞭解如何使用這個元素,請參閱「使用第三方 OAuth 權杖」。
預設: |
false |
所在地: |
選用 |
類型: | 布林值 |
有效值: | true 或 false |
搭配授權類型使用: |
|
<ExternalAuthorizationCode> 元素
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
告知 Apigee Edge 可在哪裡找到外部驗證碼 (Apigee Edge 未產生的驗證碼)。
變數 request.queryparam.external_auth_code
表示外部驗證碼應以查詢參數的形式呈現,例如 ?external_auth_code=12345678
。如需 HTTP 標頭中的外部驗證碼,請將這個值設為 request.header.external_auth_code
。另請參閱使用第三方 OAuth 權杖。
<ExternalRefreshToken> 元素
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
告知 Apigee Edge 可在何處找到外部更新權杖 (API Edge 未產生的更新權杖)。
變數 request.queryparam.external_refresh_token
表示外部更新權杖應以查詢參數的形式呈現,例如 ?external_refresh_token=12345678
。如需 HTTP 標頭中的外部更新權杖,例如,請將此值設為 request.header.external_refresh_token
。另請參閱使用第三方 OAuth 權杖。
<GenerateResponse> 元素
<GenerateResponse enabled='true'/>
如果設為 true
,政策會產生並傳回回應。例如,針對 GenerateAccessToken,回應可能如下所示:
{ "issued_at" : "1467841035013", "scope" : "read", "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930", "refresh_token_issued_at" : "1467841035013", "status" : "approved", "refresh_token_status" : "approved", "api_product_list" : "[Product1, nhl_product]", "expires_in" : "1799", "developer.email" : "edward@slalom.org", "token_type" : "BearerToken", "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ", "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj", "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a", "organization_name" : "cerruti", "refresh_token_expires_in" : "0", "refresh_count" : "0" }
如果為 false
,則不會傳送任何回應。而是將一組流程變數填入與政策函式相關的值。例如,名為 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
的資料流變數會填入新挖掘的驗證碼。請注意,expires_in 會在回應中以秒為單位表示。
預設: |
false |
所在地: |
選用 |
類型: | 字串 |
有效值: | true 或 false |
搭配授權類型使用: |
|
<GenerateErrorResponse> 元素
<GenerateErrorResponse enabled='true'/>
如果設為 true
,當 ContinueOnError 屬性設為 true 時,政策會產生並傳回回應。如果 false
(預設值),系統不會傳送任何回應。而是將一組流程變數填入與政策函式相關的值。
預設: |
false |
所在地: |
選用 |
類型: | 字串 |
有效值: | true 或 false |
搭配授權類型使用: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
向政策說明可在哪裡找到要求中傳遞的授權類型參數。根據 OAuth 2.0 規格,必須透過要求存取權杖和授權碼的要求提供授權類型。變數可以是標頭、查詢參數或表單參數 (預設)。
舉例來說,request.queryparam.grant_type
表示密碼應以查詢參數的形式呈現,例如 ?grant_type=password
。如需 HTTP 標頭中的授權類型,例如,請將這個值設為 request.header.grant_type
。另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.grant_type (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 變數,如上所述。 |
搭配授權類型使用: |
|
<Operation> 元素
<Operation>GenerateAuthorizationCode</Operation>
政策執行的 OAuth 2.0 作業。
預設: |
如未指定 |
所在地: |
選用 |
類型: | 字串 |
有效值: |
|
<PassWord> 元素
<PassWord>request.queryparam.password</PassWord>
這個元素僅適用於 密碼授權類型。採用密碼授權類型時,必須開放 OAuthV2 政策的使用者憑證 (密碼與使用者名稱)。<PassWord>
和 <UserName>
元素是用來指定 Edge 可在哪些變數找到這些值。如未指定這些元素,政策預設會尋找格式為 username
和 password
的表單參數中的值。如果找不到這些值,政策會擲回錯誤。您可以使用 <PassWord>
和 <UserName>
元素,參照包含憑證的任何流程變數。
舉例來說,您可以使用查詢參數在權杖要求中傳遞密碼,並設定如下元素:<PassWord>request.queryparam.password</PassWord>
.
如果想在 HTTP 標頭中要求密碼,請將這個值設為 request.header.password
。
OAuthV2 政策並未對這些憑證值執行任何操作;Edge 只是確認憑證是否存在。API 開發人員會在權杖產生政策執行前,擷取值要求並傳送至識別資訊提供者。
另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.password (一個 x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 可在執行階段使用任何政策流程變數。 |
搭配授權類型使用: | 密碼 |
<RedirectUri> 元素
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
指定 Edge 在要求中尋找 redirect_uri
參數的位置。
關於重新導向 URI
重新導向 URI 會與授權碼和隱含授權類型搭配使用。重新導向 URI 會告知授權伺服器 (Edge) 要在哪裡傳送授權碼 (適用於驗證碼授權類型) 或存取權杖 (適用於隱含授權類型)。請務必瞭解必要參數的時機、選用參數,以及參數的使用方式:
-
(必要) 如果開發人員應用程式註冊的回呼網址與要求的用戶端金鑰相關聯,且要求中包含
redirect_uri
,則兩者必須完全相符。如果兩者不相符,系統會傳回錯誤。如要瞭解如何在 Edge 上註冊開發人員應用程式,以及如何指定回呼網址,請參閱「註冊應用程式及管理 API 金鑰」一文。 - (選用) 如果已註冊回呼網址,且要求中缺少
redirect_uri
,則 Edge 會重新導向至已註冊的回呼網址。 - (必要) 如未註冊回呼網址,則必須使用
redirect_uri
。請注意,在本範例中,Edge 會接受 ANY 網址。這可能會產生安全性問題, 因此只應與信任的用戶端應用程式搭配使用。如果用戶端應用程式不受信任,最佳做法就是一律要求註冊回呼網址。
您可以在查詢參數或標頭中傳送此參數。變數 request.queryparam.redirect_uri
表示 RedirectUri 應顯示為查詢參數,例如 ?redirect_uri=login.myapp.com
。例如,如要在 HTTP 標頭中要求 RedirectUri,請將這個值設為 request.header.redirect_uri
。另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.redirect_uri (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 在執行階段存取政策中的任何流程變數 |
搭配授權類型使用: |
此函式也適用於 GenerateAuthorizationCode 作業。 |
<RefreshToken> 元素
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
使用更新權杖要求存取權杖時,您必須在要求中提供更新權杖。這個元素可讓您指定 Edge 要在哪裡尋找更新權杖。舉例來說,可以做為查詢參數、HTTP 標頭或表單參數 (預設) 傳送。
變數 request.queryparam.refreshtoken
表示更新權杖應以查詢參數的形式呈現,例如 ?refresh_token=login.myapp.com
。如要要求 HTTP 標頭中的 RefreshToken,例如將這個值設為 request.header.refresh_token
,另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.refresh_token (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 在執行階段存取政策中的任何流程變數 |
搭配授權類型使用: |
|
<RefreshTokenExpirationIn> 元素
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
強制執行更新權杖的到期時間 (以毫秒為單位)。到期時間值是系統產生的值加上 <RefreshTokenExpiresIn>
值。如果將 <RefreshTokenExpiresIn>
設為 -1,更新權杖就會根據OAuth 更新權杖到期時間上限到期。如未指定 <RefreshTokenExpiresIn>
,則預設到期時間為無限期。
您也可以在執行階段使用硬式編碼、預設值或參照流程變數來設定到期時間。例如,您可以將權杖效期值儲存在鍵/值對應中、擷取該值、指派給變數,以及在政策中參照。例如:kvm.oauth.expires_in
。
下列段落也會指定流程變數和預設值。請注意,資料流變數值優先於指定預設值。
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </RefreshTokenExpiresIn>
Private Cloud:如為 Edge for Private Cloud 安裝作業,預設值為 conf_keymanagement_oauth_refresh_token_expiry_time_in_millis
屬性。如要設定這項屬性,請按照下列指示操作:
- 在編輯器中開啟
message-processor.properties
檔案。如果檔案不存在,請建立檔案:vi /opt/apigee/customer/application/message-processor.properties
- 視需要設定屬性:
conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
- 確認屬性檔案為「apigee」使用者擁有:
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- 重新啟動訊息處理器。
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
預設: |
如未指定,系統會套用在系統層級設定的預設值。 |
所在地: |
選用 |
類型: | 整數 |
有效值: |
|
搭配授權類型使用: |
|
"refresh_token_expires_in" : "0"
。<ResponseType> 元素
<ResponseType>request.queryparam.response_type</ResponseType>
這個元素會告知 Edge,這會授予用戶端應用程式要求的類型。這個函式只能搭配授權碼和隱含授權類型流程使用。
根據預設,Edge 會在 response_type
查詢參數中尋找回應類型值。如要覆寫這個預設行為,請使用 <ResponseType> 元素設定包含回應類型值的流程變數。舉例來說,如果您將此元素設為 request.header.response_type
,Edge 會尋找要在要求標頭中傳遞的回應類型。另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.response_type (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用設定。如要覆寫預設行為,請使用這個元素。 |
類型: | 字串 |
有效值: | code (適用於授權碼授權類型) 或 token (適用於隱含授權類型) |
搭配授權類型使用: |
|
<ReuseRefreshToken> 元素
<ReuseRefreshToken>true</ReuseRefreshToken>
如果設為 true
,現有的更新權杖會一直重複使用,直到過期為止。若為 false
,當 Apigee Edge 顯示有效的更新權杖時,就會核發新的更新權杖。
預設: |
|
所在地: |
選填 |
類型: | boolean |
有效值: |
|
搭配授權類型使用: |
|
<Scope> 元素
<Scope>request.queryparam.scope</Scope>
如果這個元素出現在其中一項 GenerateAccessToken 或 GenerateAuthorizationCode 政策中,系統就會使用此元素指定要授予權杖或程式碼的範圍。這些值通常會從用戶端應用程式傳送至要求中的政策。您可以設定讓元素擷取資料流變數,您可以選擇在要求中傳送範圍。在以下範例中,request.queryparam.scope
表示範圍應以查詢參數的形式呈現,例如 ?scope=READ
。舉例來說,如要要求 HTTP 標頭中的範圍,請將這個值設為 request.header.scope
。
如果這個元素出現在「VerifyAccessToken」政策中,系統會使用該元素指定政策應強制執行的範圍。在這類政策中,值必須是「經過硬式編碼」的範圍名稱,無法使用變數。例如:
<Scope>A B</Scope>
另請參閱「使用 OAuth2 範圍」和「要求存取權杖和授權碼」。
預設: |
未設定範圍 |
所在地: |
選用 |
類型: | 字串 |
有效值: |
如果與 Generate* 政策搭配使用,則是指流程變數。 與 VerifyAccessToken 搭配使用時,會以空格分隔的範圍名稱 (字串) 清單。 |
搭配授權類型使用: |
|
<State> 元素
<State>request.queryparam.state</State>
如果用戶端應用程式必須將狀態資訊傳送至授權伺服器,這個元素可讓您指定 Edge 尋找狀態值的位置。例如以查詢參數或 HTTP 標頭的形式傳送。狀態值通常會做為安全措施使用,以防範 CSRF 攻擊。
舉例來說,request.queryparam.state
表示狀態應以查詢參數的形式呈現,例如 ?state=HjoiuKJH32
。例如,如要要求 HTTP 標頭中的狀態,請將這個值設為 request.header.state
。另請參閱要求存取權杖和授權碼。
預設: |
沒有狀態 |
所在地: |
選用 |
類型: | 字串 |
有效值: | 可在執行階段存取政策的任何流程變數 |
搭配授權類型使用: |
|
<StoreToken> 元素
<StoreToken>true</StoreToken>
當 <ExternalAuthorization>
元素為 true
時,將此元素設為 true
。<StoreToken>
元素會通知 Apigee Edge 儲存外部存取權杖。否則系統不會保留。
預設: |
false |
所在地: |
選用 |
類型: | 布林值 |
有效值: | true 或 false |
搭配授權類型使用: |
|
<SupportedGrantTypes>/<GrantType> 元素
<SupportedGrantTypes> <GrantType>authorization_code</GrantType> <GrantType>client_credentials</GrantType> <GrantType>implicit</GrantType> <GrantType>password</GrantType> </SupportedGrantTypes>
指定 Apigee Edge 中 OAuth 權杖端點支援的授權類型。單一端點可能支援多種授權類型 (也就是說,您可以設定一個端點,為多個授權類型發布存取權杖)。如要進一步瞭解端點,請參閱瞭解 OAuth 端點。授權類型會透過 grant_type
參數的權杖要求傳遞。
如果未指定支援的授權類型,則唯一允許的授權類型為 authorization_code
和 implicit
。另請參閱 <GrantType> 元素 (這是一個較高層級的元素,用來指定 Apigee Edge 應在何處尋找透過用戶端要求傳遞的 grant_type
參數)。Edge 會確保 grant_type
參數值與支援的其中一個授權類型相符。
預設: |
授權 _code 和隱含 |
所在地: |
必要 |
類型: | 字串 |
有效值: |
|
<Tokens>/<Token> 元素
可與 ValidationToken 和 InvalidateToken 作業搭配使用。另請參閱核准及撤銷存取權杖。<Token> 元素可識別定義要撤銷權杖來源的流程變數。如果開發人員應提交存取權杖做為名為 access_token
的查詢參數,例如使用 request.queryparam.access_token
。
<UserName> 元素
<UserName>request.queryparam.user_name</UserName>
這個元素僅適用於 密碼授權類型。採用密碼授權類型時,必須開放 OAuthV2 政策的使用者憑證 (密碼與使用者名稱)。<PassWord>
和 <UserName>
元素是用來指定 Edge 可在哪些變數找到這些值。如未指定這些元素,政策預設會尋找格式為 username
和 password
的表單參數中的值。如果找不到這些值,政策會擲回錯誤。您可以使用 <PassWord>
和 <UserName>
元素,參照包含憑證的任何流程變數。
舉例來說,您可以在查詢參數中傳遞使用者名稱,並設定 <UserName>
元素,如下所示:
<UserName>request.queryparam.username</UserName>
.
如要在 HTTP 標頭中要求使用者名稱,請將這個值設為 request.header.username
。
OAuthV2 政策並未對這些憑證值執行任何操作;Edge 只是確認憑證是否存在。API 開發人員會在權杖產生政策執行前,擷取值要求並傳送至識別資訊提供者。
另請參閱要求存取權杖和授權碼。
預設: |
request.formparam.username (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 任何變數設定。 |
搭配授權類型使用: | 密碼 |
驗證存取權杖
為 API Proxy 設定權杖端點後,指定 VerifyAccessToken
作業的對應 OAuthV2 政策就會附加至公開受保護資源的流程。
舉例來說,為確保所有對 API 發出的要求都已獲得授權,下列政策會強制執行存取權杖驗證:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
這項政策已附加至要保護的 API 資源。為確保能驗證傳送至 API 的所有要求,請將政策附加至 ProxyEndpoint 要求 PreFlow,如下所示:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
下列選用元素可用來覆寫 VerifyAccessToken 作業的預設設定。
名稱 | 說明 |
---|---|
範圍 |
以空格分隔的範圍清單。如果存取權杖中至少有一個範圍列於存取權杖中,就表示驗證成功。舉例來說,下列政策會檢查存取權杖,確保其包含至少一個列出的範圍。若 READ 或 WRITE 存在,驗證就會成功。 <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
AccessToken | 存取權杖預期所在的變數。例如:request.queryparam.accesstoken 。根據預設,存取權杖應根據 OAuth 2.0 規格,在 Authorization HTTP 標頭中顯示應用程式。如果存取權杖應出現在非標準位置 (例如查詢參數),或名稱不是「Authorization」的 HTTP 標頭,請使用這項設定。 |
另請參閱「驗證存取權杖」和「要求存取權杖和授權碼」。
指定要求變數位置
針對每種授權類型,政策會假設要求訊息中的位置或必要資訊。這些假設是以 OAuth 2.0 規格為基礎。如果您的應用程式需要使用 OAuth 2.0 規格,您可以為各參數指定預期位置。舉例來說,處理授權碼時,您可以指定授權碼的位置、用戶端 ID、重新導向 URI 和範圍。這些屬性可做為 HTTP 標頭、查詢參數或表單參數。
以下範例說明如何將必要授權代碼參數的位置指定為 HTTP 標頭:
... <GrantType>request.header.grant_type</GrantType> <Code>request.header.code</Code> <ClientId>request.header.client_id</ClientId> <RedirectUri>request.header.redirect_uri</RedirectUri> <Scope>request.header.scope</Scope> ...
如需支援您的用戶端應用程式基礎,您也可以混合或比對標頭和查詢參數:
... <GrantType>request.header.grant_type</GrantType> <Code>request.header.code</Code> <ClientId>request.queryparam.client_id</ClientId> <RedirectUri>request.queryparam.redirect_uri</RedirectUri> <Scope>request.queryparam.scope</Scope> ...
每個參數只能設定一個位置。
流程變數
系統執行各個 OAuth 政策時,就會填入本表格中定義的流程變數,因此也能提供給在 API Proxy 流程中執行的其他政策或應用程式。
VerifyAccessToken 作業
VerifyAccessToken 作業執行時,會在 Proxy 的執行環境中填入大量流程變數。這些變數可提供與存取權杖、開發人員應用程式、開發人員和公司相關的屬性。舉例來說,您可以使用 AssignMessage 或 JavaScript 政策來讀取任何變數,並在後續流程中視需求使用。這些變數也很適合用於偵錯。
proxy.pathsuffix
),系統會自動填入 API 產品變數,您不需要明確設定 flow.resource.name 變數。如果 API 產品並非以有效的環境和 API Proxy 設定,您必須明確設定 flow.resource.name
,才能在流程中填入 API 產品變數。如要進一步瞭解產品設定,請參閱使用 Edge Management API 發布 API。
權杖專屬變數
變數 | 說明 |
---|---|
organization_name |
執行 Proxy 的機構名稱。 |
developer.id |
與所註冊用戶端應用程式相關聯的開發人員 ID。 |
developer.app.name |
與所註冊用戶端應用程式相關聯的開發人員名稱。 |
client_id |
所註冊用戶端應用程式的用戶端 ID。 |
grant_type |
與要求相關聯的授權類型。 |
token_type |
與要求相關聯的權杖類型。 |
access_token |
正在驗證的存取權杖。 |
accesstoken.{custom_attribute} |
存取權杖中的已命名自訂屬性。 |
issued_at |
存取權杖的核發日期,以 Unix Epoch 紀元時間表示 (以毫秒為單位)。 |
expires_in |
存取權杖的到期時間。以秒表示。雖然 ExpiresIn 元素會以毫秒為單位設定到期時間,但在權杖回應和流程變數中,這個值的到期時間以秒為單位。 |
status |
存取權杖的狀態 (例如已核准或已撤銷)。 |
scope |
與存取權杖相關聯的範圍 (如有)。 |
apiproduct.<custom_attribute_name> |
與註冊用戶端應用程式相關聯的 API 產品具名自訂屬性。 |
apiproduct.name |
與註冊的用戶端應用程式相關聯的 API 產品名稱。 |
revoke_reason |
(僅限 Apigee 混合) 說明存取權杖撤銷的原因。 值可以是 |
應用程式專屬變數
這些變數與權杖相關聯的開發人員應用程式。
變數 | 說明 |
---|---|
app.name |
|
app.id |
|
app.accessType |
|
app.callbackUrl |
|
app.status |
已核准或已撤銷 |
app.scopes |
|
app.appFamily |
|
app.apiproducts |
|
app.appParentStatus |
|
app.appType |
例如:開發人員 |
app.appParentId |
|
app.created_by |
|
app.created_at |
|
app.last_modified_at |
|
app.last_modified_by |
|
app.{custom_attributes} |
已註冊的用戶端應用程式的具名自訂屬性。 |
開發人員專屬變數
如果 app.appType 為「Company」,系統會填入公司屬性;如果 app.appType 為「Developer」,系統會填入開發人員屬性。
變數 | 說明 |
---|---|
開發人員專屬變數 | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
有效或無效 |
developer.apps |
|
developer.created_by |
|
developer.created_at |
|
developer.last_modified_at |
|
developer.last_modified_by |
|
developer.{custom_attributes} |
開發人員的具名自訂屬性。 |
公司專屬變數
如果 app.appType 為「Company」,系統會填入公司屬性;如果 app.appType 為「Developer」,系統會填入開發人員屬性。
變數 | 說明 |
---|---|
company.id |
|
company.displayName |
|
company.apps |
|
company.appOwnerStatus |
|
company.created_by |
|
company.created_at |
|
company.last_modified_at |
|
company.last_modified_by |
|
company.{custom_attributes} |
公司的具名自訂屬性。 |
GenerateAuthorizationCode 作業
系統會在 GenerateAuthorizationCode 作業成功執行時設定這些變數:
前置字串: oauthv2authcode.{policy_name}.{variable_name}
範例:oauthv2authcode.GenerateCodePolicy.code
變數 | 說明 |
---|---|
code |
執行政策時產生的授權碼。 |
redirect_uri |
與已註冊的用戶端應用程式相關聯的重新導向 URI。 |
scope |
在用戶端要求中傳遞的選用 OAuth 範圍。 |
client_id |
在用戶端要求中傳遞的用戶端 ID。 |
GenerateAccessToken 和 RefreshAccessToken 作業
系統會在 GenerateAccessToken 和 RefreshAccessToken 作業成功執行時,設定這些變數。請注意,更新權杖變數不適用於用戶端憑證授權類型流程。
前置字串: oauthv2accesstoken.{policy_name}.{variable_name}
範例:oauthv2accesstoken.GenerateTokenPolicy.access_token
變數名稱 | 說明 |
---|---|
access_token |
產生的存取權杖。 |
client_id |
與這個權杖相關聯的開發人員應用程式的用戶端 ID。 |
expires_in |
權杖的到期時間值。詳情請參閱 <ExpiresIn> 元素。請注意,在回應中,expires_in 是以秒表示。 |
scope |
權杖的可用範圍清單。請參閱使用 OAuth2 範圍。 |
status |
approved 或 revoked 。 |
token_type |
已設為「BearerToken 」。 |
developer.email |
擁有與權杖相關聯的開發人員應用程式所屬註冊開發人員的電子郵件地址。 |
organization_name |
執行 Proxy 的機構。 |
api_product_list |
與權杖的對應開發人員應用程式相關聯的產品清單。 |
refresh_count |
|
refresh_token |
產生的更新權杖。請注意,系統不會針對用戶端憑證授權類型產生更新權杖。 |
refresh_token_expires_in |
更新權杖的效期 (以秒為單位)。 |
refresh_token_issued_at |
這個時間值是對應 32 位元時間戳記數量的字串,例如,「Wed, 21 Aug 2013 19:16:47 UTC」可對應時間戳記值 1377112607413。 |
refresh_token_status |
approved 或 revoked 。 |
GenerateAccessTokenImplicitGrant
當 GenerateAccessTokenImplicit 作業針對隱含授予類型流程成功執行時,系統會設定這些變數。
前置字串: oauthv2accesstoken.{policy_name}.{variable_name}
範例:oauthv2accesstoken.RefreshTokenPolicy.access_token
變數 | 說明 |
---|---|
oauthv2accesstoken.access_token |
在執行政策時產生的存取權杖。 |
oauthv2accesstoken.{policy_name}.expires_in |
權杖的到期時間值 (以秒為單位)。詳情請參閱 <ExpiresIn> 元素。 |
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。
錯誤代碼 | HTTP 狀態 | 原因 | 依作業擲回 |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 | 存取權杖已過期。 |
VerifyAccessToken |
steps.oauth.v2.access_token_not_approved |
401 | 存取權杖已撤銷。 | VerifyAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 | 要求的資源不存在,且沒有任何與存取權杖相關聯的 API 產品。 | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 | 這項政策預期會在 <AccessToken> 元素指定的變數中找到存取權杖,但該變數無法解析。 |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 | 這項政策預期會在 <Code> 元素指定的變數中找到授權碼,但該變數無法解析。 |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 | 這項政策預期會在 <ClientId> 元素中指定的變數中找到用戶端 ID,但該變數無法解析。 |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 | 這項政策預期會在 <RefreshToken> 元素指定的變數中找到更新權杖,但該變數無法解析。 |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 | 這項政策預期會在 <Tokens> 元素指定的變數中找到權杖,但該變數無法解析。 |
VerifyToken |
steps.oauth.v2.InsufficientScope |
403 | 要求中顯示的存取權杖範圍與驗證存取權杖政策中指定的範圍不符。如要瞭解範圍,請參閱使用 OAuth2 範圍。 | VerifyAccessToken |
steps.oauth.v2.invalid_access_token |
401 | 從用戶端傳送的存取權杖無效。 | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
如果政策的 注意:建議您變更現有的錯誤規則條件,以擷取 |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.invalid_request |
400 | 這個錯誤名稱可用於多種錯誤類型,通常是因為要求中遺漏或不正確的參數。如果將 <GenerateResponse> 設為 false ,請使用錯誤變數 (如下所述) 擷取錯誤的詳細資料,例如錯誤名稱和原因。 |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | 授權標頭不含必要的「Bearer」字詞。例如:Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
API Proxy 不在與存取權杖相關聯的產品中。 提示:請確定與存取權杖相關聯的產品設定正確無誤。舉例來說,如果您在資源路徑中使用萬用字元,請確保萬用字元已正確使用。詳情請參閱「建立 API 產品」。 如要進一步瞭解這個錯誤的原因,請一併參閱這篇Apigee 社群貼文。 |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
如果政策的 |
GenerateAccessToken |
steps.oauth.v2.InvalidParameter |
500 | 政策必須指定存取權杖或授權碼,但不得同時指定兩者。 | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 | 您必須使用 <Tokens>/<Token> 元素指定權杖類型 (例如 refreshtoken )。如果用戶端傳遞了錯誤的類型,系統就會擲回這個錯誤。 |
VerifyToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 | 回應類型為 token ,但未指定授權類型。 |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
用戶端指定的授權類型不受政策支援 (未列於 <SupportedGrantTypes> 元素中)。 注意:目前有一個錯誤,無法正確擲回不支援的授權類型錯誤。如果發生不支援的授權類型錯誤,Proxy 不會如預期進入錯誤流程。 |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
部署錯誤
若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。
錯誤名稱 | 原因 |
---|---|
InvalidValueForExpiresIn |
|
InvalidValueForRefreshTokenExpiresIn |
<RefreshTokenExpiresIn> 元素的有效值是正整數和 -1 。 |
InvalidGrantType |
<SupportedGrantTypes> 元素中指定的授權類型無效。如需有效類型的清單,請參閱政策參考資料。 |
ExpiresInNotApplicableForOperation |
請確認 <Operations> 元素中指定的作業支援到期時間。例如,VerifyToken 作業則不會。 |
RefreshTokenExpiresInNotApplicableForOperation |
請確認 <Operations> 元素中指定的作業支援更新權杖到期時間。例如,VerifyToken 作業則不會。 |
GrantTypesNotApplicableForOperation |
請確認您在 <SupportedGrantTypes> 中指定的授權類型支援指定作業。 |
OperationRequired |
您必須使用 注意:如果缺少 |
InvalidOperation |
您必須使用 注意:如果 |
TokenValueRequired |
您必須在 <Tokens> 元素中指定權杖 <Token> 值。 |
錯誤變數
當這項政策在執行階段觸發錯誤時,系統會設定這些變數。
<GenerateResponse>
設為 false
,發生錯誤時,系統就會填入這些變數。如果 <GenerateResponse>
為 true
,當發生錯誤時,政策會立即將回應傳回用戶端;系統會略過錯誤流程,而且不會填入這些變數。詳情請參閱政策錯誤須知。錯誤回應範例
如果 <GenerateResponse>
元素為 true,這些回應就會傳回用戶端。
errorcode
部分。請勿依賴 faultstring
中的文字,因為文字可能會有所變動。如果 <GenerateResponse>
為 true,政策會針對產生權杖和代碼的作業傳回這種格式的錯誤。如需完整清單,請參閱 OAuth HTTP 錯誤回應參考資料。
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
如果 <GenerateResponse>
為 true,政策會傳回這種格式的錯誤,以便驗證及驗證作業。如需完整清單,請參閱 OAuth HTTP 錯誤回應參考資料。
{ { "fault":{ "faultstring":"Invalid Access Token", "detail":{ "errorcode":"keymanagement.service.invalid_access_token" } } }
故障規則示例
<FaultRule name=OAuthV2 Faults"> <Step> <Name>AM-InvalidClientResponse</Name> <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition> </Step> <Step> <Name>AM-InvalidTokenResponse</Name> <Condition>(fault.name = "invalid_access_token")</Condition> </Step> <Condition>(oauthV2.failed = true) </Condition> </FaultRule>
政策架構
每個政策類型都是由 XML 結構定義 (.xsd
) 定義。如需參考,GitHub 提供政策結構定義。
使用預設 OAuth 設定
在 Apigee Edge 中,每個機構 (甚至是免費試用機構) 都會使用 OAuth 權杖端點佈建。端點已在 API Proxy 中名為 oauth 的政策設定。只要在 Apigee Edge 中建立帳戶之後,就能立即開始使用權杖端點。詳情請參閱「瞭解 OAuth 端點」。
清除存取權杖
根據預設,存取權杖和更新權杖 (如有) 到期後,Apigee Edge 系統中的 OAuth2 權杖會在 3 天 (259200 秒) 中清除。在某些情況下,您可能想要變更這項預設值。舉例來說,如果您要產生大量權杖,就可以縮短清除時間來節省磁碟空間。
如果您使用 Edge for Private Cloud,您可以透過設定機構屬性來變更這項設定。(在 3 天內清除過期權杖的功能,適用於 Edge for Private Cloud 4.19.01 以上版本。若是較舊版本,清除間隔預設為 180 天)。
更新 Edge Private Cloud 4.16.01 以上版本的清除設定
注意:只有套用這些設定「之後」產生的權杖會受到影響;設定不適用於先前產生的權杖。
- 開啟這個檔案以進行編輯:
/opt/apigee/customer/application/message-processor.properties
- 新增下列屬性,設定在權杖過期後,要等待多少秒才能清除權杖:
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
- 重新啟動訊息處理器。例如:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
<ExpiresIn>
和 <RefreshTokenExpiresIn>
屬性,在 OAuthV2 政策中設定權杖到期時間。正在更新 Edge Private Cloud 4.15.07 的清除設定
注意:只有套用這些設定「之後」產生的權杖會受到影響;設定不適用於先前產生的權杖。
-
為 OAuthV2 政策中的
<ExpiresIn>
和<RefreshTokenExpiresIn>
屬性設定正值。值的單位為毫秒。例如:<ExpiresIn>1000</ExpiresIn> <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
-
重新部署 Proxy。
-
使用這個 API 更新貴機構的權杖清除屬性:
POST https://<host-name>/v1/organizations/<org-name>
酬載:
<Organization name="AutomationOrganization"> <Description>Desc</Description> <Properties> <Property name="keymanagement.oauth20.access.token.purge">true</Property> <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property> </Properties> </Organization>
-
重新啟動訊息處理器。例如:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
這個 API 會將名為 AutomationOrganization 的權杖清除屬性設為 true。在此情況下,權杖和更新權杖失效後,系統會在 120 秒內清除資料庫中的存取權杖。
不符合 RFC 的行為
OAuthV2 政策會傳回權杖回應,其中包含某些不符合 RFC 規定的屬性。下表列出 OAuthV2 政策傳回的不符規定屬性,以及對應符合規定的屬性。
OAuthV2 傳回: | 符合 RFC 規定的屬性如下: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
(符合規定的值是數字,不是字串)。 |
此外,當 grant_type = refresh_token
出現時,過期更新權杖的錯誤回應如下:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
不過,符合 RFC 規定的回應如下:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}