idnits 2.17.1 draft-ietf-oauth-revocation-11.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 == Line 321 has weird spacing: '...or name unsup...' == Line 323 has weird spacing: '...ocation revoc...' -- The document date (July 13, 2013) is 3902 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) == Unused Reference: 'RFC2246' is defined on line 440, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 447, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 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: January 14, 2014 6 M. Scurtescu 7 Google 8 July 13, 2013 10 OAuth 2.0 Token Revocation 11 draft-ietf-oauth-revocation-11 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 January 14, 2014. 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 63 2. Token Revocation . . . . . . . . . . . . . . . . . . . . . . 3 64 2.1. Revocation Request . . . . . . . . . . . . . . . . . . . 3 65 2.2. Revocation Response . . . . . . . . . . . . . . . . . . . 5 66 2.2.1. Error Response . . . . . . . . . . . . . . . . . . . 5 67 2.3. Cross-Origin Support . . . . . . . . . . . . . . . . . . 6 68 3. Implementation Note . . . . . . . . . . . . . . . . . . . . . 6 69 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 4.1. OAuth Extensions Error Registration . . . . . . . . . . . 7 71 4.1.1. The "unsupported_token_type" Error Value . . . . . . 7 72 4.1.2. OAuth Token Type Hint Registry . . . . . . . . . . . 8 73 4.1.2.1. Registration Template . . . . . . . . . . . . . . 8 74 4.1.2.2. Initial Registry Contents . . . . . . . . . . . . 8 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 76 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 77 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 78 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 79 7.2. Informative References . . . . . . . . . . . . . . . . . 10 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 82 1. Introduction 84 The OAuth 2.0 core specification [RFC6749] defines several ways for a 85 client to obtain refresh and access tokens. This specification 86 supplements the core specification with a mechanism to revoke both 87 types of tokens. A token is a string representing an authorization 88 grant issued by the resource owner to the client. A revocation 89 request will invalidate the actual token and, if applicable, other 90 tokens based on the same authorization grant and the authorization 91 grant itself. 93 From an end-user's perspective, OAuth is often used to log into a 94 certain site or application. This revocation mechanism allows a 95 client to invalidate its tokens if the end-user logs out, changes 96 identity, or uninstalls the respective application. Notifying the 97 authorization server that the token is no longer needed allows the 98 authorization server to clean up data associated with that token 99 (e.g. session data) and the underlying authorization grant. This 100 behavior prevents a situation where there is still a valid 101 authorization grant for a particular client which the end user is not 102 aware of. This way, token revocation prevents abuse of abandoned 103 tokens and facilitates a better end-user experience since invalidated 104 authorization grants will no longer turn up in a list of 105 authorization grants the authorization server might present to the 106 end-user. 108 2. Token Revocation 110 Implementations MUST support the revocation of refresh tokens and 111 SHOULD support the revocation of access tokens (see Implementation 112 Note). 114 The client requests the revocation of a particular token by making an 115 HTTP POST request to the token revocation endpoint URL. This URL 116 MUST conform to the rules given in [RFC6749], section 3.1. Clients 117 MUST verify that the URL is an HTTPS URL. 119 The means to obtain the location of the revocation endpoint is out of 120 scope of this specification. For example, the client developer may 121 consult the server's documentation or automatic discovery may be 122 used. As this endpoint is handling security credentials, the 123 endpoint location needs to be obtained from a trustworthy source. 125 Since requests to the token revocation endpoint result in the 126 transmission of plain text credentials in the HTTP request, URLs for 127 token revocation endpoints MUST be HTTPS URLs. The authorization 128 server MUST use Transport Layer Security (TLS) in a version compliant 129 with [RFC6749], section 1.6. Implementations MAY also support 130 additional transport-layer security mechanisms that meet their 131 security requirements. 133 If the host of the token revocation endpoint can also be reached over 134 HTTP, then the server SHOULD also offer a revocation service at the 135 corresponding HTTP URI, but MUST NOT publish this URI as a token 136 revocation endpoint. This ensures that tokens accidentally sent over 137 HTTP will be revoked. 139 2.1. Revocation Request 141 The client constructs the request by including the following 142 parameters using the "application/x-www-form-urlencoded" format in 143 the HTTP request entity-body: 145 token REQUIRED. The token that the client wants to get revoked. 147 token_type_hint OPTIONAL. A hint about the type of the token 148 submitted for revocation. Clients MAY pass this parameter in 149 order to help the authorization server to optimize the token 150 lookup. If the server is unable to locate the token using 151 the given hint, it MUST extend its search accross all of its 152 supported token types. An authorization server MAY ignore 153 this parameter, particularly if it is able to detect the 154 token type automatically. This specification defines two 155 such values: 157 * access_token: An Access Token as defined in [RFC6749], 158 section 1.4 160 * refresh_token: A Refresh Token as defined in [RFC6749], 161 section 1.5 163 Specific implementations, profiles, and extensions of this 164 specification MAY define other values for this parameter 165 using the registry defined in Section 4.1.2. 167 The client also includes its authentication credentials as described 168 in Section 2.3. of [RFC6749]. 170 For example, a client may request the revocation of a refresh token 171 with the following request: 173 POST /revoke HTTP/1.1 174 Host: server.example.com 175 Content-Type: application/x-www-form-urlencoded 176 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 178 token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token 180 The authorization server first validates the client credentials (in 181 case of a confidential client) and then verifies whether the token 182 was issued to the client making the revocation request. If this 183 validation fails, the request is refused and the client is informed 184 of the error by the authorization server as described below. 186 In the next step, the authorization server invalidates the token. 187 The invalidation takes place immediately, and the token can not be 188 used again after the revocation. In practice there could be a 189 propagation delay, for example, in which some servers know about the 190 invalidation while others do not. Implementations should minimize 191 that window, and clients must not try to use the token after receipt 192 of an HTTP 200 response from the server. 194 Depending on the authorization server's revocation policy, the 195 revocation of a particular token may cause the revocation of related 196 tokens and the underlying authorization grant. If the particular 197 token is a refresh token and the authorization server supports the 198 revocation of access tokens, then the authorization server SHOULD 199 also invalidate all access tokens based on the same authorization 200 grant (see Implementation Note). If the token passed to the request 201 is an access token, the server MAY revoke the respective refresh 202 token as well. 204 Note: A client compliant with [RFC6749] must be prepared to handle 205 unexpected token invalidation at any time. Independent of the 206 revocation mechanism specified in this document, resource owners may 207 revoke authorization grants or the authorization server may 208 invalidate tokens in order to mitigate security threats. Thus having 209 different server policies with respect to cascading the revocation of 210 tokens should not pose interoperability problems. 212 2.2. Revocation Response 214 The authorization server responds with HTTP status code 200 if the 215 token has been revoked sucessfully or if the client submitted an 216 invalid token. 218 Note: invalid tokens do not cause an error response since the client 219 cannot handle such an error in a reasonable way. Moreover, the 220 purpose of the revocation request, invalidating the particular token, 221 is already achieved. 223 The content of the response body is ignored by the client as all 224 necessary information is conveyed in the response code. 226 An invalid token type hint value is ignored by the authorization 227 server and does not influence the revocation response. 229 2.2.1. Error Response 231 The error presentation conforms to the definition in section 5.2 of 232 [RFC6749]. The following additional error code is defined for the 233 token revocation endpoint: 235 unsupported_token_type The authorization server does not support the 236 revocation of the presented token type. I.e. the client 237 tried to revoke an access token on a server not supporting 238 this feature. 240 If the server responds with HTTP status code 503, the client must 241 assume the token still exists and may retry after a reasonable delay. 243 The server may include a "Retry-After" header in the response to 244 indicate how long the service is expected to be unavailable to the 245 requesting client. 247 2.3. Cross-Origin Support 249 The revocation end-point MAY support CORS (Cross-Origin Resource 250 Sharing) if it is aimed at use in combination with user-agent-based 251 applications. 253 In addition, for interoperability with legacy user-agents, it MAY 254 also offer JSONP (Remote JSON - JSONP) by allowing GET requests with 255 an additional parameter: 257 callback OPTIONAL. The qualified name of a JavaScript function. 259 For example, a client may request the revocation of an access token 260 with the following request (line breaks are for display purposes 261 only): 263 https://example.com/revoke?token=agabcdefddddafdd& 264 callback=package.myCallback 266 Successful response: 268 package.myCallback(); 270 Error response: 272 package.myCallback({"error":"unsupported_token_type"}); 274 Clients should be aware that when relying on JSONP, a malicious 275 revocation end-point may attempt to inject malicious code into the 276 client. 278 3. Implementation Note 280 OAuth 2.0 allows deployment flexibility with respect to the style of 281 access tokens. The access tokens may be self-contained so that an 282 resource server needs no further interaction with an authorization 283 server issuing these tokens to perform an authorization decision of 284 the client requesting access to a protected resource. A system 285 design may, however, instead use access tokens that are handles 286 referring to authorization data stored at the authorization server. 287 This consequently requires a resource server to issue a request to 288 the respective authorization server to retrieve the content of the 289 access token every time a client presents an access token. 291 While these are not the only options they illustrate the implications 292 for revocation. In the latter case the authorization server is able 293 to revoke an access token previously issued to a client when the 294 resource server relays a received access token. In the former case 295 some (currently non-standardized) backend interaction between the 296 authorization server and the resource server may be used when 297 immediate access token revocation is desired. Another design 298 alternative is to issue short-lived access tokens, which can be 299 refreshed at any time using the corresponding refresh tokens. This 300 allows the authorization server to impose a limit on the time revoked 301 access tokens are in use. 303 Which approach of token revocation is chosen will depend on the 304 overall system design and on the application service provider's risk 305 analysis. The cost of revocation in terms of required state and 306 communication overhead is ultimately the result of the desired 307 security properties. 309 4. IANA Considerations 311 This specification registers an error value in the OAuth Extension 312 Error registry and establishes the OAuth Token Type registry. 314 4.1. OAuth Extensions Error Registration 316 This specification registers the following error values in the OAuth 317 Extensions Error registry defined in [RFC6749]. 319 4.1.1. The "unsupported_token_type" Error Value 321 Error name unsupported_token_type 323 Error usage location revocation endpoint error response 325 Related protocol extension Token Revocation Endpoint 327 Change controller IETF 329 Specification document(s) [this document] 331 4.1.2. OAuth Token Type Hint Registry 333 This specification establishes the OAuth Token Type Hint registry. 334 Possible values of the parameter "token_type_hint" (see Section 2.1) 335 are registered with a Specification Required ([RFC5226]) after a two- 336 week review period on the TBD@ietf.org mailing list, on the advice of 337 one or more Designated Experts. However, to allow for the allocation 338 of values prior to publication, the Designated Expert(s) may approve 339 registration once they are satisfied that such a specification will 340 be published. Registration requests must be sent to the TBD@ietf.org 341 mailing list for review and comment, with an appropriate subject 342 (e.g., "Request for parameter: example"). Within the review period, 343 the Designated Expert(s) will either approve or deny the registration 344 request, communicating this decision to the review list and IANA. 345 Denials should include an explanation and, if applicable, suggestions 346 as to how to make the request successful. IANA must only accept 347 registry updates from the Designated Expert(s) and should direct all 348 requests for registration to the review mailing list. 350 4.1.2.1. Registration Template 352 Hint Value: The additional value, which can be used to indicate a 353 certain token type to the authorization server. 355 Change controller: For Standards Track RFCs, state "IETF". For 356 others, give the name of the responsible party. Other details 357 (e.g., postal address, email address, home page URI) may also be 358 included. 360 Specification document(s): Reference to the document(s) that specify 361 the type, preferably including a URI that can be used to retrieve 362 a copy of the document(s). An indication of the relevant sections 363 may also be included but is not required. 365 4.1.2.2. Initial Registry Contents 367 The OAuth Token Type Hint registry's initial contents are: 369 o Hint Value: access_token 371 o Change controller: IETF 373 o Specification document(s): [this document] 375 o Hint Value: refresh_token 377 o Change controller: IETF 378 o Specification document(s): [this document] 380 5. Security Considerations 382 If the authorization server does not support access token revocation, 383 access tokens will not be immediately invalidated when the 384 corresponding refresh token is revoked. Deployments must take this 385 into account when conducting their security risk analysis. 387 Cleaning up tokens using revocation contributes to overall security 388 and privacy since it reduces the likelihood for abuse of abandoned 389 tokens. This specification in general does not intend to provide 390 countermeasures against token theft and abuse. For a discussion of 391 respective threats and countermeasures, consult the security 392 considerations given in section 10 of the OAuth core specification 393 [RFC6749] and the OAuth threat model document [RFC6819]. 395 Malicious clients could attempt to use the new endpoint to launch 396 denial of service attacks on the authorization server. Appropriate 397 countermeasures, which should be in place for the token endpoint as 398 well, MUST be applied to the revocation endpoint (see [RFC6819], 399 section 4.4.1.11). Specifically, invalid token type hints may 400 misguide the authorization server and cause additional database 401 lookups. Care MUST be taken to prevent malicious clients from 402 exploiting this feature to launch denial of service attacks. 404 A malicious client may attempt to guess valid tokens on this endpoint 405 by making revocation requests against potential token strings. 406 According to this specification, a client's request must contain a 407 valid client_id, in the case of a public client, or valid client 408 credentials, in the case of a confidential client. The token being 409 revoked must also belong to the requesting client. If an attacker is 410 able to successfully guess a public client's client_id and one of 411 their tokens, or a private client's credentials and one of their 412 tokens, they could do much worse damage by using the token elsewhere 413 than by revoking it. If they chose to revoke the token, the 414 legitimate client will lose its authorization grant and will need to 415 prompt the user again. No further damage is done and the guessed 416 token is now worthless. 418 Since the revocation endpoint is handling security credentials, 419 clients need to obtain its location from a trustworthy source only. 420 Otherwise, an attacker could capture valid security tokens by 421 utilizing a counterfeit revocation endpoint. Moreover in order to 422 detect counterfeit revocation endpoints, clients MUST authenticate 423 the revocation endpoint (certificate validation etc.). 425 6. Acknowledgements 427 We would like to thank Peter Mauritius, Amanda Anganes, Mark Wubben, 428 Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George 429 Fletcher, Sebastian Ebling, Christian Stuebner, Brian Campbell, Igor 430 Faynberg, Lukas Rosenstock, and Justin Richer for their valuable 431 feedback. 433 7. References 435 7.1. Normative References 437 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 438 Requirement Levels", BCP 14, RFC 2119, March 1997. 440 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 441 RFC 2246, January 1999. 443 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 444 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 445 May 2008. 447 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 448 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 450 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 451 6749, October 2012. 453 7.2. Informative References 455 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 456 Threat Model and Security Considerations", RFC 6819, 457 January 2013. 459 [W3C.WD-cors-20120403] 460 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 461 Web Consortium LastCall WD-cors-20120403, April 2012, 462 . 464 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005, . 468 Authors' Addresses 470 Torsten Lodderstedt (editor) 471 Deutsche Telekom AG 473 Email: torsten@lodderstedt.net 475 Stefanie Dronia 477 Email: sdronia@gmx.de 479 Marius Scurtescu 480 Google 482 Email: mscurtescu@google.com