RFC 7009
OAuth 2.0 Token Revocation
RFC 7009: OAuth 2.0 Token Revocation 💖
okay bestie, here's the quick vibe check before we dive in 🎀
- Publisher: Internet Engineering Task Force (IETF) 🌸
- Authors: T. Lodderstedt, Ed. (Deutsche Telekom AG), S. Dronia, M. Scurtescu (Google)
- Category: Standards Track 🔥
- Date: August 2013
- ISSN: 2070-1721
- Obsoletes / Updates: none listed in this header 🙈
Abstract ✨
okay so this doc adds a brand new endpoint for OAuth authorization servers 🦋 It lets clients tell the server "hey, I don't need this refresh or access token anymore" 💅 The server can then clean up its security credentials, which is so responsible of it 🫶 A revocation request kills the actual token and, if it applies, any other tokens that came from the same authorization grant 🌈
Status of This Memo 🧚
this is an Internet Standards Track document 🔥
it's a product of the Internet Engineering Task Force (IETF) 🌸 it represents the consensus of the IETF community and got public review 👑 it was approved for publication by the Internet Engineering Steering Group (IESG) 💅 if you want more on Internet Standards, check out Section 2 of RFC 5741 🤓
for the current status, errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc7009 💖
Copyright Notice 🎀
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. 🌈
this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stood on the date of publication 📜 please actually read those, because they spell out your rights and restrictions for this doc 🙏 also, any Code Components pulled out of this doc have to include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License ⚠️
Table of Contents 🍓
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3
2. Token Revocation . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Revocation Request . . . . . . . . . . . . . . . . . . . 4
2.2. Revocation Response . . . . . . . . . . . . . . . . . . . 5
2.2.1. Error Response . . . . . . . . . . . . . . . . . . . 6
2.3. Cross-Origin Support . . . . . . . . . . . . . . . . . . 6
3. Implementation Note . . . . . . . . . . . . . . . . . . . . . 7
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
4.1. OAuth Extensions Error Registration . . . . . . . . . . . 8
4.1.1. The "unsupported_token_type" Error Value . . . . . . 8
4.1.2. OAuth Token Type Hints Registry . . . . . . . . . . . 8
4.1.2.1. Registration Template . . . . . . . . . . . . . . 9
4.1.2.2. Initial Registry Contents . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . 111. Introduction 🦋
okay so the OAuth 2.0 core spec [RFC6749] already defines a bunch of ways for a client to get refresh and access tokens 🔑 this spec is the glow-up that adds a way to revoke both kinds 💅 a token is a string that stands for an authorization grant the resource owner gave to the client 🎟️ a revocation request kills the actual token and, if it applies, other tokens based on the same grant, plus the authorization grant itself 💀
now from the end-user's side, OAuth is usually what lets you log into some site or app ✨ this revocation mechanism means a client can wipe its tokens when the end-user logs out, changes identity, or uninstalls the app 🧹 telling the server the token isn't needed lets it clean up the data tied to that token (like session data) and the underlying grant too 🫧 this is lowkey important because it stops a situation where a valid grant is still sitting there for a client the end-user has no idea about 👀 so token revocation shuts down abuse of abandoned tokens and makes the end-user experience better, since dead grants won't show up in the list of grants the server might show the end-user 💖
1.1. Requirements Language 📜
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 🤓
2. Token Revocation 💅
okay the main rule: Implementations MUST support the revocation of refresh tokens, and they SHOULD support the revocation of access tokens too (see Implementation Note) 🔥
the client asks for a particular token to be revoked by sending an HTTP POST request to the token revocation endpoint URL 📮 that URL MUST conform to the rules in [RFC6749], Section 3.1 🔗 and clients MUST verify that it's an HTTPS URL 🔒
how the client finds that endpoint is out of scope for this spec 🗺️ the client dev might check the server's docs, or automatic discovery might be used 🤖 since this endpoint handles security credentials, the location has to come from a trustworthy source 🫶
and because requests to this endpoint send plaintext credentials in the HTTP request, URLs for token revocation endpoints MUST be HTTPS URLs 🔐 the authorization server MUST use Transport Layer Security (TLS) [RFC5246] in a version compliant with [RFC6749], Section 1.6 🛡️ implementations MAY also support other transport-layer security mechanisms that meet their security requirements, so you get options 🌈
if the host of the token revocation endpoint can also be reached over HTTP, then the server SHOULD also offer a revocation service at the matching HTTP URI, but it MUST NOT publish that URI as a token revocation endpoint 🙈 the reason is so tokens that accidentally get sent over HTTP still get revoked 🧚
2.1. Revocation Request 🎀
the client builds the request by including these parameters in the HTTP request entity-body, using the "application/x-www-form-urlencoded" format 📝
tokenREQUIRED. The token that the client wants to get revoked.token_type_hintOPTIONAL. A hint about the type of the token submitted for revocation. Clients MAY pass this parameter to help the authorization server optimize the token lookup. If the server can't find the token using the given hint, it MUST extend its search across all of its supported token types. An authorization server MAY ignore this parameter, especially if it can detect the token type automatically. This spec defines two values:
Specific implementations, profiles, and extensions of this spec MAY define other values for this parameter using the registry defined in Section 4.1.2.
the client also includes its authentication credentials, as described in Section 2.3. of [RFC6749] 🔑
for example, a client might request revocation of a refresh token with this request 💌
POST /revoke HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=45ghiukldjahdnhzdauz&token_type_hint=refresh_tokenso the authorization server first checks the client credentials (if it's a confidential client) and then checks whether the token was issued to the client making the revocation request 🕵️ if that validation fails, the request gets refused and the server tells the client about the error, as described below ❌
next up, the server invalidates the token ⚡ the invalidation happens immediately, and the token can't be used again after it's revoked 🚫 in practice there could be a propagation delay, where some servers know about the invalidation and others don't yet 🌀 implementations should minimize that window, and clients must not try to use the token after getting an HTTP 200 response from the server 🙅♀️
depending on the server's revocation policy, revoking one token may also revoke related tokens and the underlying authorization grant 🌳 if the token is a refresh token and the server supports revoking access tokens, then the server SHOULD also invalidate all access tokens based on the same authorization grant (see Implementation Note) 💥 if the token in the request is an access token, the server MAY revoke the respective refresh token as well 🫧
Note: A client compliant with [RFC6749] must be prepared to handle unexpected token invalidation at any time. Independent of the revocation mechanism specified in this document, resource owners may revoke authorization grants, or the authorization server may invalidate tokens in order to mitigate security threats. Thus, having different server policies with respect to cascading the revocation of tokens should not pose interoperability problems. 🫶
2.2. Revocation Response 🌈
the authorization server responds with HTTP status code 200 if the token was revoked successfully, or if the client submitted an invalid token ✅
Note: invalid tokens don't cause an error response, since the client can't handle that error in a reasonable way 🙃 plus, the whole point of the request, invalidating that particular token, is already achieved 🎉
the client ignores the content of the response body, because all the necessary info is conveyed in the response code 🤷♀️
an invalid token type hint value gets ignored by the authorization server and doesn't change the revocation response 💁♀️
2.2.1. Error Response 🚨
the error format follows the definition in Section 5.2 of [RFC6749] 📋 this spec adds one more error code for the token revocation endpoint 🪄
unsupported_token_type: The authorization server doesn't support revoking the presented token type. That is, the client tried to revoke an access token on a server that doesn't support this feature. 💀
if the server responds with HTTP status code 503, the client must assume the token still exists, and it may retry after a reasonable delay ⏳ the server may include a Retry-After header in the response to show how long the service is expected to be unavailable to the requesting client 🕰️
2.3. Cross-Origin Support ✨
okay so the revocation endpoint MAY support Cross-Origin Resource Sharing (CORS) [W3C.WD-cors-20120403] if it's aimed at being used alongside user-agent-based apps 💅🫶
and for interop with legacy user-agents, it MAY also offer JSONP (Remote JSON - JSONP) [jsonp] 🎀 by allowing GET requests with one extra parameter:
callback OPTIONAL. The qualified name of a JavaScript function. 🌸
ok here's an example of a client asking to revoke an access token (line breaks are just for display, bestie 🙈):
https://example.com/revoke?token=agabcdefddddafdd&
callback=package.myCallbackSuccessful response:
package.myCallback();Error response:
package.myCallback({"error":"unsupported_token_type"});ngl clients need to be aware that when they rely on JSONP, a malicious revocation endpoint may try to inject malicious code into the client 💀😭 so be careful, babe 🚨
3. Implementation Note 🧚
okay so OAuth 2.0 gives deployments lots of flexibility when it comes to the style of access tokens 🦋 The access tokens may be self-contained, so that a resource server doesn't need any further interaction with the authorization server that issued them in order to make an authorization decision about 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 🍓 This means a resource server has to send a request to the matching authorization server to retrieve the content of the access token every single time a client presents one 😩
these aren't the only options, but they show what it all means for revocation 👑 In the handle case, the authorization server can revoke an access token it previously issued to a client when the resource server relays a received access token 💜 In the self-contained case, some (currently non-standardized) backend interaction between the authorization server and the resource server may be used when immediate access token revocation is wanted 🔥 Another design alternative is to issue short-lived access tokens, which can be refreshed at any time using the corresponding refresh tokens 🌈 This lets the authorization server impose a limit on the time a revoked token stays usable while access tokens are in use ⭐
which revocation approach gets chosen depends on the overall system design and on the application service provider's risk analysis 🎀 The cost of revocation, in terms of required state and communication overhead, is ultimately the result of the security properties you want 💅
4. IANA Considerations 📋
this spec registers an error value in the "OAuth Extensions Error Registry" and establishes the "OAuth Token Type Hints" registry 🦋
4.1. OAuth Extensions Error Registration
this spec registers the following error value in the "OAuth Extensions Error Registry" defined in [RFC6749] ✨
4.1.1. The "unsupported_token_type" Error Value
Error name: unsupported_token_type
Error Usage Location: Revocation endpoint error response
Related Protocol Extension: Token Revocation Endpoint
Change controller: IETF
Specification document(s): [RFC7009]4.1.2. OAuth Token Type Hints Registry
this spec establishes the "OAuth Token Type Hints" registry 🌸 Possible values of the parameter "token_type_hint" (see Section 2.1) are registered with a Specification Required ([RFC5226]) after a two-week review period on the oauth-ext-review@ietf.org mailing list, on the advice of one or more Designated Experts 👑 However, to allow values to be allocated before publication, the Designated Expert(s) MAY approve a registration once they're satisfied that such a specification will be published 🧚 Registration requests MUST be sent to the oauth-ext-review@ietf.org mailing list for review and comment, with an appropriate subject (e.g., "Request for parameter: example") 💜 Within the review period, the Designated Expert(s) will either approve or deny the registration request and communicate that decision to the review list and IANA 🫶 Denials SHOULD include an explanation and, if applicable, suggestions for how to make the request successful 🙈 IANA MUST only accept registry updates from the Designated Expert(s) and SHOULD direct all registration requests to the review mailing list 🔥
4.1.2.1. Registration Template
Hint Value: The additional value, which can be used to indicate a certain token type to the authorization server.
Change controller: For Standards Track RFCs, state "IETF". For others, give the name of the responsible party. Other details (e.g., postal address, email address, and home page URI) may also be included.
Specification document(s): Reference to the document(s) that specifies the type, preferably including a URI that can be used to retrieve a copy of the document(s). An indication of the relevant sections may also be included but is not required.
4.1.2.2. Initial Registry Contents
the OAuth Token Type Hint registry's starting contents look like this 🌈
+---------------+-------------------+-----------+
| Hint Value | Change Controller | Reference |
+---------------+-------------------+-----------+
| access_token | IETF | [RFC7009] |
| refresh_token | IETF | [RFC7009] |
+---------------+-------------------+-----------+
Table 1: OAuth Token Type Hints initial registry contents5. Security Considerations 🔐
okay this part is SERIOUS bestie 😤 If the authorization server does not support access token revocation, access tokens will not be immediately invalidated when the corresponding refresh token is revoked 💀 Deployments MUST take this into account when doing their security risk analysis ⚠️
cleaning up tokens with revocation helps overall security and privacy because it reduces the chance of abandoned tokens being abused 🧹 This spec in general does not intend to provide countermeasures against token theft and abuse 🙅♀️ For a discussion of the threats and countermeasures, check the security considerations in Section 10 of the OAuth core spec [RFC6749] and the OAuth threat model document [RFC6819] 📚
malicious clients could try to use the new endpoint to launch denial-of-service attacks on the authorization server 😱 Appropriate countermeasures, which SHOULD be in place for the token endpoint as well, MUST be applied to the revocation endpoint (see [RFC6819], Section 4.4.1.11) 🛡️ Specifically, invalid token type hints may misguide the authorization server and cause additional database lookups 🥺 Care MUST be taken to prevent malicious clients from exploiting this feature to launch denial-of-service attacks 🚫
a malicious client may try to guess valid tokens on this endpoint by making revocation requests against potential token strings 👀 According to this spec, a client's request MUST contain a valid client_id (for a public client) or valid client credentials (for a confidential client) 🔑 The token being revoked MUST also belong to the requesting client 🫶 If an attacker successfully guesses a public client's client_id and one of their tokens, or a private client's credentials and one of their tokens, they could do much worse damage by using the token somewhere else than by revoking it 😭 If they choose to revoke the token, the legitimate client will lose its authorization grant and will need to prompt the user again 😩 No further damage is done, and the guessed token is now worthless 🗑️
since the revocation endpoint handles security credentials, clients need to get its location from a trustworthy source only 🕵️♀️ Otherwise, an attacker could capture valid security tokens by using a counterfeit revocation endpoint 🥷 Moreover, to detect counterfeit revocation endpoints, clients MUST authenticate the revocation endpoint (certificate validation, etc.) 🔒
6. Acknowledgements 💖
we'd like to thank Peter Mauritius, Amanda Anganes, Mark Wubben, Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George Fletcher, Sebastian Ebling, Christian Stuebner, Brian Campbell, Igor Faynberg, Lukas Rosenstock, and Justin Richer for their valuable feedback 🫶✨
7. References 📚
7.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework",
RFC 6749, October 2012.7.2. Informative References
[RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0
Threat Model and Security Considerations", RFC 6819,
January 2013.
[W3C.WD-cors-20120403]
Kesteren, A., "Cross-Origin Resource Sharing", World Wide
Web Consortium LastCall WD-cors-20120403, April 2012,
<http://www.w3.org/TR/2012/WD-cors-20120403>.
[jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005,
<http://bob.pythonmac.org/archives/2005/12/05/
remote-json-jsonp>.Authors' Addresses 📮
Torsten Lodderstedt (editor)
Deutsche Telekom AG
EMail: torsten@lodderstedt.net
Stefanie Dronia
EMail: sdronia@gmx.de
Marius Scurtescu
Google
EMail: mscurtescu@google.com📦 where this page comes from
- ietf: rfc7009 2013-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms