Revoking and approving tokens

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Understanding token revocation

In some cases, apps are required to explicitly revoke or invalidate individual tokens. A typical case might be when a user logs out of an OAuth-enabled app. A revoked token will no longer be useful for authorization. After a token has been revoked, if an app presents that token to an API proxy, an OAuthV2 policy with an Operation of VerifyAccessToken will reject that token.

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.

The standard for token revocation is defined by IETF RFC 7009, the OAuth 2.0 Token Revocation specification.

As an alternative to revoking specific tokens, you can revoke client IDs, or entire developer apps. See Revoking and approving developer app keys for details. As compared to revoking an individual token, revoking a client ID or developer app has a broader impact. When you revoke a client ID or developer app, Apigee will reject all tokens associated with that client ID or developer app, and will no longer issue new tokens for that client ID or developer app.

After revoking a token, either an access token or a refresh token, you can optionally re-approve that token, at any time before it expires. After re-approving the token, the Apigee OAuthV2 policy will again accept that token for authorization, until the token expires. Token expiration is independent of the approved or revoked state of the token. The Apigee OAuthV2 policy with an Operation of ValidateAccessToken will accept an access token only if that token is both approved (or not revoked) and not expired. Likewise, the Apigee OAuthV2 policy with an Operation of RefreshAccessToken will accept a refresh token only if that token is both approved (or not revoked) and not expired.

Note: You cannot revoke a JWT access token. You can revoke only opaque OAuth tokens, either access tokens or refresh tokens, that have been generated by the OAuthV2 policy. While the OAuthV2 policy can generate access tokens that are of either opaque format or JWT format, you cannot revoke JWT access tokens that have been generated by the OAuthV2 policy.

There are two policies that you can use to revoke tokens:

• the OAuthV2 policy, using an Operation of InvalidateToken.
• the RevokeOAuthV2 policy.

The OAuthV2 policy has the capability to revoke, and also reinstate, a single token at a time. The RevokeOAuthV2 policy is more flexible in that it can revoke multiple tokens at once, by App ID, or End User ID. The rest of this page describes using the OAuthV2 policy to revoke a token or to reinstate a previously revoked token.

Revoking access and refresh tokens

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.

Here's an example configuration for the OAuthV2 policy that uses the InvalidateToken Operation. In this case, because the cascade attribute on the Token element is true, Apigee revokes both the access token and its associated refresh token.

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>
  

For more information about how the cascade flag works, see the section below on the Attributes for the Token element.

<Tokens>/<Token> element

Identifies the flow variable that specifies the token to be revoked. If developers are expected to submit a revocation request using a query parameter named access_token, for example, the correct flow variable will be: request.queryparam.access_token. To require the token in an HTTP header, for example, set this value to request.header.access_token.

It is not possible to revoke an access token that is in JWT format. Further, it is not possible to use the OAuthV2 policy to revoke a refresh token that is associated to an access token that is in JWT format. A runtime error will occur if the context variable specified here refers to a JWT access token, or a refresh token that is associated to a JWT access token. You can revoke refresh tokens associated to JWT access tokens using the RevokeOAuthV2 policy.

Attributes

• type (required, string): The token type identified by the variable specified. Supported values are accesstoken and refreshtoken:
  • To revoke an access token, specify type accesstoken.
  • To revoke both the access and refresh tokens, specify type refreshtoken. When it sees type refreshtoken, Apigee assumes the token is a refresh token. If that refresh token is found, then it is revoked. If that refresh token is not found, then Apigee checks to see if it is an access token. If the access token exists, then it is revoked.
    
    Note: If you pass an already invalidated token to an InvalidateToken policy, the policy doesn't return an error, although you might expect it to. Such an operation has no effect.
• cascade (optional, boolean, default: true) The primary use of this attribute is to revoke a refresh token without revoking its associated access token. Consider these cases:
  • Revoke a refresh token only and do not revoke its associated access token. To do this, set the <Token> type to refreshtoken and set cascade to false.
  • Revoke both the access token and the refresh token. To do this, set the <Token> type to accesstoken. The value of cascade can be either true (the default) or false. If you set it to true, then both the access token and the refresh token are revoked. If you set it to false, the access token is revoked, and the refresh token is unusable. See the Note below for more explanation.
  • Revoke an access token and do not revoke its associated refresh token. Not supported. See the Note below for more explanation.

Note: For security reasons, if you revoke an access token, the associated refresh token will be revoked also. Therefore, you cannot use the cascade attribute to revoke only an access token. For example, if you set the <Token> type to accesstoken, and set cascade=false, the access token is revoked (as expected); however, the associated refresh token is unusable. It cannot be used to refresh the revoked access token. The primary use case for the cascade attribute is when you want to only revoke a refresh token. In that case, set the <Token> type to refreshtoken, and set cascade=false. The refresh token will be revoked, but its associated access token will remain valid (until it expires or is revoked). For more information, see this Community forum discussion.

Approving access and refresh tokens

Use the ValidateToken operation to "re-approve" a revoked token. That is, when you apply this operation, the status of the targeted access or refresh token is changed from 'revoked' to 'approved'. You can validate any revoked token that has not already expired.

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

<Tokens>/<Token> element

Identifies the flow variable that specifies the token to be validated. If developers are expected to submit a validation request using a query parameter named access_token, for example, the correct flow variable will be: request.queryparam.access_token. To require the token in an HTTP header, for example, set this value to request.header.access_token.

Attributes

• type (required, string) The token type identified by the variable specified. Supported values are accesstoken and refreshtoken.
• cascade (optional, boolean): By default, this option is set to true, and causes the validation to propagate to associated tokens. So, if applied to a refresh token, its associated access token is also validated. If applied to an access token, its associated refresh token is also validated. If you set this to false, then only the specified access or refresh token is validated.