idnits 2.17.1 draft-ietf-oauth-revocation-05.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 (February 12, 2013) is 4090 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: August 16, 2013 6 M. Scurtescu 7 Google 8 February 12, 2013 10 Token Revocation 11 draft-ietf-oauth-revocation-05 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 authorization 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 August 16, 2013. 45 Copyright Notice 47 Copyright (c) 2013 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. Revocation Request . . . . . . . . . . . . . . . . . . . . 4 65 2.2. Revocation Response . . . . . . . . . . . . . . . . . . . . 5 66 2.2.1. Error Response . . . . . . . . . . . . . . . . . . . . 5 67 2.3. Cross-Origin Support . . . . . . . . . . . . . . . . . . . 5 68 3. Implementation Note . . . . . . . . . . . . . . . . . . . . . . 6 69 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7 72 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 7.1. Normative References . . . . . . . . . . . . . . . . . . . 8 74 7.2. Informative References . . . . . . . . . . . . . . . . . . 8 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 77 1. Introduction 79 The OAuth 2.0 core specification [RFC6749] defines several ways for a 80 client to obtain refresh and access tokens. This specification 81 supplements the core specification with a mechanism to revoke both 82 types of tokens. A token is a string representing an authorization 83 grant issued by the resource owner to the client. A revocation 84 request will invalidate the actual token and, if applicable, other 85 tokens based on the same authorization grant and the authorization 86 grant itself. 88 From an end-user's perspective, OAuth is often used to log into a 89 certain site or app. This revocation mechanism allows a client to 90 invalidate its tokens if the end-user logs out, changes identity, or 91 uninstalls the respective app. Notifying the authorization server 92 that the token is no longer needed allows the authorization server to 93 clean up data associated with that token (e.g. session data) and the 94 underlying authorization grant. This behavior prevents a situation 95 where there is still a valid authorization grant for a particular 96 client which the end user is not aware of. This way, token 97 revocation prevents abuse of abandoned tokens and facilitates a 98 better end-user experience since invalidated authorization grants 99 will no longer turn up in a list of authorization grants the 100 authorization server might present to the end-user. 102 2. Token Revocation 104 Implementations MUST support the revocation of refresh tokens and 105 SHOULD support the revocation of access tokens (see Implementation 106 Note). 108 The client requests the revocation of a particular token by making an 109 HTTP POST request to the token revocation endpoint URL. The token 110 endpoint URL MAY include a query component. The means to obtain the 111 location of the revocation endpoint is out of scope of this 112 specification. For example, the client developler may consult the 113 server's documentation or automatic discovery may be used. As this 114 endpoint is handling security credentials, the endpoint location MUST 115 be obtained from a trustworthy source. 117 Since requests to the token revocation endpoint result in the 118 transmission of plain text credentials in the HTTP request, the 119 authorization server MUST require the use of a transport-layer 120 security mechanism when sending requests to the token revocation 121 endpoints. The authorization server MUST support TLS 1.0 122 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 123 replacements, and MAY support additional transport-layer mechanisms 124 meeting its security requirements. 126 2.1. Revocation Request 128 The client constructs the request by including the following 129 parameters using the "application/x-www-form-urlencoded" format in 130 the HTTP request entity-body: 132 token REQUIRED. The token that the client wants to get revoked. 134 token_type_hint OPTIONAL. A hint about the type of the token 135 submitted for revocation. Clients MAY pass this parameter in 136 order to help the authorization server to optimize the token 137 lookup. If the server is unable to locate the token using 138 the given hint, it MUST extend its search accross all of its 139 supported token types. An authorization server MAY ignore 140 this parameter, particularly if it is able to detect the 141 token type automatically. This specification defines two 142 such values: 144 * access_token An Access Token as defined in [RFC6749] 145 section 1.4 147 * refresh_token A Refresh Token as defined in [RFC6749] 148 section 1.5 150 Specific implementations, profiles, and extensions of this 151 specification MAY define other values for this parameter. 153 The client also includes its authentication credentials as described 154 in Section 2.3. of [RFC6749]. 156 For example, a client may request the revocation of a refresh token 157 with the following request (line breaks are for display purposes 158 only): 160 POST /revoke HTTP/1.1 161 Host: server.example.com 162 Content-Type: application/x-www-form-urlencoded 163 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 165 token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token 167 The authorization server first validates the client credentials (in 168 case of a confidential client) and then verifies whether the token 169 was issued to the client making the revocation request. If this 170 validation fails, the request is refused and the client is informed 171 of the error by the authorization server as described below. 173 In the next step, the authorization server invalidates the token. 174 The client MUST assume the revocation is immediate upon the return of 175 the request. The client MUST NOT use the token again after the 176 revocation. 178 Depending on the authorization server's revocation policy, the 179 revocation of a particular token may cause the revocation of related 180 tokens and the underlying authorization grant. If the particular 181 token is a refresh token and the authorization server supports the 182 revocation of access tokens, then the authorization server SHOULD 183 also invalidate all access tokens based on the same authorization 184 grant (see Implementation Note). If the token passed to the request 185 is an access token, the server MAY decide to revoke the respective 186 refresh token as well. 188 Note: A client compliant with [RFC6749] must be prepared to handle 189 unexpected token invalidation at any time. Independent of the 190 revocation mechanism specified in this document, resource owners may 191 decide to revoke authorization grants or the authorization server may 192 invalidate tokens in order to mitigate security threats. Thus having 193 different server policies with respect to cascading the revocation of 194 tokens should not pose interoperability problems. 196 2.2. Revocation Response 198 The authorization server indicates a successful processing of the 199 request by a HTTP status code 200. This also applies if the client 200 submits an invalid token to the revocation endpoint. 202 2.2.1. Error Response 204 The error presentation conforms to the defintion in section 5.2 of 205 [RFC6749]. The following additional error code is defined for the 206 token revocation endpoint: 208 unsupported_token_type The authorization server does not support the 209 revocation of the presented token type. I.e. the client 210 tried to revoke an access token on a server not supporting 211 this feature. 213 2.3. Cross-Origin Support 215 The revocation end-point MAY support CORS [W3C.WD-cors-20120403] if 216 it is aimed at use in combination with user-agent-based applications. 218 In addition, for interoperability with legacy user-agents, it MAY 219 also offer JSONP [jsonp] by allowing GET requests with an additional 220 parameter: 222 callback OPTIONAL. The qualified name of a JavaScript function. 224 For example, a client may request the revocation of an access token 225 with the following request (line breaks are for display purposes 226 only): 228 https://example.com/revoke?token=agabcdefddddafdd& 229 callback=package.myCallback 231 Successful response: 233 package.myCallback(); 235 Error response: 237 package.myCallback({"error":"unsupported_token_type"}); 239 Clients should be aware that when relying on JSONP, a malicious 240 revocation end-point may attempt to inject malicious code into the 241 client. 243 3. Implementation Note 245 OAuth 2.0 allows deployment flexibility with respect to the style of 246 access tokens. The access tokens may be self-contained so that an 247 resource server needs no further interaction with an authorization 248 server issuing these tokens to perform an authorization decision of 249 the client requesting access to a protected resource. A system 250 design may, however, instead use access tokens that are handles 251 referring to authorization data stored at the authorization server. 252 This consequently requires a resource server to issue a request to 253 the respective authorization server to retrieve the content of the 254 access token every time a client presents an access token. 256 While these are not the only options they illustrate the implications 257 for revocation. In the latter case the authorization server is able 258 to revoke an access token previously issued to a client when the 259 resource server relays a received access token. In the former case 260 some (currently non-standardized) backend interaction between the 261 authorization server and the resource server may be used when 262 immediate access token revocation is desired. Another design 263 alternative is to issue short-lived access tokens, which can be 264 refreshed at any time using the corresponding refresh tokens. This 265 allows the authorization server to impose a limit on the time revoked 266 access tokens are in use. 268 Which approach of token revocation is chosen will depend on the 269 overall system design and on the application service provider's risk 270 analysis. The cost of revocation in terms of required state and 271 communication overhead is ultimately the result of the desired 272 security properties. 274 4. Acknowledgements 276 We would like to thank Peter, Mauritius, Amanda Anganes, Mark Wubben, 277 Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George 278 Fletcher, Sebastian Ebling, Christian Stuebner, Brian Campbell, Igor 279 Faynberg, Lukas Rosenstock, and Justin Richer for their valuable 280 feedback. 282 5. IANA Considerations 284 This draft includes no request to IANA. 286 6. Security Considerations 288 If the authorization server does not support access token revocation, 289 access tokens will not be immediately invalidated when the 290 corresponding refresh token is revoked. Deployments MUST take this 291 into account when conducting their security risk analysis. 293 Cleaning up tokens using revocation contributes to overall security 294 and privacy since it reduces the likelihood for abuse of abandoned 295 tokens. This specification in general does not intend to provide 296 countermeasures against token theft and abuse. For a discussion of 297 respective threats and countermeasures, consult the security 298 considerations given in section 10 of the OAuth core specification 299 [RFC6749] and the OAuth threat model document 300 [I-D.ietf-oauth-v2-threatmodel]. 302 Malicious clients could attempt to use the new endpoint to launch 303 denial of service attacks on the authorization server. Appropriate 304 countermeasures, which should be in place for the token endpoint as 305 well, MUST be applied to the revocation endpoint (see 306 [I-D.ietf-oauth-v2-threatmodel], section 4.4.1.11). 308 A malicious client may attempt to guess valid tokens on this endpoint 309 by making revocation requests against potential token strings. 311 According to this specification, a client's request must contain a 312 valid client_id, in the case of a public client, or valid client 313 credentials, in the case of a confidential client. The token being 314 revoked must also belong to the requesting client. If an attacker is 315 able to successfully guess a public client's client_id and one of 316 their tokens, or a private client's credentials and one of their 317 tokens, they could do much worse damage by using the token elsewhere 318 than by revoking it. If they chose to revoke the token, the 319 legitimate client will lose its authorization grant and will need to 320 prompt the user again. No further damage is done and the guessed 321 token is now worthless. 323 Since the revocation endpoint is handling security credentials, 324 clients shall obtain its location from a trustworthy source only. 325 Otherwise, an attacker could capture valid security tokens by 326 utilizing a counterfeit revocation endpoint. 328 7. References 330 7.1. Normative References 332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 333 Requirement Levels", BCP 14, RFC 2119, March 1997. 335 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 336 RFC 2246, January 1999. 338 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 339 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 341 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 342 RFC 6749, October 2012. 344 7.2. Informative References 346 [I-D.ietf-oauth-v2-threatmodel] 347 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 348 Threat Model and Security Considerations", 349 draft-ietf-oauth-v2-threatmodel-08 (work in progress), 350 October 2012. 352 [W3C.WD-cors-20120403] 353 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 354 Web Consortium LastCall WD-cors-20120403, April 2012, 355 . 357 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005. 359 Authors' Addresses 361 Torsten Lodderstedt (editor) 362 Deutsche Telekom AG 364 Email: torsten@lodderstedt.net 366 Stefanie Dronia 368 Email: sdronia@gmx.de 370 Marius Scurtescu 371 Google 373 Email: mscurtescu@google.com