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

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

 N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

 false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

 true Optional
async

This attribute is deprecated.

 false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type String

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

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code HTTP status Cause
steps.oauth.v2.access_token_expired 500 The access token sent to the policy is expired.
steps.oauth.v2.authorization_code_expired 500 The authorization code sent to the policy is expired.
steps.oauth.v2.invalid_access_token 500 The access token sent to the policy is invalid.
steps.oauth.v2.invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
steps.oauth.v2.invalid_refresh_token 500 The refresh token sent to the policy is invalid.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Please see this Apigee Community post for information about troubleshooting this error.
steps.oauth.v2.refresh_token_expired 500 The refresh token sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.cause = ClientID is Invalid

Example error response

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

相關主題