Get OAuth V2 Info policy

About | Samples | Element reference | Flow variables |  Schema  | Related topics

What

Gets profile attributes of access tokens, refresh tokens, and authorization codes and populates variables with 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.

The properties of a token or auth code profile are set as variables whenever a token or auth code is generated or validated. Sometimes, however, you will need to access these properties when no token generation or validation occurs. To do so, you can explicitly populate the access token profile by using the GetOAuthV2Info policy. See also Customizing tokens and auth codes.

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

For example:

<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 AuthorizationCode element in the policy as follows:

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

For example:

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

In some rare cases you may need to get the profile a statically configured token. You can do 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="SetOAuthV2Info-1"
    <DisplayName>Set OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref={some-variable}></AccessToken>
</SetOAuthV2Info

<GetOAuthV2Info> attributes

<SetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Set-OAuth-v20-Info-1">
Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The internal name of the policy. This name is referenced in Step elements to attach the policy to an API proxy flow.

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

N/A Required

<DisplayName> element

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>SetOAuthV2Info 1</DisplayName>
Default: Policy name attribute value.
Presence: Optional
Type: String

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

<AccessToken ref="request.queryparam.access_token"></AccessToken>
Default: N/A
Presence: Optional
Type: 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.

<AccessToken ref="request.queryparam.authorization_code"></AccessToken>
Default: N/A
Presence: Optional
Type: String

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

<AccessToken ref="request.queryparam.refresh_token"></AccessToken>
Default: N/A
Presence: Optional
Type: String

Flow variables

When an access token, refresh token, or authorization token is granted or validated by a policy, the following attributes from the token's profile are set as variables. These variables are then available to other policies or code executing in the same Flow. For example, you might need to access these variables in another policy to enable custom behavior based on the scope associated with the access token.

The GetOAuthV2Info policy also 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

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{custom_attribute_name}

Access token variables

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

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}.{custom_attribute_name}

Refresh token variables

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

Schema

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

Related topics

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)