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" : "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:
- 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 Optionally, use the |
N/A | Required |
continueOnError |
Set to Set to |
false | Optional |
enabled |
Set to Set to |
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 |
---|---|
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 |
|
---|---|
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 |
|
---|---|
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>