OAuthV2 policy

About | Samples | Element reference | Error codes | Schema | Related topics | Variables

What

OAuthV2 is a multi-faceted policy for performing OAuth 2.0 grant type operations. This is the primary policy used to configure OAuth 2.0 endpoints on Apigee Edge.

If you want to learn more about OAuth on Apigee Edge, see the OAuth home page. It provides links to resources, samples, videos, and more. See the advanced OAuth sample on GitHub for a good demonstration of how this policy is used in a working application. 

Where

Place this policy on custom API proxy flows to generate access tokens, refresh tokens, authorization codes, to perform token validation, and other operations. For example, you might put this policy on an API proxy endpoint called /authorizationcode for apps to request authorization codes. Likewise, you might put this policy on an API proxy endpoint called /token to generate an access token when that endpoint is called.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request              
                Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

Samples

VerifyAccessToken

Use this OAuthV2 policy configuration to verify that an access token submitted to Apigee Edge is valid. When this policy operation is triggered, Edge looks for a valid access token in the request. If the access token is valid, the request is allowed to proceed. If invalid, all processing stops and an error is returned in the response. 

This OAuthV2 policy performs the VerifyAccessToken operation.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Tokens/>
</OAuthV2>

Note that only bearer (access) tokens are supported. MAC tokens are not supported.

Apps must pass the access token in the Authorization HTTP request header. For example:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Generate access token and return as response

Generate an access token for the supplied authorization code, resource owner password credentials, and client credentials grant types. All of the required and optional elements shown in the example are described in this policy reference.

The presence of the </GenerateResponse> element tells the policy to return the access token directly in a response. If this element is not present, then the flow processing continues without returning.

For the implicit grant type, use the GenerateAccessTokenImplicitGrant policy operation.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1000</ExpiresIn>
   <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn> <!-- Optional --> 
    <SupportedGrantTypes> <!-- Optional -->
        <GrantType>authorization_code</GrantType>
        <GrantType>password</GrantType>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType> flow.variable </GrantType> <!-- Optional -->   
    <ClientId> flow.variable </ClientId> <!-- Optional -->    
    <RedirectUri> flow.variable </RedirectUri> <!-- Optional -->    
    <Scope> flow.variable </Scope> <!-- Optional -->    
    <AppEndUser> flow.variable </AppEndUser> <!-- Optional -->    
    <Code> flow.variable </Code> <!-- Optional -->    
    <UserName> flow.variable </UserName> <!-- Optional -->   
    <PassWord> flow.variable </PassWord> <!-- Optional --> 
    <Attributes> <!-- Optional -->
        <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>
    <GenerateResponse/>
    <ExternalAuthorization>true|false</ExternalAuthorization>
</OAuthV2> 

Sample requests:

A request to an endpoint containing this policy must include a basic authorization header with a base-64 encoded Consumer ID + Consumer Secret, and x-www-form-urlencoded parameters specified in the request body. The examples below show how to form the request for each grant type.

Sending all the parameters in as x-www-form-urlencoded is the default configuration specified in the IETF OAuth 2.0 specification. Apigee Edge lets you specify in the policy that some or all of the parameters will be either Header or Query parameters, in which case, Apigee Edge expects those parameters to be sent in as such. See "Specifying request variable locations" for more information.

For the authorization code grant type:

$ curl -i -H 'ContentType: x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'code=I9dMGHAN&redirect_uri=http://weatherapp.com&grant_type=authorization_code' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

For the client credentials grant type:

$ curl -i -H 'ContentType: x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'

For the resource owner password credentials grant type:

$ curl -i -H 'ContentType: x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=password&username=the-user-name&password=the-users-password' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'
	  

Generate authorization code and return as response

Generate an authorization code. All of the required and optional elements shown in the example are described in this policy reference.

The presence of the </GenerateResponse> element tells the policy to return the authorization code directly in a response. If this element is not present, then the flow processing continues without returning.

This operation is only used with the authorization code grant type flow. In that flow, an the client app needs to obtain an access code and then exchange the code for an access token in a separate step. For more information about this grant type, see Implementing the authorization code grant type.

Sample policy:

<OAuthV2 name="GetAuthCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <ResponseType> flow.variable </ResponseType>  <!-- Optional -->
    <ClientId> flow.variable </ClientId> <!-- Optional -->
    <RedirectUri> flow.variable </RedirectUri> <!-- Optional -->
    <Scope> flow.variable </Scope> <!-- Optional -->
    <State>flow.variable</State>    <!-- Optional -->
    <Attributes> <!-- Optional -->
        <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>
    <GenerateResponse/>
</OAuthV2>

Sample request:

https://docs-test.apigee.net/oauth/authorizationcode?response_type=code&client_id=XYZ123&redirect_uri=www.example.com&scope=READ

Note that scope is optional, the rest of the parameters are mandatory.

Generate implicit access token and return as response

With the implicit grant type flow, a client requests an access token directly, without the need for an authorization code. To generate an access token with the implicit grant type, use the GenerateAccessTokenImplicitGrant operation. This operation validates the request (which includes user credentials) and returns an access token if the request is valid, or an error if it isn't. 

Sample policy:

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <ExpiresIn>1000</ExpiresIn>
    <ResponseType>flow.variable</ResponseType> <!-- Optional -->    
    <ClientId>flow.variable</ClientId> <!-- Optional -->    
    <RedirectUri>flow.variable</RedirectUri> <!-- Optional -->    
    <Scope>flow.variable</Scope> <!-- Optional -->    
    <State>flow.variable</State> <!-- Optional -->    
    <AppEndUser>flow.variable</AppEndUser> <!-- Optional -->
    <Attributes> <!-- Optional -->
        <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>
</OAuthV2>

Sample Request:

https://docs-test.apigee.net/oauth/token_implicit?response_type=token&client_id=ABC123&redirect_uri=www.example.com&state=ABC123&scope=READ&app_enduser=joe123

Note that scope, state, and app_enduser are optional. The other parameters are mandatory.

Refresh an access token and return as response

Certain grant types allow for refresh tokens. A refresh token is a form of credential that lets the bearer request a new access token.

The presence of the </GenerateResponse> element tells the policy to return the refresh token directly in a response. If this element is not present, then the flow processing continues without returning.

Sample policy:

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn> <!--Optional-->
    <ExpiresIn>1000</ExpiresIn>
    <RefreshToken>flow.variable</RefreshToken> <!-- Optional -->
    <GrantType>flow.variable</GrantType> <!-- Optional -->
    <ReuseRefreshToken>true | false</ReuseRefreshToken> <!--Optional-->
    <GenerateResponse/>
</OAuthV2>

 

https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken?grant_type=refresh_token -X POST -d "refresh_token=my-refresh-token" -H "Content-type: application/x-www-form-urlencoded

 

ValidateToken

Validates a token that was previously invalidated (revoked).

Sample policy:

<OAuthV2 name="ValidateToken">
   <Operation>ValidateToken</Operation>
      <Tokens>
         <Token type="accesstoken" cascade="true">flow.variable</Token>
         <Token type="refreshtoken" cascade="true">flow.variable</Token>
    </Tokens>
</OAuthV2>

The token type can only be accesstoken or refreshtoken, and the type is mandatory.

flow.variable can be in header or queryparam or formparam, in the format request.{ formparam | queryparam | header }.variable_name (mandatory)

cascade  can only be booleanvalues(optional)

Default Behaviors(if no cascade attribute is specified) :


  • Validation of accesstoken will default cascade validation or approval of the associated refreshtoken.
  • Validation  of refreshtoken will default cascade validation or approval of the associated accesstoken.

 

InvalidateToken

Invalidates (revokes) a token.

Sample policy:

<OAuthV2 name="InvalidateToken">
   <Operation>InvalidateToken</Operation>
      <Tokens>
         <Token type="accesstoken" cascade="true">flow.variable</Token>
         <Token type="refreshtoken" cascade="true">flow.variable</Token>
    </Tokens>
</OAuthV2>

The token type can only be accesstoken or refreshtoken, and the type is mandatory.

flow.variable can be in header or queryparam or formparam, in the format request.{ formparam | queryparam | header }.variable_name (mandatory)
 

cascade  can only be booleanvalues(optional)

Default Behaviors(if no cascade attribute is specified) :


  • Invalidation of accesstoken will default cascade invalidation or revoke of the associated refreshtoken.
  • Invalidation  of refreshtoken will default cascade invalidation or revoke of the associated accesstoken.

 

Policy reference

The policy reference describes the elements and attributes of the OAuthV2 policy.

The way you configure this policy, and the elements you need to specify, depend on which operation you want the policy to perform. For example, if you are implementing the authorization code grant type, then you will require four separate OAuthV2 policies to perform authorization code generation, access code generation, access code validation, and refresh token generation. This reference lists all of the elements that can be used with this policy.

If you want to see configurations for specific grant type use cases, refer to the OAuth home page for a list of grant type implementations. In particular, see the advanced OAuth sample on GitHub for a good demonstration of how this policy is used in a working application. 

The sample policy shown below is one of many possible configurations. This sample shows an OAuthV2 policy configured for the GenerateAccessToken operation. It includes required and optional elements. Refer to the element descriptions in this section for details.

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>1000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
   <GrantType>authorization_code</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Code>request.queryparam.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
</OAuthV2>
    

<OAuthV2> attributes

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">
Attribute Description Default 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.

See also the <DisplayName> element.

N/A Required
async

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

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

false Optional
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies. For example, when a quota is exceeded, an error will be raised.

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

<AppEndUser> element

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

In cases where the app end user ID must be sent to the authorization server, this element lets you specify where Edge should look for the end user ID. For example, it could be sent as a query parameter or in an HTTP header.

For example request.queryparam.app_enduser indicates that the AppEndUser should be present as a query parameter, as, for example, ?app_enduser=ntesla@theramin.com. To require the AppEndUser in an HTTP header, for example, set this value to request.header.app_enduser.

Providing this setting enables you to include an app end user ID in the access token. This feature is useful if you want to be able to retrieve or revoke OAuth 2.0 access tokens by end user ID. For more information, see Enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, app id, or both.

Default:

N/A

Presence:

Optional

Type: String
Valid values:

Any flow variable accessible to the policy at runtime.

Used with operations:
  • All

<Attributes/Attribute>

<Attributes>    <!-- Optional -->
    <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>

<Attribute> can take a value from a flow variable or a default value which is specified in the policy. If both are specified, value specified in flow variable is taken. The optional display attribute can be set to true to false. If set to true, the attribute will not be shown in the response. Default value is false.

Default:

N/A

Presence:

optional

Valid values:
  • name -The attribute name
  • ref - The value of the attribute. Can come from a flow variable.
  • display - If set to true, the attribute will not be shown in the response. Default value is false.
Used with operations:
  • GenerateAccessToken
  • GenerateAuthorizationCode
  • GenerateAccessTokenImplictGrant

<ClientId> element

<ClientId>request.queryparam.client_id</ClientId>

In several cases, the client app must send the client ID to the authorization server. This element lets you specify where Edge should look for the client ID. For example, it could be sent as a query parameter or in an HTTP header.

The variable request.queryparam.client_id indicates that the client_id should be present as a query parameter, as, for example, ?client_id=AfGlvs9. To require the ClientId in an HTTP header, for example, set this value to request.header.client_id.

Default:

N/A

Presence:

Optional

Type: String
Valid values: Any flow variable accessible to the policy at runtime
Used with operations:
  • GenerateAccessTokenImplicit
  • GenerateAuthorizationCode

<Code> element

<Code>request.queryparam.code</Code>

In the authorization grant type flow, the client must submit an authorization code to the authorization server (Apigee Edge). This element lets you specify where Edge should look for the authorization code. For example, it could be sent as a query parameter or in an HTTP header.

The variable, request.queryparam.auth_code indicates that the authorization code should be present as a query parameter, as, for example, ?auth_code=AfGlvs9. To require the authorization code in an HTTP header, for example, set this value to request.header.auth_code.

Default:

N/A

Presence:

optional

Type: String
Valid values: Any flow variable accessible to the policy at runtime
Used with operations: GenerateAccessToken (with authorization code grant type only)

<ExpiresIn> element

<ExpiresIn>1000</ExpiresIn> 

Enforces the expiry time of access tokens, refresh tokens, and authorization codes in milliseconds. The expiry time value is a system generated value plus the <ExpiresIn> value. If <ExpiresIn> is set to -1, the token or code is given an infinite lifetime. If <ExpiresIn> is not specified, the system applies a default value configured at the system level. Contact Apigee Support for more information about default system settings.

The expiry time can also be set at runtime using a reference to a flow variable. The following examples shows how to do this, and specify a default value as well.

<ExpiresIn ref="flow.variable">
    {default_value}
</ExpiresIn>

Default:

If not specified, the system applies a default value configured at the system level.

Presence:

Optional

Type: Integer
Valid values: Any integer, including -1 (which indicates an infinite expiry time).
Used with operations
  • GenerateAccessToken
  • GenerateAccessTokenImplicitGrant
  • GenerateAuthorizationCode
  • RefreshAccessToken

<GenerateResponse> element

<GenerateResponse />

Indicates that the policy defines an endpoint, and that no further processing of the request message should take place. The policy itself generates a response and returns it to the requesting client app. Remove this element if you want the request message to be passed to the target endpoint.

Default:

N/A

Presence:

Optional

Type: string
Valid values: N/A
Used with operations:
  • All

<Operation> element

<Operation>GenerateAuthorizationCode</Operation>

The OAuth 2.0 operation executed by the policy. See also the Grant type and operations reference below.

Default:

N/A

Presence:

Required

Type: String
Valid values:
  • GenerateAccessToken - Generates an access token. See the GenerateAccessToken sample above.
  • GenerateAccessTokenImplicitGrant - Generates an access token for the implict grant type. See the GenerateAccessTokenImplicitGrant sample above.
  • GenerateAuthorizationCode - Generates an auth code. Used with the authorization code grant type. See the GenerateAuthorizationCode sample above.
  • RefreshAccessToken - Exchange a new access token for a refresh token. See the RefreshAccessToken sample above.
  • VerifyAccessToken - Verifies that an access token sent in a request is valid. See the VerifyAccessToken sample above and "Verifying access tokens". 
  • InvalidateToken - Revokes an access token. When revoked, clients cannot call the protected API. See also Approving and revoking access tokens.
  • ValidateToken - Reinstates or "approves" an access token that was previously revoked. See also Approving and revoking access tokens.

<Password> element

<PassWord>request.queryparam.password</PassWord>

In cases where the app user's password must be sent to the authorization server, this element lets you specify where Edge should look for the password. For example, it could be sent as a query parameter or in an HTTP header.

For example request.queryparam.password indicates that the Password should be present as a query parameter, as, for example, ?password=changeit. To require the Password in an HTTP header, for example, set this value to request.header.password.

Default:

N/A

Presence:

Optional

Type: String
Valid values: Any flow variable available to the the policy at runtime.
Used with operations: GenerateAccessToken

<RedirectUri> element

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

In several cases, the client app must send the redirect URI (also called the callback URL) to the authorization server. This element lets you specify where Edge should look for the redirect URI. For example, it could be sent as a query parameter or in an HTTP header.

The variable request.queryparam.redirect_uri indicates that the RedirectUri should be present as a query parameter, as, for example, ?redirect_uri=login.myapp.com. To require the RedirectUri in an HTTP header, for example, set this value to request.header.redirect_uri.

Default:

N/A

Presence:

Optional

Type: String
Valid values: Any flow variable accessible in the policy at runtime
Used with operations:
  • GenerateAuthorizationCode
  • GenerateAccessCode
  • GenerateAccessTokenImplicit

<ReuseRefreshToken> element

<ReuseRefreshToken>true</ReuseRefreshToken>

When set to true, the existing refresh token is reused until it expires. If false, a new refresh token is issued by Apigee Edge when a valid refresh token is presented.

Default:

false

Presence:

optional

Type: boolean
Valid values:

true or false

Used with operations:
  • RefreshAccessToken

<RefreshTokenExpiresIn> element

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Enforces the expiry time of refresh tokens in milliseconds. The expiry time value is a system generated value plus the <RefreshTokenExpiresIn> value. If <RefreshTokenExpiresIn> is set to -1, the refresh token is given an infinite lifetime. If <RefreshTokenExpiresIn> is not specified, the system applies a default value configured at the system level. Contact Apigee Support for more information about default system settings.

The expiry time can also be set at runtime using a reference to a flow variable, as follows.

<RefreshTokenExpiresIn ref="flow.variable">
    {default_value}
</RefreshTokenExpiresIn>

Default:

If not specified, the system applies a default value configured at the system level.

Presence:

Optional

Type: Integer
Valid values:

Any integer, including -1 (which indicates an infinite expiry time).

Used with grant types
  • Authorization code
  • Resource owner password
Used with operations
  • GenerateAccessToken
  • RefreshAccessToken

<Scope> element

  <Scope>request.queryparam.scope</Scope> 

In cases where the client app must send the scope to the authorization server, this element lets you specify where Edge should look for the scope values. For example, it could be sent as a query parameter or in an HTTP header.

The variable request.queryparam.scope indicates that the scope should be present as a query parameter, as, for example, ?scope=READ. To require the scope in an HTTP header, for example, set this value to request.header.scope. See also Working with scopes.

Default:

N/A

Presence:

Optional

Type: String
Valid values: Any flow variable accessible to the policy at runtime.
Used with operations:
  • VerifyAccessToken
  • GenerateAccessToken
  • GenerateAccessTokenImplicitGrant
  • GenerateAuthorizationCode

<State> element

<State>request.queryparam.state</State>

In cases where the client app must send the state information to the authorization server, this element lets you specify where Edge should look for the state values. For example, it could be sent as a query parameter or in an HTTP header. The state value is typically used as a security measure to prevent CSRF attacks.

For example request.queryparam.state indicates that the state should be present as a query parameter, as, for example, ?state=HjoiuKJH32. To require the state in an HTTP header, for example, set this value to request.header.state.

Default:

N/A

Presence:

Optional

Type: String
Valid values: Any flow variable accessible to the policy at runtime
Used with operations:
  • GenerateAccessTokenImplicitGrant
  • GenerateAuthorizationCode

<SupportedGrantTypes> element

<SupportedGrantTypes>    
    <GrantType>authorization_code</GrantType>   
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Specifies the grant types supported by an OAuth token endpoint on Apigee Edge. An endpoint may support multiple grant types (that is, a single endpoint can be configured to distribute access tokens for multiple grant types.) For more on endpoints, see Configuring OAuth endpoints and policies. The grant type is passed in token requests in a grant_type parameter. If no supported grant types are specified, then the only allowed grant type is authorization_code.

Default:

authorization _code

Presence:

Required

Type: String
Valid values:

All supported grant types:

  • client_credentials
  • authorization_code
  • password
  • implicit
Used with operations
  • GenerateAccessToken

<Tokens>/<Token> element

Used with the ValidateToken and InvalidateToken operations. See also Approving and revoking access tokens. The <Token> element identifies the flow variable that defines the source of the token to be revoked. If developers are expected to submit access tokens as query parameters named access_token, for example, use request.queryparam.access_token.

<Username> element

<UserName>request.queryparam.user_name</UserName>

In cases where the app user name must be sent to the authorization server, this element lets you specify where Edge should look for the end user name. For example, it could be sent as a query parameter or in an HTTP header.

For example request.queryparam.username indicates that the username should be present as a query parameter, as, for example, ?username=joe. To require the UserName in an HTTP header, for example, set this value to request.header.username.

Default:

N/A

Presence:

Optional

Type: String
Valid values: Any variable setting.
Used with operations: All

Verifying access tokens

Once a token endpoint is set up for an API proxy, a corresponding OAuthV2 policy that specifies the VerifyAccessToken operation is attached to the Flow that exposes the protected resource.

For example, to ensure that all requests to an API are authorized, the following policy enforces access token verification:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

The policy is attached to the API resource to be protected. To ensure that all requests to an API are verified, attach the policy to the ProxyEndpoint request PreFlow, as follows:

<PreFlow>
  <Request>
	<Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

The following optional elements can be used to override the default settings for the VerifyAccessToken operation.

Name Description
Scope

A space-delimited list of scopes. Verification will succeed if at least one of the scopes listed is present in the access token. For example, the following policy will check the access token to ensure that it contains at least one of the scopes listed. If READ or WRITE is present, verification will succeed.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken The variable where the access token is expected to be located. For example request.queryparam.accesstoken. By default, the access token is expected to be presented by the app in the Authorization HTTP header,  according to the OAuth 2.0 specification. Use this setting if the access token is expected to be presented in a non-standard location, such as a query parameter, or an HTTP header with a name other than Authorization.

For instructions on obtaining and verifying tokens, see OAuth.

Specifying request variable locations

For each grant type, the policy makes assumptions about the location or required information in request messages. These assumptions are based on the the OAuth 2.0 specification. If your apps need to deviate from the OAuth 2.0 specification, then you can specify the expected locations for each parameter. For example, when handling an authorization code, you can specify the location of the authorization code, the client ID, the redirect URI, and the scope. These can be specified as HTTP headers, query parameters, or form parameters.

The example below demonstrates how you can specify the location of required authorization code parameters as HTTP headers:

  <GrantType>request.header.grant_type</GrantType>

  <Code>request.header.code</Code>

  <ClientId>request.header.client_id</ClientId>

  <RedirectUri>request.header.redirect_uri</RedirectUri>

  <Scope>request.header.scope</Scope>

Or, if necessary to support your client app base, you can mix and match headers and query parameters:

  <GrantType>request.header.grant_type</GrantType>

  <Code>request.header.code</Code>

  <ClientId>request.queryparam.client_id</ClientId>

  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>

  <Scope>request.queryparam.scope</Scope>

Only one location can be configured per parameter.

Flow variables

The flow variables defined in this table are populated when the respective OAuth policies are executed, and hence are available to other policies or applications executing in the API proxy flow.

VerifyAccessToken operation

These variables are set when the VerifyAccessToken policy operation executes.

Variables Description
organization_name  
organization_name  
developer.id  
developer.app.name  
client_id  
grant_type  
token_type  
access_token  
accesstoken.{custom_attribute}  
issued_at  
expires_in  
status  
scope  
apiproduct.<custom_attribute_name>*  
apiproduct.name*  

* API product variables

 

GenerateAuthorizationCode operation

These variables are set when the GenerateAuthorizationCode policy operation executes successfully:

Variable Description
oauthv2authcode.{policy_name}.code The authorization code generated by the policy
oauthv2authcode.{policy_name}.redirect_uri  
oauthv2authcode.{policy_name}.scope  
oauthv2authcode.{policy_name}.client_id  

 

GenerateAccessToken and GenerateAccessTokenImplicitGrant

These variables are set when the GenerateAccessToken policy operation executes successfully for the authorization code, password, and client credentials grant types:

Variable Description
oauthv2accesstoken.{policy_name}.access_token The access token generated by the policy
oauthv2accesstoken.{policy_name}.token_type  
oauthv2accesstoken.{policy_name}.expires_in  
oauthv2accesstoken.{policy_name}.refresh_token The refresh token generated by the policy

 

RefreshAccessToken operation

These variables are set when the RefreshAccessToken policy operation executes successfully:

Variable Description
oauthv2accesstoken.{policy_name}.access_token The access token generated by the policy.
oauthv2accesstoken.{policy_name}.token_type  
oauthv2accesstoken.{policy_name}.expires_in  
oauthv2accesstoken.{policy_name}.refresh_token The refresh token generated by the policy. The value depends on the value of the <ReuseRefreshToken> element.

Error codes

The default format for error codes returned by Policies is:

{
  "code" : " {ErrorCode} ",
  "message" : " {Error message} ",
  "contexts" : [ ]
}

The OAuthV2 Policy type defines the following error codes:

Error Code Message
FailedToResolveOAuthConfig Failed to resolve oauth config {0}
OperationRequired Operation required
InvalidOperation Operation {0} is invalid
InsufficientScope Required scope(s) : {0}
FailedToResolveClientId Failed to resolve client id variable {0}
FailedToResolveAccessToken Failed to resolve access token variable {0}
FailedToResolveRefreshToken Failed to resolve refresh token variable {0}
FailedToResolveToken Failed to resolve token variable {0}
FailedToResolveAuthorizationCode Failed to resolve authorization code variable {0}
ExpiresInNotApplicableForOperation ExpiresIn element is not valid for operation {0}
RefreshTokenExpiresInNotApplicableForOperation RefreshToken ExpiresIn element is not valid for operation {0}
InvalidValueForExpiresIn Invalid value for ExpiresIn element for operation {0}
InvalidValueForRefreshTokenExpiresIn Invalid value for Refresh Token ExpiresIn element for operation {0}
InvalidGrantType Invalid grant type: {0}
GrantTypesNotApplicableForOperation Grant types are not applicable for operation {0}
UnSupportedGrantType Unsupported Grant Type: {0}
InvalidParameter Invalid required paramater: {0}
MissingParameter Missing required paramater: {0}
SpecifyValueOrRefApiKey Specify Api Key as value or ref in stepDefinition {0}
SpecifyAPIProduct Specify the API Product to get details {0}
FailedToFetchApiProduct Failed to fetch api product for key {0}
FailedToResolveAPIKey Failed to resolve API Key variable {0}
FailedToResolveAPIProduct Failed to resolve API product variable {0}
InvalidTokenType Valid token types : {0}, Invalid toke type {1} in stepDefinition {2}
TokenValueRequired Token value is required in stepDefinition {0}
FailedToResolveRealm Failed to resolve realm {0}

Policy schema

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

Working with the default OAuth configuration

Each organization (even a free trial org) on Apigee Edge is provisioned with an OAuth token endpoint. The endpoint is preconfigured with policies in the API proxy called oauth. You can begin using the token endpoint as soon as you create an account on Apigee Edge. For details, see Configuring OAuth endpoints and policies.

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