GetOAuthV2Info 政策

您正在查看 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

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和半形句號。這個值不得超過 255 個半形字元。

您也可以選擇使用 <DisplayName> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<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 傳送至政策的更新權杖已過期。

部署錯誤

如要瞭解部署錯誤,請參閱使用者介面中回報的訊息。

錯誤變數

當這項政策在執行階段觸發錯誤時,系統會設定這些變數。

Variables 地點 範例
fault.name="fault_name" fault_name 是錯誤的名稱,如上方的「執行階段錯誤」表格所示。錯誤名稱是錯誤碼的最後一個部分。 fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name 是擲回錯誤的政策使用者指定的名稱。 oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name 是擲回錯誤的政策使用者指定的名稱。 oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name 是擲回錯誤的政策使用者指定的名稱。 oauthV2.GetTokenInfo.cause = ClientID is Invalid

錯誤回應範例

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

相關主題