]> 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 the 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 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 on a security incident or on the employee's termination. This specification describes an API endpoint so that an authorization server 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 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.

Token Revocation A revocation request is a POST request 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 with tools that will use it.

Revocation Request The request is a POST request with an application/json body containing a single property subject, the value of which is a Security Event Token Subject Identifier as defined in . In practice, this means the value of subject 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 an OAuth 2.0 Bearer Token () or a JWT (). The following example requests all tokens for a user identified by an email address to be revoked: To request revocation of all tokens for a user identified by a user ID at the Authorization Server, use the "opaque subject" identifier:

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 NOT issue new access tokens or refresh tokens without re-authenticating the user

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

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.

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 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. For this reason, revocation of access tokens is optional in this specification, since it may post 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.

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 Section 7.2.) If omitted, the set of supported authentication methods MUST be determined by other means.

Security Considerations TODO Security

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. IANA Amazon Coinbase Fastly 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 describe a subject, and named formats that define the syntax and semantics for encoding subject identifiers as JSON objects. It also defines a registry for defining and allocating names for such formats, as well as the "sub_id" JSON Web Token (JWT) claim. 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.

Document History (( To be removed from the final specification )) -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: George Fletcher, Karl McGuinness, Mike Jones.