GetOAuthV2Info 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

政策圖示

結果

取得存取權杖、更新權杖、授權碼和用戶端應用程式屬性的屬性，並使用這些屬性的值填入變數。

當您需要根據權杖或驗證碼中的值，設定動態條件行為時，這項政策就很實用。每次發生符記驗證時，系統都會自動將符記屬性的值填入變數。不過，如果尚未進行符記驗證，您可以使用這項功能，明確地將符記的屬性值填入變數。另請參閱「自訂權杖和授權碼」。

您傳遞至這項政策的存取權權杖必須有效，否則政策會擲回 invalid_access_token 錯誤。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

範例

以下範例會使用「取得 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、授權碼和重新整理權杖) 執行這項操作。

用戶端 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 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

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

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<AccessToken> 元素

擷取存取權杖的設定檔。您傳入的變數必須包含存取權杖字串，或常值權杖字串 (較少見)。在這個範例中，系統會從要求中傳遞的查詢參數擷取存取權權杖。如果您想傳回已撤銷或過期的權杖資訊，請使用 <IgnoreAccessTokenStatus> 元素。

<AccessToken ref="request.queryparam.access_token"></AccessToken>

預設值：

request.formparam.access_token (以 x-www-form-url-encoded 編碼，並在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值：

含有存取權憑證字串的流程變數，或字串常值。

<AuthorizationCode> 元素

擷取授權碼的設定檔。您傳入的變數必須包含驗證碼字串，或字面值符記字串 (較少見)。在這個範例中，系統會從要求中傳遞的查詢參數中擷取驗證碼。如需這項作業填入的變數清單，請參閱「流程變數」。

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

預設值：

request.formparam.access_token (以 x-www-form-url-encoded 編碼，並在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值：

包含授權碼字串的流程變數，或字面字串。

<ClientId> 元素

擷取與用戶端 ID 相關的資訊。在這個範例中，系統會從要求中傳遞的查詢參數擷取用戶端 ID。如需這項作業填入的變數清單，請參閱「流程變數」。

<ClientId ref="request.queryparam.client_id"></ClientId>

預設值：

request.formparam.access_token (以 x-www-form-url-encoded 編碼，並在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值： 包含授權碼字串的流程變數，或字面字串。

<IgnoreAccessTokenStatus> 元素

即使權杖已過期或遭撤銷，也能傳回權杖資訊。這個元素只能與存取權存取權杖搭配使用。根據預設，系統會傳回其他實體的資訊 (例如重新整理權杖和授權碼)，無論其狀態為何。

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

預設值：

false

外觀狀態：

選用
類型： 布林值
有效值： 是非題

<RefreshToken> 元素

擷取更新權杖的設定檔。您傳入的變數必須包含重新整理權杖字串，或字面權杖字串 (較少見)。在這個範例中，系統會從要求中傳遞的查詢參數中擷取重新整理權杖。如需這項作業填入的變數清單，請參閱「流程變數」。

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

預設值：

request.formparam.access_token (以 x-www-form-url-encoded 編碼，並在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值：

含有重新整理權杖字串的流程變數，或字串常值。

流程變數

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 查看政策架構。

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。下方顯示的錯誤名稱是發生錯誤時，指派給 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 如要瞭解如何排解此錯誤，請參閱「 Oauth2.0 存取權杖驗證會擲回「找不到相符的 apiproduct，因此 API 呼叫無效」錯誤」一文。
steps.oauth.v2.refresh_token_expired 500 傳送至政策的更新權杖已過期。

部署錯誤

請參閱 UI 中回報的訊息，瞭解部署錯誤。

錯誤變數

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

變數 地點 範例
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>

相關主題