Approving and revoking access tokens

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Revoking access and refresh tokens

In some cases, apps are required to explicitly revoke or invalidate tokens, for example, when a user logs out of an OAuth-enabled app. If you revoke a token, it can be re-approved anytime before it expires.

The procedure for token revocation is defined by the OAuth 2.0 Token Revocation specification.

Apigee Edge provides an InvalidateToken operation that enables you to configure a dedicated token revocation endpoint. By publishing the URI of this endpoint, you enable app developers to invalidate tokens issued by Edge.

Here's an example configuration for the OAuthV2 policy and the InvalidateToken operation. In this case, both the access token and its associated refresh token are revoked. Technically, they are both revoked because the cascade flag is set to true. For more information about how the cascade flag works, see the Token element's attributes section below. 

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

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

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, Edge 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 Edge 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.