Revoke OAuth V2 policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

policy icon

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.

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" : "tesla@weathersample.com",
  "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" : "tesla@weathersample.com",
 "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:

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.

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