Send Docs Feedback

Customizing tokens and auth codes

About customizing tokens and auth codes

Apigee Edge generates and distributes OAuth access tokens, refresh tokens, and authorization codes to apps. Edge stores those tokens and codes and uses them to authorize consumer apps. 

When Edge generates these OAuth artifacts, it also generates a profile that contains metadata related to the token or code. For example, the default access token profile contains name/value pairs that define expiration time, the associated app and developer, and so on.

The JSON representation of an Edge access token looks like the following:

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

Sometimes its useful to add custom attributes to an access token. For example, you might wish to embed a department name, a customer ID, or, more technically, a session identifier. You can also get and set these custom attributes at runtime using policies (as explained below). 

Customizing tokens with the OAuthV2 policy

You can configure custom token attributes directly in the OAuthV2 policy that generates the tokens or auth codes. 

<Attributes> 
  <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
  <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Where display is set to true, custom attributes are returned in the response, where they may be viewable by the app end user.

Where display is set to false, custom attributes are stored in the data store, but are not returned in the response message.

For example, to add the User-Agent associated with the request to an access token:

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken
  </Operation>
  <ExpiresIn>1000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="user-agent" ref="request.header.user-agent" display="false"></Attribute>
  </Attributes>
</OAuthV2>

Getting and setting custom attributes at runtime

In some situations, you will need to update the profile of an access token at runtime while an API call is being processed on Apigee Edge. To help with this, Apigee provides policies for getting and setting token attributes. For more information, see Get OAuth V2 Info policy and Set OAuth V2 Info policy. Use these policies when you need tokens to be updated at runtime, such as at the time when the token or code is generated by Apigee Edge.

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 an ExtractVariables policy.

You can also use Edge APIs to manage a token's profile. See the API documentation for the Update OAuth 2.0 Access Token method.

Training video

Apigee offers free online training for API developers. Simply register for Foundational Training: Create and Manage APIs. Custom access token attributes is covered in Part 6, Lessons 5 of this Apigee Academy free course. 

Help or comments?