Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Get OAuth V2 Info policy

What

Gets attributes of access tokens, refresh tokens, and authorization codes and populates variables with the values of those attributes. This policy type can be useful when you need to configure dynamic, conditional behavior based on a value in a token or code. Whenever token validation occurs, variables are automatically populated with the values of token attributes. However, in cases where token validation has not occured, you can use this feature to explicity populate variables with the attribute values of a token.  See also Customizing tokens and auth codes.

An access token that you pass to this policy must be valid or the policy will throw an invalid_access_token error. Also, the resource path that is used to call a proxy with this policy must be included in the Product that was used to generate the original token. In other words, if you call the proxy with the path /tokeninfo, then the /tokeninfo resource path must be included in the Product that was used to generate the token. If not, you will receive an InvalidAPICallAsNoApiProductMatchFound error. For more information, see this Apigee Community post

Where

This policy can be attached in the following locations. See the Samples section below for specific attachment guidance in different situations.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    レスポンス
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

This example shows how to retrieve profile information for an access token and use it to populate a set of variables. In this case, the policy expects to find the access token in a query parameter called access_token. Given the access token, the policy looks up the token's profile and populates a set of variables with the profile data. The variables will be prefixed with oauthv2accesstoken. 

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

You can then access the variables using JavaScript or another means. For example, to retrieve the scope(s) associated with an access token using JavaScript:

var scope = context.getVariable(‘oauthv2accesstoken.GetTokenAttributes.scope’);

Retrieving authorization code attributes

As with access tokens (described in the Access Code example), you can retrieve authorization code attributes by using the AuthorizationCode element in the policy as follows:

<GetOAuthV2Info name="GetAuthCodeAttributes">
    <AuthorizationCode ref="{variable name}"/>
</GetOAuthV2Info>

例:

<GetOAuthV2Info name="GetAuthCodeAttributes">
    <AuthorizationCode ref="request.queryparam.code"></AuthorizationCode>
</GetOAuthV2Info>

 

Retrieving refresh token attributes

As with access tokens (described in the Access Code example), you can retrieve refresh token attributes by using the RefreshToken element in the policy as follows:

<GetOAuthV2Info name="GetTokenAttributes">
    <RefreshToken ref="{variable name}"/>
</GetOAuthV2Info>

例:

<GetOAuthV2Info name="GetTokenAttributes">
  <RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>
</GetOAuthV2Info>
    

In some rare cases you may need to get the profile of a statically configured token (one that is not accessible through a variable). You can do this by providing the value of the access token as an element.

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

You can do this with all other token types (client ID, authorization code, and refresh tokens) as well.


Element Reference

The element reference describes the elements and attributes of the GetOAuthV2Info policy.

<?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={some-variable}></AccessToken>
</GetOAuthV2Info

<GetOAuthV2Info> attributes

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

The following attributes are common to all policy parent elements.

Attribute 説明 デフォルト Presence
name

The internal name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

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

該当なし 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:

該当なし

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

Presence: Optional
Type: 文字列

 

<AccessToken> element

Retrieves the profile for an access token. You pass in a either a variable that contains the access token string or a literal token string (rare case). In this example, the access token is retrieved from a query parameter passed in a request. Use the <IgnoreAccessTokenStatus> element if you want to return information for a revoked or expired token.

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

Default:

request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)

Presence:

Optional

Type: 文字列
Valid values:

Either a flow variable containing an access token string, or a literal string.


<AuthorizationCode> element

Retrieves the profile for an authorization code. You pass in a either a variable that contains the auth code string or a literal token string (rare case). In this example, the auth code is retrieved from a query parameter passed in a request. For a list of variables populated by this operation, see "Flow variables". 

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

Default:

request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)

Presence:

Optional

Type: 文字列
Valid values:

Either a flow variable containing an auth code string, or a literal string.

<ClientId> element

Retrieves information related to a client ID. In this example, the client ID is retrieved from a query parameter passed in a request. For a list of variables populated by this operation, see "Flow variables". 

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

Default:

request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)

Presence:

Optional

Type: 文字列
 
Valid values: Either a flow variable containing an auth code string, or a literal string.

 

<IgnoreAccessTokenStatus> element

Returns the token information even if the token is expired or revoked. This element can only be used with access tokens. Information for other entities like refresh tokens and authorization codes are returned regardless of their status, by default.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Default:

false

Presence:

Optional

Type: Boolean
 
Valid values: true or false
 

<RefreshToken> element

Retrieves the profile for a refresh token. You pass in a either a variable that contains the refresh token string or a literal token string (rare case). In this example, the refresh token is retrieved from a query parameter passed in a request. For a list of variables populated by this operation, see "Flow variables". 

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

Default:

request.formparam.access_token (a x-www-form-urlencoded and specified in the request body)

Presence:

Optional

Type: 文字列
Valid values:

Either a flow variable containing an refresh token string, or a literal string.

Flow variables

The GetOAuthV2Info policy populates these variables, and is typically used in cases where you need the profile data, but where a grant or validation has not occurred yet. .

Client ID variables

These variables are populated when the <ClientId> operation executes:

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}

Access token variables

These variables are populated when the <AccessToken> operation executes:

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}
oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.expires_in
oauthv2accesstoken.{policy_name}.status

Authorization code variables

These variables are populated when the <AuthorizationCode> operation executes:

oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.organization_id
oauthv2authcode.{policy_name}.issued_at
oauthv2authcode.{policy_name}.expires_in
oauthv2authcode.{policy_name}.redirect_uri
oauthv2authcode.{policy_name}.status
oauthv2authcode.{policy_name}.state
oauthv2authcode.{policy_name}.scope
oauthv2authcode.{policy_name}.id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

Refresh token variables

These variables are populated when the <RefreshToken> operation executes:

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

スキーマ

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Error reference

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

Error code prefix

steps.oauth.v2 (What's this?)

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.

Error name HTTP status Cause
invalid_access_token 500 The access token sent to the policy is invalid.
invalid_refresh_token 500 The refresh token sent to the policy is invalid.
expired_access_token 500 The access token sent to the policy is expired.
refresh_token_expired 500 The refresh token sent to the policy is expired.
invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
authorization_code_expired 500 The authorization code 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.

You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables set (Learn more) Where
[prefix].[policy_name].failed The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.GetTokenInfo.failed = true
[prefix].[policy_name].fault.name The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.

oauthV2.GetTokenInfo.fault.name = invalid_client-invalid_client_id

[prefix].[policy_name].fault.cause The [prefix] is oauthV2.
The [policy_name] is the name of the policy that threw the error.
oauthV2.GetTokenInfo.cause = ClientID is Invalid
fault.name = [error_name] [error_name] is the specific error name to check for as listed in the table above. fault.name = "invalid_client-invalid_client_id"

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>

関連トピック

Help or comments?