| Internet-Draft | Global Token Revocation | September 2024 |
| Parecki | Expires 26 March 2025 | [Page] |
Global Token Revocation enables parties such as a security incident management tool or an external Identity Provider to send a request to an Authorization Server to indicate that it should revoke all of the user's existing tokens and require that the user re-authenticates before issuing new tokens.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://drafts.aaronpk.com/global-token-revocation/draft-parecki-oauth-global-token-revocation.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-parecki-oauth-global-token-revocation/.¶
Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/.¶
Source for this draft and an issue tracker can be found at https://github.com/aaronpk/global-token-revocation.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 26 March 2025.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
An OAuth Authorization Server issues tokens in response to a user authorizing a client. A party external to the OAuth Authorization Server may wish to instruct the Authorization Server to revoke all tokens belonging to a particular user, and prevent the server from issuing new tokens until the user re-authenticates.¶
For example, a security incident management tool may detect anomalous behaviour on a user's account, or if the user logged in through an enterprise Identity Provider, the Identity Provider may want to revoke all of a user's tokens in the event of a security incident or on the employee's termination.¶
This specification describes a new API endpoint on an Authorization Server that can accept requests from external parties to revoke all tokens associated with a given user.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This specification uses the terms "Access Token", "Authorization Code", "Authorization Endpoint", "Authorization Server" (AS), "Client", "Client Authentication", "Client Identifier", "Client Secret", "End-User", "Grant Type", "Protected Resource", "Redirection URI", "Refresh Token", "Resource Owner", "Resource Server" (RS) and "Token Endpoint" defined by [RFC6749], and the terms "OpenID Provider" (OP) and "ID Token" defined by [OpenID].¶
This specification uses the term "Identity Provider" (IdP) to refer to the Authorization Server or OpenID Provider that is used for End-User authentication.¶
TODO: Replace RFC6749 references with OAuth 2.1¶
In a typical OAuth deployment, the OAuth client obtains tokens from the authorization server when a user logs in and authorizes the client. In many cases, the method by which a user logs in at the authorization server is through an external identity provider.¶
For example, a mobile chat application is an OAuth Client, and obtains tokens from its backend server which stores the chat messages. The mobile chat backend plays the OAuth roles of "Resource Server" and "Authorization Server".¶
In some cases, the user will log in to the Authorization Server using an external (e.g. enterprise) Identity Provider. In that case, when a user logs in to the chat application, the backend server may play the role of an OAuth client (or OpenID or SAML "relying party") to the Identity Provider in a new authorization or authentication flow.¶
A revocation request is a POST request containing a subject identifier to the Global Token Revocation endpoint, which starts the process of revoking all tokens for the identified subject.¶
The Global Token Revocation endpoint is a URL at the authorization server which accepts HTTP POST requests with parameters in the HTTP request message body using the application/json format. The Global Token Revocation endpoint URL MUST use the https scheme.¶
If the authorization server supports OAuth Server Metadata ([RFC8414]), the authorization server SHOULD include the URL of their Global Token Revocation endpoint in their authorization server metadata document using the global_token_revocation_endpoint parameter as defined in Section 5.¶
The authorization server MAY alternatively register the endpoint with tools that will use it.¶
The request is a POST request with an application/json body containing a single property sub_id, the value of which is a Security Event Token Subject Identifier as defined in "Subject Identifiers for Security Event Tokens" [RFC9493].¶
In practice, this means the value of sub_id is a JSON object with a property format, and at least one additional property depending on the value of format.¶
The request MUST also be authenticated, the particular authentication method and means by which the authentication is established is out of scope of this specification, but may include OAuth 2.0 Bearer Token [RFC6750] or a client authentication JWT [RFC7523].¶
The following example requests that all tokens for a user identified by an email address be revoked:¶
POST /global-token-revocation
Host: example.com
Content-Type: application/json
Authorization: Bearer f5641763544a7b24b08e4f74045
{
"sub_id": {
"format": "email",
"email": "user@example.com"
}
}
¶
If the user identifier at the authorization server is known by the system making the revocation request, the request can use the "Opaque Identifer" format to provide the user identifier:¶
POST /global-token-revocation
Host: example.com
Content-Type: application/json
Authorization: Bearer f5641763544a7b24b08e4f74045
{
"sub_id": {
"format": "opaque",
"id": "e193177dfdc52e3dd03f78c"
}
}
¶
If it is expected that the authorization server knows about the user identifier at the IdP, the request can use the "Issuer and Subject Identifier" format:¶
POST /global-token-revocation
Host: example.com
Content-Type: application/json
Authorization: Bearer f5641763544a7b24b08e4f74045
{
"sub_id": {
"format": "iss_sub",
"iss": "https://issuer.example.com/",
"sub": "af19c476f1dc4470fa3d0d9a25"
}
}
¶
Upon receiving a revocation request, authorizing the request, and validating the identified user, the Authorization Server:¶
This specification indicates success and error conditions by using HTTP response codes, and does not define the response body format or content.¶
To indicate that the request was successful and revocation of the requested set of tokens has begun, the server returns an HTTP 204 response.¶
The following HTTP response codes can be used to indicate various error conditions:¶
400 Bad Request: The request was malformed, e.g. an unrecognized or unsupported type of subject identifier.¶
401 Unauthorized: Authentication provided was invalid.¶
403 Forbidden: Insufficient authorization, e.g. missing scopes.¶
404 User Not Found: The user indicated by the subject identifier was not found.¶
422 Unable to Process Request: Unable to log out the user.¶
OAuth 2.0 allows deployment flexibility with respect to the style of access tokens. The access tokens may be self-contained (e.g. [RFC9068]) so that a resource server needs no further interaction with an authorization server issuing these tokens to perform an authorization decision of the client requesting access to a protected resource. A system design may, however, instead use access tokens that are handles (also known as "reference tokens") referring to authorization data stored at the authorization server.¶
While these are not the only options, they illustrate the implications for revocation. In the latter case of reference tokens, the authorization server is able to revoke an access token by removing it from storage. In the former case, without storing tokens, it may be impossible to revoke tokens without taking additional measures. One such measure is to use [I-D.ietf-oauth-status-list] to maintain a distributed and easily-compressed list of token revocation statuses.¶
For this reason, revocation of access tokens is optional in this specification, since it may pose too significant of a burden for implementers. It is not required to revoke access tokens to be able to return a success code to the caller.¶
While Section 3.2 requires that the revocation request is an authenticated request, the specifics of the authentication are out of scope of this specification.¶
Since the revocation request ultimately has wide-reaching effects (a user is expected to be logged out of all devices), this presents a new Denial of Service attack vector. As such, the authentication used for this request SHOULD be narrowly scoped to avoid granting unnecessary privileges to the caller.¶
For example, if using OAuth Bearer Tokens, the token SHOULD be issued with a single scope that enables it to perform the revocation request, and no other type of token issued should include this scope.¶
If the authorization server is multi-tenant (supports multiple customers) through different identity providers, each identity provider SHOULD use its own scoped credential that is only authorized to revoke tokens for users within the same tenant.¶
Typically, an API that accepts a user identifier and returns different statuses depending on whether the user exists would provide an attack vector allowing enumeration of user accounts. This specification does require a "User Not Found" response, so would normally fall under this category. However, requests to the endpoint defined by this specification are required to be authenticated, so this is not considered a public endpoint.¶
If the tool making the request is compromised, and the attacker can impersonate the requests from this tool (either by coercing the tool to make the request, or by extracting the credentials), then the attacker would be able to enumerate user accounts. However, since the request is not just testing the presence of a user account, but actually revoking the tokens associated with the user if successful, this would likely be easily visible in any audit logs, as many users' tokens would be revoked in a short period of time.¶
To mitigate some of the concerns of providing such a powerful API endpoint, the users that a particular client can request revocation for SHOULD be limited, and the authentication of the request SHOULD be used to scope the possible user revocation list to only users authorized to the client as described in Section 6.1.¶
For example, a multi-tenant identity provider that uses different signing keys for users associated with different tenants, can also use the same signing keys to authenticate revocation requests, such as creating a JWT to use as client authentication as described in [RFC7523]. This enables the authorization server receiving the request to only accept revocation requests for users that are associated with the particular tenant at the identity provider.¶
(( To be removed from the final specification ))¶
-04¶
-03¶
Renamed property from subject to sub_id for consistency with JWT claim name defined in RFC9493¶
Added reference to draft-ietf-oauth-status-list¶
Added additional security considerations for authentication of the revocation request and malicious authorization servers¶
-02¶
Added security consideration around enumeration of user accounts¶
Added an appendix describing the differences between this and related logout specifications¶
-01¶
Clarified revocation expectations¶
Better definition of endpoint¶
Added section defining endpoint in Authorization Server Metadata¶
-00¶
Initial Draft¶
The authors would like to thank the following people for their contributions and reviews of this specification: Apoorva Deshpande, George Fletcher, Karl McGuinness, Mike Jones.¶