]> Okta

aaron@parecki.com https://aaronparecki.com

Security Web Authorization Protocol oauth token revocation logout 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 a user's existing tokens and require that the user re-authenticates before issuing new tokens. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction 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 for that user 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 upon 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.

Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here.

Terminology 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 , and the terms "OpenID Provider" (OP) and "ID Token" defined by . 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

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

Token Revocation A revocation request is an HTTP POST request containing a subject identifier to the Global Token Revocation endpoint, which starts the process of revoking all tokens for the identified subject.

Revocation Endpoint 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 (), 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 . The authorization server MAY alternatively register the endpoint directly with tools that will use it.

Revocation Request 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" . 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. This specification RECOMMENDS using a private key JWT as described in . Other authentication methods such as OAuth 2.0 Bearer Token MAY be used where appropriate. The following example requests that all tokens for a user identified by an email address be revoked using the Email Identifier Format as defined in : 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 as defined in to provide the user identifier: 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 as defined in :

Revocation Expectations Upon receiving a revocation request, authorizing the request, and validating the identified user, the Authorization Server:

• MUST revoke all active refresh tokens
• SHOULD invalidate all access tokens, although it is recognized that it might not be technically feasible to invalidate access tokens (see below)
• MUST re-authenticate the user before issuing new access tokens or refresh tokens

Revocation Response This specification indicates success and error conditions by using HTTP response codes, and does not define the response body format or content.

Successful Response To indicate that the request was successful and revocation of the requested set of tokens has begun, the server returns an HTTP 204 response.

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

Authentication Using Private Key JWT When the caller is an Identity Provider, the RECOMMENDED authentication method is to send a signed JWT as a Bearer token in the HTTP Authorization header, following the structure of the private_key_jwt client authentication method defined in . The JWT MUST contain the following claims:

iss:

The issuer identifier of the Identity Provider. If using OpenID Connect, this MUST be the same issuer value that the IdP uses as the issuer value in ID tokens.

sub:

An identifier for the caller within the IdP. For OpenID Connect clients this is typically the client_id; for SAML integrations it is typically the appInstanceId.

aud:

The URL of the Global Token Revocation endpoint. This MUST be the exact endpoint URL, without query string parameters or fragment identifiers.

jti:

A unique identifier for this JWT. The authorization server SHOULD reject requests using a jti value that has been seen before within the token's validity window, in order to prevent replay attacks.

iat:

The unit timestamp at which the JWT was created.

exp:

The expiration time of the JWT. The JWT SHOULD be short-lived; a validity window of five minutes is RECOMMENDED.

The JWT MUST be signed using an asymmetric algorithm (e.g., RS256 or ES256). The signing key SHOULD be the same private key that the IdP uses to sign its ID tokens or SAML assertions, so that the authorization server can verify the signature using the IdP's already-published public keys (e.g., via the IdP's JWKS endpoint referenced in its OpenID Connect discovery document ). The JWT is sent as a Bearer token: Where the JWT payload is: The authorization server MUST validate the JWT signature, verify that the claims are well-formed, and confirm that the aud claim matches the revocation endpoint URL. It MUST also verify that the exp has not passed and that the jti has not been previously used.

Revocation of Access Tokens OAuth 2.0 allows deployment flexibility with respect to the style of access tokens. The access tokens may be self-contained (e.g. ) 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 (commonly referred to 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 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.

Revocation Completion Notification The 204 response defined in indicates that the authorization server has accepted the revocation request and that the revocation process has begun. It does not guarantee that all tokens have been revoked at the moment the response is returned. In many deployments, particularly those with distributed token storage or self-contained access tokens, full revocation may complete asynchronously after the HTTP response has been sent. For use cases where a caller needs confirmation that revocation is fully complete — for example, a security incident management tool that must verify all active sessions have been terminated before proceeding — a notification mechanism is needed. Authorization servers that support the Shared Signals Framework MAY use it to deliver a completion notification to the caller. Specifically, the authorization server MAY transmit a CAEP "Session Revoked" event to a preconfigured SSF stream for the caller once all tokens for the identified subject have been revoked and the re-authentication requirement has been enforced. The use of SSF for completion notification is entirely OPTIONAL. Callers that do not require confirmation of completion MAY rely solely on the 204 response as an indication that revocation has been initiated. The Global Token Revocation endpoint defined in this specification operates independently of whether SSF is supported by either party. If an authorization server supports SSF-based completion notifications, it SHOULD document this capability and the event types it delivers out of band, as no authorization server metadata parameter is defined here for this purpose. Note that the direction of the SSF stream in this case is reversed from the typical identity-provider-to-authorization-server direction described in : here, the authorization server acts as the SSF transmitter, delivering events back to the caller (e.g., the identity provider or security tool) that initiated the revocation request.

Authorization Server Metadata The following authorization server metadata parameters are introduced to signal the server's capability and policy with respect to Global Token Revocation.

"global_token_revocation_endpoint":

The URL of the authorization server's global token revocation endpoint.

"global_token_revocation_endpoint_auth_methods_supported":

OPTIONAL. JSON array containing a list of client authentication methods supported by this introspection endpoint. The valid client authentication method values are those registered in the IANA "OAuth Token Endpoint Authentication Methods" registry or those registered in the IANA "OAuth Access Token Types" registry . (These values are and will remain distinct, due to .) If omitted, the set of supported authentication methods MUST be determined by other means.

Security Considerations

Authentication of Revocation Request The revocation request MUST be authenticated as described in . The RECOMMENDED method is the private key JWT mechanism described in , which binds the credential to the specific endpoint URL via the aud claim and limits its validity window, reducing the risk of credential misuse or replay. 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 only 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. When using private key JWT authentication as described in , the iss claim serves this purpose naturally, as each IdP signs with its own private key.

Enumeration of User Accounts 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 . 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 . 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.

Malicious Authorization Server From the point of view of an identity provider that supports integrations with multiple downstream applications, there is an opportunity for a downstream application to maliciously set up a Global Token Revocation endpoint to harvest user identifiers and authentication of the revocation requests. Similarly as described in above, each integration SHOULD be using separate authentication credentials, and each credential SHOULD be scoped as narrowly as possible, such that a malicious server that receives this authentication cannot replay it anywhere else to perform any actions on other systems.

IANA Considerations

OAuth Authorization Server Metadata IANA has (TBD) registered the following values in the IANA "OAuth Authorization Server Metadata" registry of established by . Metadata Name: global_token_revocation_endpoint Metadata Description: URL of the authorization server's global token revocation endpoint. Change Controller: IESG Specification Document: Section X of [[ this specification ]] Metadata Name: global_token_revocation_endpoint_auth_methods_supported Metadata Description: OPTIONAL. Indicates the list of client authentication methods supported by this endpoint. Change Controller: IESG Specification Document: Section X of [[ this specification ]]

References Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification defines a metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an OAuth 2.0 authorization server, including its endpoint locations and authorization server capabilities. Security events communicated within Security Event Tokens may support a variety of identifiers to identify subjects related to the event. This specification formalizes the notion of Subject Identifiers as structured information that describes a subject and named formats that define the syntax and semantics for encoding Subject Identifiers as JSON objects. It also establishes a registry for defining and allocating names for such formats as well as the JSON Web Token (JWT) "sub_id" Claim. IANA In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References This specification describes how to use bearer tokens in HTTP requests to access OAuth 2.0 protected resources. Any party in possession of a bearer token (a "bearer") can use it to get access to the associated resources (without demonstrating possession of a cryptographic key). To prevent misuse, bearer tokens need to be protected from disclosure in storage and in transport. [STANDARDS-TRACK] This document proposes an additional endpoint for OAuth authorization servers, which allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. This allows the authorization server to clean up security credentials. A revocation request will invalidate the actual token and, if applicable, other tokens based on the same authorization grant. This specification defines the use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. This specification defines a profile for issuing OAuth 2.0 access tokens in JSON Web Token (JWT) format. Authorization servers and resource servers from different vendors can leverage this profile to issue and consume access tokens in an interoperable manner. MATTR Bundesdruckerei SPRIND This specification defines a status mechanism called Token Status List (TSL), data structures and processing rules for representing the status of tokens secured by JSON Object Signing and Encryption (JOSE) or CBOR Object Signing and Encryption (COSE), such as JWT, SD-JWT, CBOR Web Token, and ISO mdoc. It also defines an extension point and a registry for future status mechanisms.

Relationship to Related Specifications

RFC7009: Token Revocation OAuth 2.0 Token Revocation defines an endpoint for authorization servers that an OAuth client can use to notify the authorization server that a previously-obtained access or refresh token is no longer needed. The request is made by the OAuth client. The input to the Token Revocation request is the token itself, as well as the client's own authentication credentials. This differs from the Global Token Revocation endpoint which does not take a token as an input, but instead takes a user identifier as input. It is not called by OAuth clients, but is instead called by an external party such as a security monitoring tool or an identity provider that the user used to authenticate at the authorization server.

OpenID Connect Front-Channel Logout OpenID Connect Front-Channel Logout provides a mechanism for an OpenID Provider to log users out of Relying Parties by redirecting the user agent. While the logout request is the same direction as this draft describes, this relies on the redirection of the user agent, so is only applicable when the user is actively interacting with the application in a web browser. The Global Token Revocation request works regardless of whether the user is actively using the application, and is also applicable to non-web based applications.

OpenID Connect Back-Channel Logout OpenID Connect Back-Channel Logout provides a mechanism for an OpenID Provider to log users out of a Relying Party by making a back-channel POST request containing the user identifier of the user to log out. This is the most similar existing logout specification to Global Token Revocation. However, there are still a few key differences that make it insufficient for the use cases enabled by Global Token Revocation. OpenID Connect Back-Channel Logout requires Relying Parties to clear state of any sessions for the user, but doesn't mention anything about access tokens. It also says that refresh tokens issued with the offline_access scope "SHOULD NOT be revoked". This is a concretely different outcome than is described by Global Token Revocation, which requires the revocation of all refresh tokens for the user regardless of whether the refresh token was issued with the offline_access scope. OpenID Connect Back-Channel Logout also assumes that the Relying Party implements OpenID Connect, which creates implementation challenges to use it when the Relying Party actually integrates with the identity provider using other specifications such as SAML. Additionally, OpenID Connect Back-Channel Logout identifies the user using the sub claim of an ID token. This limits the applicability, since there is no mechanism to identify the user by email address or other identifier that might be known between the identity provider and authorization server. Global Token Revocation instead relies on Security Event Token Subject Identifiers () which provide multiple options for identifying the user. Global Token Revocation works regardless of the protocol that the user uses to authenticate, so works equally well with OpenID Connect and SAML integrations.

Shared Signals Framework The Shared Signals Framework at the OpenID Foundation provides two specifications that have functionality related to session and token revocation. Continuous Access Evaluation Profile (CAEP) defines several event types that can be sent between cooperating parties. In particular, the "Session Revoked" event can be sent from an identity provider to an authorization server when the user's session at the identity provider was revoked. The main difference between this and the Global Token Revocation request is that the CAEP event is a signal that may or may not be acted upon by the receiver, whereas the Global Token Revocation request is a command that has a defined list of expected outcomes. Risk Incident Sharing and Coordination (RISC) defines events that have somewhat stronger defined meanings compared to CAEP. In particular, the "Account Disabled" event has clear meaning and strongly implies that a receiver should also disable the specified account. However, RISC also has a mechanism for a user to opt out of sending events for their account, so it does not provide the same level of assurance as a Global Token Revocation request. Lastly, it is more complex to set up a receiver for CAEP and RISC events compared to a receiver for the Global Token Revocation request, so if the receiver is only interested in supporting the revocation use cases, it is much simpler to support the single POST request described in this draft. While SSF and Global Token Revocation serve complementary purposes, they can also be used together. As described in , an authorization server MAY use SSF to deliver a completion notification back to the caller once revocation is fully complete, reversing the typical signal direction so that the AS acts as SSF transmitter.

Document History (( To be removed from the final specification )) -06

• added description of how to use SSF to confirm revocation
• added description of how to use private_key_jwt to authenticate requests to the Authorization Server

-05

• Editorial clarifications
• Added specific references to subject identifier formats

-04

• Edits for clarity
• Fixed prose description renaming subject to sub_id

-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

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