Revoke OAuth V2 policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

The JWT access token feature is available for Apigee and for Apigee hybrid versions 1.7.0 and later. See Using JWT OAuth tokens.

Overview

Revokes OAuth2 access tokens associated with a developer app ID or app end user ID, or both.

This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.

Warning: OAuth tokens are cached for three minutes (180 seconds); therefore, a revoked token may still succeed for up to three minutes, until its cache limit expires.

Warning: You can potentially revoke a large number of tokens with a single execution of this policy. Because you cannot undo the revocation of a token, ensure that the ID you pass to this policy specifying the tokens to revoke is correct.

Use the OAuthv2 policy to generate an OAuth 2.0 access token. An Apigee generated token has the following format:

{
  "issued_at" : "1421847736581",
  "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[PremiumWeatherAPI]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "[e-mail]",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
  "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
  "organization_name" : "myorg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

The application_name element contains the developer app ID associated with the token.

By default, Apigee does not include the end user ID in the token. You can configure Apigee to include the end user ID by adding the <AppEndUser> element to the OAuthv2 policy:

<OAuthV2 name="GenerateAccessTokenClient">
    <Operation>GenerateAccessToken</Operation>
    ...
    <AppEndUser>request.queryparam.app_enduser</AppEndUser>
</OAuthV2>

In this example, pass the end user ID to the OAuthv2 policy in a query parameter named app_enduser. The end user ID is then included in the token in the app_enduser element:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "[e-mail]",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

Revoke by developer app ID

Revoke OAuth2 access tokens associated with a developer app ID. All OAuth2 access tokens generated by Apigee include the ID of the developer app associated with the token. You can then revoke tokens based on that app ID.

To get a list of app IDs for a specific developer, use the:

• Method: organizations.developers.apps.list API to get a list of apps associated with a developer.
• Method: organizations.developers.apps.get API to get details about the app, including the app ID.

Revoke by app end-user ID

Revoke OAuth2 access tokens associated with a specific app end-user's ID. This is the token associated with the ID of the user to whom the tokens were issued.

By default, there is no field for end user ID in the OAuth access token. To enable revocation of OAuth 2.0 access tokens by end user ID, you have to configure the OAuthv2 policy to include the user ID in the token, as shown above.

To get an app end-user ID, use the Method: organizations.developers.get.

Samples

The following samples use the Revoke OAuth V2 policy to revoke OAuth2 access tokens.

Developer app ID

To revoke access tokens by developer app ID, use the <AppId> element in your policy.

The following example expects to find the developer app ID of the access token in a query parameter named app_id:

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
</RevokeOAuthV2>

Given the ID of the developer app, the policy revokes the access token.

Revoke before timestamp

To revoke access tokens by developer app ID that were generated before a specific date and time, use the <RevokeBeforeTimestamp> element in your policy. <RevokeBeforeTimestamp> specifies a UTC epoch time in milliseconds. All tokens issued before that time are revoked.

The following example revokes the access tokens for a developer app created before July 1, 2019:

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
  <RevokeBeforeTimestamp>1561939200000</RevokeBeforeTimestamp>
</RevokeOAuthV2>

The <RevokeBeforeTimestamp> element takes a 64-bit (long) integer representing the number of milliseconds elapsed since midnight, on January 1, 1970 UTC.

---

Element Reference

The element reference describes the elements and attributes of the RevokeOAuthV2 policy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RevokeOAuthV2 continueOnError="false" enabled="true" name="GetOAuthV2Info-1">
  <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
  <AppId ref="variable"></AppId>
  <EndUserId ref="variable"></EndUserId>
  <RevokeBeforeTimestamp ref="variable"></RevokeBeforeTimestamp>
  <Cascade>false</Cascade>
</RevokeOAuthV2>

<RevokeOAuthV2> attributes

<RevokeOAuthV2 continueOnError="false" enabled="true" name="Revoke-OAuth-v20-1">

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

Attribute	Description	Default	Presence
name	The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.	N/A	Required
continueOnError	Set to false to return an error when a policy fails. This is expected behavior for most policies. 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

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

Default	N/A If you omit this element, the value of the policy's name attribute is used.
Presence	Optional
Type	String

<AppId> element

Specifies the developer app ID of the tokens to revoke. Pass either a variable that contains the app ID or a literal app ID.

<AppId>appIdString</AppId>

or:

<AppId ref="request.queryparam.app_id"></AppId>

Default	request.formparam.app_id (a x-www-form-urlencoded and specified in the request body)
Presence	Optional
Type	String
Valid values	Either a flow variable containing an app ID string, or a literal string.

<Cascade> element

If true and you have a traditional opaque access token, then both the refresh token and access token will be revoked if either <AppId> or <EndUserId> match. If you have a JWT access token, then only the refresh token issued with the access token is revoked. By design, JWT access tokens cannot be revoked. If false, only the access token is revoked and the refresh token is unchanged. The same behavior applies for opaque access tokens only. JWT access tokens cannot be revoked.

<Cascade>false<Cascade>

Default	false
Presence	Optional
Type	Boolean
Valid values	true or false

<EndUserId> element

Specifies the app end-user ID of the token to revoke. Pass either a variable that contains the user ID or a literal token string.

<EndUserId>userIdString</EndUserId>

or:

<EndUserId ref="request.queryparam.access_token"></EndUserId>

Default	request.formparam.enduser_id (a x-www-form-urlencoded and specified in the request body)
Presence	Optional
Type	String
Valid values	Either a flow variable containing a user ID string, or a literal string.

<RevokeBeforeTimestamp> element

Revoke tokens that were issued before the timestamp. This element works with <AppId> and <EndUserId> to let you revoke tokens before a specific time. The default value is the time that the policy executes.

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

<RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>

Default	The timestamp that the policy is executed.
Presence	Optional
Type	64-bit (long) integer representing the number of milliseconds ellapsed since midnight, on January 1, 1970 UTC.
Valid values	Either a flow variable containing a timestamp, or a literal timestamp. The timestamp cannot be in the future and cannot be before January 1, 2014.

Flow variables

The RevokeOAuthV2 policy does not set flow variables.

Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code	HTTP status	Cause
steps.oauth.v2.InvalidFutureTimestamp	500	Timestamp cannot be in the future.
steps.oauth.v2.InvalidEarlyTimestamp	500	Timestamp cannot be earlier than January 1, 2014.
steps.oauth.v2.InvalidTimestamp	500	Timestamp is invalid.
steps.oauth.v2.EmptyAppAndEndUserId	500	Both AppdId and EndUserId cannot be empty.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

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

Note: You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GetTokenInfo.cause = ClientID is Invalid

Example error response

{
   "fault":{
      "faultstring":"Timestamp is in the future.",
      "detail":{
         "errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
      }
   }
}

Example fault rule

<FaultRule name="RevokeOAuthV2 Faults">
    <Step>
        <Name>AM-InvalidTimestamp</Name>
    </Step>
    <Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>

Related topics

• OAuthV2 policy
• OAuth home
• Customizing Tokens and Authorization Codes