Was this helpful?

Apigee Edge generates and manages a set of OAuth resources for apps. Depending on the OAuth configuration for an organization, Apigee Edge will generate and manage access tokens, authorization codes, and refresh tokens. For each OAuth resource that it generates, Edge also creates and stores a profile.

The GetOauthV2Info policy type enables you to get attributes of tokens and to make them available to policies and code executing in an API proxy. This policy type can be useful when you need to configure dynamic, conditional behavior based on a value in an access token.

An access token has the following JSON representation on Apigee Edge:

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[FreeProduct]",
  "expires_in" : "3599",
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

The properties of an access token profile are set as variables whenever a token 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.

The AccessToken element value is set to the name of the variable where the access token can be located: either in the request message, or in some other variable where it might be populated by am ExtractVariables policy.

Samples

You can provide a reference to a variable that contains the token. The policy configuration below will obtain the access token by reference to query parameter called access_token. The policy expects the access token to be presented by the app as a query parameter named access_token. The policy will use that access token to retrieve the associated profile from Apigee Edge's token store. The access token's profile will then be used to populate a set of variables.

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

The oauthv2accesstoken variables are then populated with values specific to the access token.

The values of the variables could then be accessed, for example, by JavaScript. For example, to retrieve the scope(s) associated with an access token using JavaScript:

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

You can also retrieve attributes of an access token by using a policy of type GetOAuthV2Info and referring to a variable set by the execution of any OAuthV2 policy.

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.

Retrieving authorization code attributes

As with access tokens, you can retrieve authorization code attributes by using the AuthorizationCode element in a policy of type GetOAuthV2Info

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

For example:

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

Retrieving refresh token attributes

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

For example:

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

Configuring the GetOAuthV2Info policy

Configure a GetOAuthV2Info policy using the following elements.

Field Name Description
Name (Mandatory) Name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

 

AccessToken (Optional) Use this element to retrieve the profile for an OAuth 2.0 access token.
AuthorizationCode (Optional) Use this element to retrieve the profile for an OAuth 2.0 authorization code.
RefreshToken (Optional) Use this element to retrieve the profile for an OAuth 2.0 refresh token.

Policy-specific variables

When an access token is granted or validated by a policy, the following attributes of the access token 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.

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}

To support backward compatibility , the above flow variables prefixed with oauthv2accesstoken.{policy_name} are also available.

Policy schema

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

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?)