idnits 2.17.1 draft-ietf-oauth-revocation-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 24, 2012) is 4143 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group T. Lodderstedt, Ed. 3 Internet-Draft Deutsche Telekom AG 4 Intended status: Standards Track S. Dronia 5 Expires: May 28, 2013 6 M. Scurtescu 7 Google 8 November 24, 2012 10 Token Revocation 11 draft-ietf-oauth-revocation-03 13 Abstract 15 This document proposes an additional endpoint for OAuth authorization 16 servers, which allows clients to notify the authorization server that 17 a previously obtained refresh or access token is no longer needed. 18 This allows the authorization server to cleanup security credentials. 19 A revocation request will invalidate the actual token and, if 20 applicable, other tokens based on the same access grant. 22 Requirements Language 24 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 25 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 26 document are to be interpreted as described in RFC 2119 [RFC2119]. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on May 28, 2013. 45 Copyright Notice 47 Copyright (c) 2012 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Token Revocation . . . . . . . . . . . . . . . . . . . . . . . 3 64 2.1. Cross-Origin Support . . . . . . . . . . . . . . . . . . . 5 65 3. Implementation Note . . . . . . . . . . . . . . . . . . . . . . 5 66 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 67 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 69 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 7.1. Normative References . . . . . . . . . . . . . . . . . . . 7 71 7.2. Informative References . . . . . . . . . . . . . . . . . . 7 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 7 74 1. Introduction 76 The OAuth 2.0 core specification [RFC6749] defines several ways for a 77 client to obtain refresh and access tokens. This specification 78 supplements the core specification with a mechanism to revoke both 79 types of tokens. A token is the external representation of an access 80 grant issued by a resource owner to a particular client. A 81 revocation request will invalidate the actual token and, if 82 applicable, other tokens based on the same access grant and the 83 access grant itself. 85 From an end-user's perception, OAuth is often used to log into a 86 certain site or app. This revocation mechanism allows a client to 87 invalidate its tokens if the end-user logs out, changes identity, or 88 uninstalls the respective app. Notifying the authorization server 89 that the token is no longer needed allows the authorization server to 90 clean up data associated with that token (e.g. session data) and the 91 underlying access grant. This behavior prevents a situation where 92 there is still a valid access grant for a particular client which the 93 end user is not aware of. This way, token revocation prevents abuse 94 of abandoned tokens and facilitates a better end-user experience 95 since invalidated access grants will no longer turn up in a list of 96 access grants the authorization server might present to the end-user. 98 2. Token Revocation 100 The client requests the revocation of a particular token by making an 101 HTTP POST request to the token revocation endpoint. The location of 102 the token revocation endpoint can be found in the authorization 103 server's documentation. The token endpoint URI MAY include a query 104 component. 106 Implementations MUST support the revocation of refresh tokens and 107 SHOULD support the revocation of access tokens (see Implementation 108 Note). 110 Since requests to the token revocation endpoint result in the 111 transmission of plain text credentials in the HTTP request, the 112 authorization server MUST require the use of a transport-layer 113 security mechanism when sending requests to the token revocation 114 endpoints. The authorization server MUST support TLS 1.0 115 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 116 replacements, and MAY support additional transport-layer mechanisms 117 meeting its security requirements. 119 The client constructs the request by including the following 120 parameters using the "application/x-www-form-urlencoded" format in 121 the HTTP request entity-body: 123 token REQUIRED. The token that the client wants to get revoked. 124 Note: the authorization server is supposed to detect the 125 token type automatically. 127 The client also includes its authentication credentials as described 128 in Section 2.3. of [RFC6749]. 130 For example, a client may request the revocation of a refresh token 131 with the following request (line breaks are for display purposes 132 only): 134 POST /revoke HTTP/1.1 135 Host: server.example.com 136 Content-Type: application/x-www-form-urlencoded 137 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 139 token=45ghiukldjahdnhzdauz& 141 The authorization server first validates the client credentials (in 142 case of a confidential client) and verifies whether the client is 143 authorized to revoke the particular token. These checks are used to 144 validate whether the token being presented has been issued to the 145 client presenting it. 147 In the next step, the authorization server invalidates the token and 148 the respective access grant. If the particular token is a refresh 149 token and the authorization server supports the revocation of access 150 tokens, then the authorization server SHOULD also invalidate all 151 access tokens based on the same access grant (see Implementation 152 Note). 154 The client MUST NOT use the token again after revocation. 156 The authorization server indicates a successful processing of the 157 request by a HTTP status code 200. Status code 401 indicates a 158 failed client authentication, whereas a status code 403 is used if 159 the client is not authorized to revoke the particular token. For all 160 other error conditions, a status code 400 is used along with an error 161 response as defined in section 5.2. of [RFC6749]. The following 162 error codes are defined for the token revocation endpoint: 164 unsupported_token_type The authorization server does not support the 165 revocation of the presented token type. I.e. the client 166 tried to revoke an access token on a server not supporting 167 this feature. 169 invalid_token The presented token is invalid. 171 2.1. Cross-Origin Support 173 The revokation end-point SHOULD support CORS [W3C.WD-cors-20120403] 174 if it is aimed at use in combination with user-agent-based 175 applications. In addition, for interoperability with legacy user- 176 agents, it MAY offer JSONP [jsonp] by allowing GET requests with an 177 additional parameter: 179 callback The qualified name of a JavaScript function. 181 Example request: 183 https://example.com/revoke?token=45ghiukldjahdnhzdauz& 184 callback=package.myCallback 186 Successful response: 188 package.myCallback(); 190 Error response: 192 package.myCallback({"error":"invalid_token"}); 194 Clients should be aware that when relying on JSONP, a malicious 195 revokation end-point may attempt to inject malicious code into the 196 client. 198 3. Implementation Note 200 Depending on the authorization server's token design, revocation of 201 access tokens might be a costly process. For example, revocation of 202 self-contained access tokens requires (time-consuming) backend calls 203 between resource and authorization server on every request to the 204 resource server or to push notifications from the authorization 205 server to the affected resource servers. Alternatively, 206 authorization servers may choose to issue short living access tokens, 207 which can be refreshed at any time using the corresponding refresh 208 tokens. In this case, a client would revoke the refresh token and 209 access tokens issued based on this particular refresh token are at 210 most valid until expiration. Whether this is an viable option or 211 whether access token revocation is required should be decided based 212 on the service provider's risk analysis. 214 4. Acknowledgements 216 We would like to thank Hannes Tschofenig, Michiel de Jong, Doug 217 Foiles, Paul Madsen, George Fletcher, Sebastian Ebling, Christian 218 Stuebner, Brian Campbell, Igor Faynberg, Lukas Rosenstock, and Justin 219 Richer for their valuable feedback. 221 5. IANA Considerations 223 This draft includes no request to IANA. 225 6. Security Considerations 227 If the authorization server does not support access token revocation, 228 access tokens will not be immediately invalidated when the 229 corresponding refresh token is revoked. Deployments MUST take this 230 in account when conducting their security risk analysis. 232 Cleaning up tokens using revocation contributes to overall security 233 and privacy since it reduces the likelihood for abuse of abandoned 234 tokens. This specification in general does not intend to provide 235 countermeasures against token theft and abuse. For a discussion of 236 respective threats and countermeasures, consult the security 237 considerations given in section 10 of the OAuth core specification 238 [RFC6749] and the OAuth threat model document 239 [I-D.ietf-oauth-v2-threatmodel]. 241 Malicious clients could attempt to use the new endpoint to launch 242 denial of service attacks on the authorization server. Appropriate 243 countermeasures, which should be in place for the token endpoint as 244 well, MUST be applied to the revocation endpoint. 246 A malicious client may attempt to guess valid tokens on this 247 endpoints. As a pre-requisite, the client either requires a valid 248 client_id of a public client or the credentials of a confidential 249 client. An sucessful attempt would result in the revocation of the 250 respective token, thus causing the legitimate client to lose its 251 authorization. The malicious client does not gain further 252 advantages. 254 7. References 255 7.1. Normative References 257 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 258 Requirement Levels", BCP 14, RFC 2119, March 1997. 260 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 261 RFC 2246, January 1999. 263 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 264 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 266 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 267 RFC 6749, October 2012. 269 7.2. Informative References 271 [I-D.ietf-oauth-v2-threatmodel] 272 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 273 Threat Model and Security Considerations", 274 draft-ietf-oauth-v2-threatmodel-08 (work in progress), 275 October 2012. 277 [W3C.WD-cors-20120403] 278 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 279 Web Consortium LastCall WD-cors-20120403, April 2012, 280 . 282 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005. 284 Authors' Addresses 286 Torsten Lodderstedt (editor) 287 Deutsche Telekom AG 289 Email: torsten@lodderstedt.net 291 Stefanie Dronia 293 Email: sdronia@gmx.de 295 Marius Scurtescu 296 Google 298 Email: mscurtescu@google.com