OAuthV2 policy

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

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.

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

Samples

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

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

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

See also "Encoding basic authentication credentials".

Element reference

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

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">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> attributes

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

The following table describes attributes that are common to all policy parent elements:

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

<AccessToken> element

<AccessToken>request.header.access_token</AccessToken>

By default, VerifyAccessToken expects the access token to be sent in the Authorization header. You can change that default using this element. For example request.queryparam.access_token indicates that the access token should be present as a query parameter named access_token.

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

<AccessTokenPrefix> element

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

By default, VerifyAccessToken expects the access token to be sent in an Authorization header as a Bearer token. For example:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Currently, Bearer is the only supported prefix.

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

<Attributes/Attribute>

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

Use this element to add custom attributes to an access token or authorization code. For example, you may wish to embed a user ID or session identifier in an access token that can be extracted and checked at runtime.

This element lets you specify a value in a flow variable or from a literal string. If you specify both a variable and a string, the value specified in the flow variable is used. If the variable cannot be resolved, then the string is the default.

For more information on using this element, see Customizing Tokens and Authorization Codes.

Displaying or hiding custom attributes in the response

Remember that if you set the GenerateResponse element of this policy to true, the full JSON representation of the token is returned in the response, including any custom attributes that you set. In some cases, you might want to hide some or all of your custom attributes in the response so that they are not visible to client apps.

By default, custom attributes do appear in the response. If you want to hide them, you can set the display parameter to false. For example:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

The value of the display attribute is not persisted. Let's say you generate an access token with custom attributes that you want to hide in the generated response. Setting display=false accomplishes that goal. However, if a new access token is generated later using a refresh token, the original custom attributes from the access token will show up in the refresh token response. This is because Edge does not remember that the display attribute was originally set to false in the generate access token policy--the custom attribute is simply part of the access token's metadata.

You will see the same behavior if you add custom attributes to an authorization code--when an access token is generated using that code, those custom attributes will show up in the access token response. Again, this may not be the behavior you intend.

To hide custom attributes in these cases, you have these choices:

• Explicitly reset the custom attributes in the refresh token policy and set their display to false. In this case, you may need to retrieve the original custom values from the original access token using the GetOAuthV2Info policy.
• Use a postprocessing JavaScript policy to manually extract any custom attributes that you do not want to see in the response.

See also Customizing Tokens and Authorization Codes.

<ClientId> element

<ClientId>request.formparam.client_id</ClientId>

In several cases, the client app must send the client ID to the authorization server. This element specifies that Apigee should look for the client ID in the flow variable request.formparam.client_id. Setting ClientId to any other variable is not supported. See also Requesting access tokens and authorization codes.

<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, HTTP header, or form parameter (the default).

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. See also Requesting access tokens and authorization codes.

<ExpiresIn> element

<ExpiresIn>10000</ExpiresIn> 

Enforces the expiry time of access tokens and authorization codes in milliseconds. (For refresh tokens, use <RefreshTokenExpiresIn>.) The expiry time value is a system-generated value plus the <ExpiresIn> value. If <ExpiresIn> is set to -1, the token or code expires as per the maximum OAuth access token expiration. If <ExpiresIn> is not specified, the system applies a default value configured at the system level.

The expiry time can also be set at runtime using either a hard-coded, default value or by referencing a flow variable. For example, you can store a token expiration value in a key value map, retrieve it, assign it to a variable, and reference it in the policy. For example, kvm.oauth.expires_in.

With Apigee Edge for Public Cloud, Edge keeps the following entities in cache for a minimum of 180 seconds after the entities are accessed.

• OAuth access tokens. This means that a revoked token may still succeed for up to three minutes, until its cache limit expires.
• Key Management Service (KMS) entities (Apps, Developers, API Products).
• Custom attributes on OAuth tokens and KMS entities.

The following stanza specifies a flow variable and a default value as well. Note that the flow variable value takes precedence over the specified default value.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge does not support a way to force the expiration of a token after it has been created. If you need to force token expiration (for example, based on a condition), a possible solution is described in this Apigee Community post.

By default, expired access tokens are purged from the Apigee Edge system automatically 3 days after expiration. See also Purging access tokens

Private Cloud: For an Edge for Private Cloud installation, the default value is set by the conf_keymanagement_oauth_auth_code_expiry_time_in_millis property. To set this property:

1. Open the message-processor.properties file in an editor. If the file does not exist, create it:

   vi /opt/apigee/customer/application/message-processor.properties

2. Set the property as desired:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Make sure the properties file is owned by the "apigee" user:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Restart the Message Processor.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ExternalAccessToken> element

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Tells Apigee Edge where to find an external access token (an access token not generated by Apigee Edge).

The variable request.queryparam.external_access_token indicates that the external access token should be present as a query parameter, as, for example, ?external_access_token=12345678. To require the external access token in an HTTP header, for example, set this value to request.header.external_access_token. See also Using Third-Party OAuth Tokens.

<ExternalAuthorization> element

<ExternalAuthorization>true</ExternalAuthorization>

If this element is false or not present, then Edge validates the client_id and client_secret normally against the Apigee Edge authorization store. Use this element when you want to work with third-party OAuth tokens. For details on using this element, see Using Third-Party OAuth Tokens.

<ExternalAuthorizationCode> element

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Tells Apigee Edge where to find an external auth code (an auth code not generated by Apigee Edge).

The variable request.queryparam.external_auth_code indicates that the external auth code should be present as a query parameter, as, for example, ?external_auth_code=12345678. To require the external auth code in an HTTP header, for example, set this value to request.header.external_auth_code. See also Using Third-Party OAuth Tokens.

<ExternalRefreshToken> element

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Tells Apigee Edge where to find an external refresh token (a refresh token not generated by Apigee Edge).

The variable request.queryparam.external_refresh_token indicates that the external refresh token should be present as a query parameter, as, for example, ?external_refresh_token=12345678. To require the external refresh token in an HTTP header, for example, set this value to request.header.external_refresh_token. See also Using Third-Party OAuth Tokens.

<GenerateResponse> element

<GenerateResponse enabled='true'/>

If set to true, the policy generates and returns a response. For example, for GenerateAccessToken, the response might be like:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

If false, no response is sent. Instead, a set of flow variables are populated with values related to the policy's function. For example, a flow variable called oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code gets populated with the newly minted auth code. Note that expires_in is expressed in seconds in the response.

<GenerateErrorResponse> element

<GenerateErrorResponse enabled='true'/>

If set to true, the policy generates and returns a response if the ContinueOnError attribute is set to true. If false (the default), no response is sent. Instead, a set of flow variables are populated with values related to the policy's function.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Tells the policy where to find the grant type parameter that is passed in a request. Per the OAuth 2.0 specification, the grant type must be supplied with requests for access tokens and authorization codes. The variable can be a header, query parameter, or form parameter (default).

For example request.queryparam.grant_type indicates that the Password should be present as a query parameter, as, for example, ?grant_type=password. To require the grant type in an HTTP header, for example, set this value to request.header.grant_type. See also Requesting access tokens and authorization codes.

<Operation> element

<Operation>GenerateAuthorizationCode</Operation>

The OAuth 2.0 operation executed by the policy.

<PassWord> element

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

This element is used with the password grant type only. With the password grant type, user credentials (password and username) must be made available to the OAuthV2 policy. The <PassWord> and <UserName> elements are used to specify variables where Edge can find these values. If these elements are not specified, the policy expects to find the values (by default) in form parameters named username and password. If the values are not found, the policy throws an error. You can use the <PassWord> and <UserName> elements to reference any flow variable containing the credentials.

For example, you can pass the password in a token request using a query parameter and set the element like this: <PassWord>request.queryparam.password</PassWord>. To require the password in an HTTP header, set this value to request.header.password.

The OAuthV2 policy doesn't do anything else with these credential values; Edge is simply verifying that they are present. It is up to the API developer to retrieve the values request and send them to an identity provider before the token generation policy executes.

See also Requesting access tokens and authorization codes.

<RedirectUri> element

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

Specifies where Edge should look for the redirect_uri parameter in the request.

About redirection URIs

Redirection URIs are used with the authorization code and implicit grant types. The redirect URI tells the authorization server (Edge) where to send an authorization code (for the auth code grant type) or access token (for the implicit grant type). It's important to understand when this parameter is required, when it is optional, and how it is used:

• (required) If a Callback URL is registered with the developer app that is associated with the request's client keys, and if the redirect_uri is present in the request, then the two must match exactly. If they do not match, an error is returned. For information on registering developer apps on Edge and specifying a Callback URL, see Register apps and manage API keys.

• (optional) If a Callback URL is registered, and the redirect_uri is missing from the request, then Edge redirects to the registered Callback URL.
• (required) If a Callback URL is not registered, then the redirect_uri is required. Note that in this case, Edge will accept ANY URL. This case can present a security issue, and therefore should only be used with trusted client apps. If client apps are not trusted, then the best practice is to always require the registration of a Callback URL.

You can send this parameter in a query parameter or in a 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. See also Requesting access tokens and authorization codes.

<RefreshToken> element

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

When requesting an access token using a refresh token, you must supply the refresh token in the request. This element lets you specify where Edge should look for the refresh token. For example, it could be sent as a query parameter, HTTP header, or form parameter (the default).

The variable request.queryparam.refreshtoken indicates that the refresh token should be present as a query parameter, as, for example, ?refresh_token=login.myapp.com. To require the RefreshToken in an HTTP header, for example, set this value to request.header.refresh_token. See also Requesting access tokens and authorization codes.

<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 expires as per the maximum OAuth refresh token expiration. If <RefreshTokenExpiresIn> is not specified, the system applies a default value configured at the system level. Contact Apigee Edge Support for more information about default system settings.

The expiry time can also be set at runtime using either a hard-coded, default value or by referencing a flow variable. For example, you can store a token expiration value in a key value map, retrieve it, assign it to a variable, and reference it in the policy. For example, kvm.oauth.expires_in.

The following stanza specifies a flow variable and a default value as well. Note that the flow variable value takes precedence over the specified default value.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Private Cloud: For an Edge for Private Cloud installation, the default value is set by the conf_keymanagement_oauth_refresh_token_expiry_time_in_millis property. To set this property:

1. Open the message-processor.properties file in an editor. If the file does not exist, create it:

   vi /opt/apigee/customer/application/message-processor.properties

2. Set the property as desired:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Make sure the properties file is owned by the "apigee" user:

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Restart the Message Processor.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ResponseType> element

<ResponseType>request.queryparam.response_type</ResponseType>

This element informs Edge which grant type the client app is requesting. It is used only with the authorization code and implicit grant type flows.

By default, Edge looks for the response type value in a response_type query parameter. If you wish to override this default behavior, use the <ResponseType> element to configure a flow variable containing the response type value. For example, if you set this element to request.header.response_type, Edge looks for the response type to be passed in the request header. See also Requesting access tokens and authorization codes.

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

<Scope> element

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

If this element is present in one of the GenerateAccessToken or GenerateAuthorizationCode policies, it is used to specify which scopes to grant the token or code. These values are typically passed to the policy in the request from a client app. You can configure the element to take a flow variable, giving you the option to choose how the scopes are passed in a request. In the following example, 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.

If this element appears in a "VerifyAccessToken" policy, then it is used to specify which scopes the policy should enforce. In this type of policy, the value must be a "hard coded" scope name -- you can't use variables. For example:

<Scope>A B</Scope>

See also Working with OAuth2 scopes and Requesting access tokens and authorization codes.

<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. See also See also Requesting access tokens and authorization codes.

<StoreToken> element

 <StoreToken>true</StoreToken> 

Set this element to true when the <ExternalAuthorization> element is true. The <StoreToken> element tells Apigee Edge to store the external access token. Otherwise, it will not be persisted.

<SupportedGrantTypes>/<GrantType> 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 Understanding OAuth endpoints. 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 types are authorization_code and implicit. See also the <GrantType> element (which is a higher-level element that is used to specify where Apigee Edge should look for the grant_type parameter that is passed in a client request. Edge will make sure that the value of the grant_type parameter matches one of the supported grant types).

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

This element is used with the password grant type only. With the password grant type, user credentials (password and username) must be made available to the OAuthV2 policy. The <PassWord> and <UserName> elements are used to specify variables where Edge can find these values. If these elements are not specified, the policy expects to find the values (by default) in form parameters named username and password. If the values are not found, the policy throws an error. You can use the <PassWord> and <UserName> elements to reference any flow variable containing the credentials.

For example, you can pass the username in a query parameter and set the <UserName> element like this: <UserName>request.queryparam.username</UserName>.To require the username in an HTTP header, set this value to request.header.username.

The OAuthV2 policy doesn't do anything else with these credential values; Edge is simply verifying that they are present. It is up to the API developer to retrieve the values request and send them to an identity provider before the token generation policy executes.

See also Requesting access tokens and authorization codes.

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.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

See also Verifying access tokens and Requesting access tokens and authorization codes.

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

The VerifyAccessToken operation executes, a large number of flow variables are populated in the proxy's execution context. These variables give you properties related to the access token, developer app, developer, and company. You can use an AssignMessage or JavaScript policy, for example, to read any of these variables and use them as needed later in the flow. These variables can also be useful for debugging purposes.

Token-specific variables

App-specific variables

These variables are related to the Developer App that is associated with the token.

Developer-specific variables

If the app.appType is "Company", then company attributes are populated and if app.appType is "Developer", then developer attributes are populated.

Company-specific variables

If the app.appType is "Company", then company attributes are populated and if app.appType is "Developer", then developer attributes are populated.

GenerateAuthorizationCode operation

These variables are set when the GenerateAuthorizationCode operation executes successfully:

Prefix: oauthv2authcode.{policy_name}.{variable_name}

Example: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken and RefreshAccessToken operations

These variables are set when the GenerateAccessToken and RefreshAccessToken operations execute successfully. Note that refresh token variables do not apply for the client credentials grant type flow.

Prefix: oauthv2accesstoken.{policy_name}.{variable_name}

Example: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

These variables are set when the GenerateAccessTokenImplicit operation executes successfully for the implicit grant type flow.

Prefix: oauthv2accesstoken.{policy_name}.{variable_name}

Example: oauthv2accesstoken.RefreshTokenPolicy.access_token

Error reference

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

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime.

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Example fault rule

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

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 Understanding OAuth endpoints.

Purging access tokens

By default, OAuth2 tokens are purged from the Apigee Edge system 3 days (259200 seconds) after both the access token and refresh token (if it exists) have expired. In some cases, you may want to change this default. For example, you may want to shorten the purge time to save disk space if a large number of tokens are being generated.

If you are on Edge for Private Cloud, you can change this default by setting organization properties as explained in this section. (The 3-day purge of expired tokens applies to Edge for Private Cloud version 4.19.01 and later. For earlier versions, the default purge interval is 180 days.)

Updating purge settings for Edge Private Cloud 4.16.01 and later versions

Note: Only tokens generated after these settings are applied are affected; the settings do not apply to tokens that were generated earlier.

Updating purge settings for Edge Private Cloud 4.15.07

Note: Only tokens generated after these settings are applied are affected; the settings do not apply to tokens that were generated earlier.

Non-RFC-compliant behavior

The OAuthV2 policy returns a token response that contains certain non-RFC-compliant properties. The following table shows the non-compliant properties returned by the OAuthV2 policy and the corresponding compliant properties.

Also, the error response for an expired refresh token when grant_type = refresh_token is:

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

However, the RFC-compliant response is:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Related topics

• Introduction to OAuth 2.0