您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
取得存取權杖、更新權杖、授權碼和用戶端應用程式屬性的屬性,並在變數中填入這些屬性的值。
當您需要根據權杖或驗證碼中的值設定動態條件式行為時,這項政策就能派上用場。每當系統進行權杖驗證時,變數就會自動填入權杖屬性值。然而,如未進行權杖驗證,您可以使用這項功能,在變數中明確填入符記的屬性值。另請參閱自訂權杖與授權碼。
傳送至這項政策的存取權杖必須有效,否則政策將擲回 invalid_access_token
錯誤。
範例
下列範例使用「取得 OAuth V2 資訊」政策來擷取 OAuth2 工作流程的各個元件相關資訊,然後在程式碼中存取該項資訊。
存取權杖
如要取得存取權杖的參照,請在政策中使用 <AccessToken>
元素。
以下範例預期可在名為「access_token」的查詢參數中找出存取權杖 (實際實作詳情取決於您):
<GetOAuthV2Info name="MyTokenAttrsPolicy"> <AccessToken ref="request.queryparam.access_token"></AccessToken> </GetOAuthV2Info>
取得存取權杖後,政策會查詢權杖的設定檔,並將設定檔資料填入一組變數。
接下來,您可以透過 JavaScript 或其他方式存取變數。以下範例會使用 JavaScript 擷取與存取權杖相關聯的範圍:
var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');
請注意,如要在程式碼中存取這些變數,您必須在這些變數前面加上「oauthv2accesstoken」。如需透過存取權杖取得的變數完整清單,請參閱存取權杖變數。
驗證碼
如要取得授權碼屬性,請在政策中使用 <AuthorizationCode>
元素。
以下範例預期可在名為「code」的格式參數中找到存取權杖 (實際實作詳情由您決定):
<GetOAuthV2Info name="MyAuthCodeAttrsPolicy"> <AuthorizationCode ref="request.formparam.code"></AuthorizationCode> </GetOAuthV2Info>
基於驗證碼,政策會查詢代碼資訊,並將驗證碼資料填入一組變數。
接下來,您可以透過 JavaScript 或其他方式存取變數。以下範例會使用 JavaScript 擷取與授權碼相關聯的自訂屬性:
var attr = context.getVariable(‘oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name’);
請注意,如要在程式碼中存取這些變數,您必須在這些變數前面加上「oauthv2authcode」。 如需驗證碼可用的變數完整清單,請參閱授權碼變數。
重新整理權杖
如要取得更新權杖屬性,請使用政策中的 <RefreshToken>
元素。
以下範例預期可在名為「refresh_token」的查詢參數中找到存取權杖 (實際實作詳情由您決定):
<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy"> <RefreshToken ref="request.queryparam.refresh_token"/> </GetOAuthV2Info>
針對更新權杖,政策會查詢更新權杖的資訊,並將更新權杖資料填入一組變數。
這樣一來,您就能透過 JavaScript 或其他方式存取這些變數。以下範例會使用 JavaScript 擷取與更新權杖相關聯的自訂屬性:
var attr = context.getVariable(‘oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name’);
請注意,如要存取程式碼中的變數,您必須在這些變數前面加上「oauthv2refreshtoken」。如需可更新權杖的完整變數清單,請參閱「重新整理權杖變數」一節。
靜態
在極少數情況下,您可能需要取得靜態設定權杖 (無法透過變數存取) 的設定檔。如要這麼做,請將存取權杖的值做為元素提供。
<GetOAuthV2Info name="GetTokenAttributes"> <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken> </GetOAuthV2Info>
您也可以透過所有其他權杖類型 (用戶端 ID、授權碼和更新權杖) 執行這項操作。
Client-ID
本例說明如何使用用戶端 ID 擷取用戶端應用程式相關資訊。執行後,政策會將用戶端資訊填入一組變數。在這種情況下,政策會預期在名為 client_id
的查詢參數中找到用戶端 ID。針對用戶端 ID,政策會查詢用戶端設定檔,並將設定檔資料填入一組變數。變數的前置字串會是 oauthv2client.
<GetOAuthV2Info name="GetClientAttributes"> <ClientId ref="request.queryparam.client_id"></ClientId> </GetOAuthV2Info>
接下來,您可以透過 JavaScript 或其他方式存取變數。舉例來說,如要使用 JavaScript 取得與用戶端應用程式相關聯的開發人員應用程式名稱和開發人員電子郵件地址:
context.getVariable("oauthv2client.GetClientAttributes.developer.email"); context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");
元素參照
元素參考資料說明 GetOAuthV2Info 政策的元素和屬性。
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1" <DisplayName>Get OAuth v2.0 Info 1</DisplayName> <AccessToken ref="variable"></AccessToken> <AuthorizationCode ref="variable"></AuthorizationCode> <ClientId ref="variable"></ClientId> <RefreshToken ref="variable"></RefreshToken> </GetOAuthV2Info>
<GetOAuthV2Info> 屬性
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">
下表說明所有政策父項元素的通用屬性:
屬性 | 說明 | 預設 | 存在必要性 |
---|---|---|---|
name |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<AccessToken> 元素
擷取存取權杖的設定檔。您傳入包含存取權杖字串或常值權杖字串的變數 (罕見情況)。在此範例中,系統會從要求中傳遞的查詢參數中擷取存取權杖。如要傳回已撤銷或過期權杖的資訊,請使用 <IgnoreAccessTokenStatus> 元素。
<AccessToken ref="request.queryparam.access_token"></AccessToken>
預設: |
request.formparam.access_token (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: |
包含存取權杖字串的流程變數或常值字串。 |
<AuthorizationCode> 元素
擷取授權碼的設定檔。您傳入包含驗證碼字串或常值權杖字串 (罕見情況) 的變數。在本範例中,驗證碼是擷取自要求中傳遞的查詢參數,如需這項作業填入的變數清單,請參閱「流程變數」一節。
<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>
預設: |
request.formparam.access_token (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: |
包含驗證碼字串的流程變數或常值字串。 |
<ClientId> 元素
擷取用戶端 ID 相關資訊。在此範例中,系統會從要求中傳遞的查詢參數中擷取用戶端 ID。如需這項作業填入的變數清單,請參閱「流程變數」一節。
<ClientId ref="request.queryparam.client_id"></ClientId>
預設: |
request.formparam.access_token (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: | 包含驗證碼字串的流程變數或常值字串。 |
<IgnoreAccessTokenStatus> 元素
即使權杖已過期或撤銷,系統還是會傳回權杖資訊。這個元素只能與存取權杖搭配使用。根據預設,無論實體狀態為何,系統都會傳回重新整理權杖和授權碼等其他實體的資訊。
<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>
預設: |
false |
所在地: |
選用 |
類型: | 布林值 |
有效值: | true 或 false |
<RefreshToken> 元素
擷取更新權杖的設定檔。您傳入包含更新權杖字串或常值權杖字串 (罕見情況) 的變數。在本範例中,系統會從要求中傳遞的查詢參數中擷取更新權杖。如需這項作業填入的變數清單,請參閱「流程變數」一節。
<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>
預設: |
request.formparam.access_token (x-www-form-url 編碼,並在要求主體中指定) |
所在地: |
選用 |
類型: | 字串 |
有效值: |
包含更新權杖字串的流程變數或常值字串。 |
流程變數
GetOAuthV2Info 政策會填入這些變數,通常用於您需要設定檔資料,但尚未進行授權或驗證的情況。.
用戶端 ID 變數
設定 ClientId 元素時,系統就會填入這些變數:
oauthv2client.{policy_name}.client_id oauthv2client.{policy_name}.client_secret oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris' oauthv2client.{policy_name}.developer.email oauthv2client.{policy_name}.developer.app.name oauthv2client.{policy_name}.developer.id oauthv2client.{policy_name}.{developer_app_custom_attribute_name}
存取權杖變數
設定 AccessToken 元素時,系統就會填入這些變數:
oauthv2accesstoken.{policy_name}.developer.id oauthv2accesstoken.{policy_name}.developer.app.name oauthv2accesstoken.{policy_name}.developer.app.id oauthv2accesstoken.{policy_name}.developer.email oauthv2accesstoken.{policy_name}.organization_name oauthv2accesstoken.{policy_name}.api_product_list oauthv2accesstoken.{policy_name}.access_token oauthv2accesstoken.{policy_name}.scope oauthv2accesstoken.{policy_name}.expires_in //in seconds oauthv2accesstoken.{policy_name}.status oauthv2accesstoken.{policy_name}.client_id oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name} oauthv2accesstoken.{policy_name}.refresh_token oauthv2accesstoken.{policy_name}.refresh_token_status oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds oauthv2accesstoken.{policy_name}.refresh_count oauthv2accesstoken.{policy_name}.refresh_token_issued_at oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED
授權碼變數
設定 AuthorizationCode 元素時,系統就會填入這些變數:
oauthv2authcode.{policy_name}.code oauthv2authcode.{policy_name}.scope oauthv2authcode.{policy_name}.redirect_uri oauthv2authcode.{policy_name}.client_id oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}
重新整理權杖變數
設定 RefreshToken 元素時,系統就會填入這些變數:
oauthv2refreshtoken.{policy_name}.developer.id oauthv2refreshtoken.{policy_name}.developer.app.name oauthv2refreshtoken.{policy_name}.developer.app.id oauthv2refreshtoken.{policy_name}.developer.email oauthv2refreshtoken.{policy_name}.organization_name oauthv2refreshtoken.{policy_name}.api_product_list oauthv2refreshtoken.{policy_name}.access_token oauthv2refreshtoken.{policy_name}.scope oauthv2refreshtoken.{policy_name}.expires_in //in seconds oauthv2refreshtoken.{policy_name}.status oauthv2refreshtoken.{policy_name}.client_id oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name} oauthv2refreshtoken.{policy_name}.refresh_token oauthv2refreshtoken.{policy_name}.refresh_token_status oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds oauthv2refreshtoken.{policy_name}.refresh_count oauthv2refreshtoken.{policy_name}.refresh_token_issued_at oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED
結構定義
每個政策類型都是由 XML 結構定義 (.xsd
) 定義。如需參考,GitHub 提供政策結構定義。
錯誤參考資料
本節說明當這項政策觸發錯誤時,傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。 如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。
執行階段錯誤
執行政策時,可能會發生這些錯誤。下列錯誤名稱是系統在發生錯誤時指派給 fault.name
變數的字串。詳情請參閱下方的「錯誤變數」一節。
錯誤代碼 | HTTP 狀態 | 原因 |
---|---|---|
steps.oauth.v2.access_token_expired |
500 | 傳送至政策的存取權杖已過期。 |
steps.oauth.v2.authorization_code_expired |
500 | 傳送至政策的授權碼已過期。 |
steps.oauth.v2.invalid_access_token |
500 | 傳送至政策的存取權權杖無效。 |
steps.oauth.v2.invalid_client-invalid_client_id |
500 | 傳送至政策的用戶端 ID 無效。 |
steps.oauth.v2.invalid_refresh_token |
500 | 傳送至政策的更新權杖無效。 |
steps.oauth.v2.invalid_request-authorization_code_invalid |
500 | 傳送至政策的授權碼無效。 |
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound |
401 | 如要瞭解如何排解這項錯誤,請參閱 這篇 Apigee 社群文章。 |
steps.oauth.v2.refresh_token_expired |
500 | 傳送至政策的更新權杖已過期。 |
部署錯誤
如要瞭解部署錯誤,請參閱使用者介面中回報的訊息。
錯誤變數
當這項政策在執行階段觸發錯誤時,系統會設定這些變數。
錯誤回應範例
{ "fault":{ "faultstring":"ClientId is Invalid", "detail":{ "errorcode":"keymanagement.service.invalid_client-invalid_client_id" } } }
故障規則示例
<FaultRule name="OAuthV2 Faults"> <Step> <Name>AM-InvalidClientIdResponse</Name> </Step> <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition> </FaultRule>