GetOAuthV2Info 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

當您需要根據權杖或授權碼中的值設定動態條件式行為時，這項政策就很有用。每當進行權杖驗證時，系統會自動填入權杖屬性的值。不過，如果尚未驗證權杖，您可以使用這項功能，明確填入權杖的屬性值。另請參閱自訂憑證和授權碼。

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

範例

下列範例使用「Get OAuth V2 Info」政策，擷取 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> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 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-urlencoded，且在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值：

包含存取權權杖字串的流程變數，或字串常值。

<AuthorizationCode> 元素

根據授權碼擷取設定檔。您可以傳入包含授權碼字串的變數，或是傳入字面值權杖字串 (少見情況)。在本例中，驗證碼是從要求中傳遞的查詢參數擷取而來。如需這項作業填入的變數清單，請參閱「流程變數」。

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

預設值：

request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值：

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

<ClientId> 元素

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

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

預設值：

request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態：

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

<IgnoreAccessTokenStatus> 元素

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

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

預設值：

false

外觀狀態：

選用
類型： 布林值
有效值： true 或 false

<RefreshToken> 元素

擷取更新權杖的設定檔。您可以傳入包含重新整理權杖字串的變數，或是權杖字串文字 (少見情況)。在本例中，重新整理權杖是從要求中傳遞的查詢參數擷取。如需這項作業填入的變數清單，請參閱「流程變數」。

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

預設值：

request.formparam.access_token (x-www-form-urlencoded，且在要求主體中指定)

外觀狀態：

選用
類型： 字串
有效值：

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

流程變數

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.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>

相關主題