Revoke OAuth V2 policy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

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" : "[email protected]",
  "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" : "[email protected]",
 "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.

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

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

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:

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

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

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

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

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

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.

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.

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