idnits 2.17.1 draft-ietf-oauth-revocation-10.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 314 has weird spacing: '...or name unsup...' == Line 316 has weird spacing: '...ocation revoc...' -- The document date (June 16, 2013) is 3966 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 433, but no explicit reference was found in the text == Unused Reference: 'RFC5246' is defined on line 440, 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: December 18, 2013 6 M. Scurtescu 7 Google 8 June 16, 2013 10 OAuth 2.0 Token Revocation 11 draft-ietf-oauth-revocation-10 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 December 18, 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 . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . 7 73 4.1.2.1. Registration Template . . . . . . . . . . . . . . 8 74 4.1.2.2. Initial Registry Contents . . . . . . . . . . . . 8 75 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 77 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 78 7.1. Normative References . . . . . . . . . . . . . . . . . . 10 79 7.2. Informative References . . . . . . . . . . . . . . . . . 10 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 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. 118 The means to obtain the location of the revocation endpoint is out of 119 scope of this specification. For example, the client developer may 120 consult the server's documentation or automatic discovery may be 121 used. As this endpoint is handling security credentials, the 122 endpoint location needs to be obtained from a trustworthy source. 124 Since requests to the token revocation endpoint result in the 125 transmission of plain text credentials in the HTTP request, the 126 authorization server MUST require the use of a transport-layer 127 security mechanism when sending requests to the token revocation 128 endpoints. The authorization server MUST use Transport Layer 129 Security (TLS) in a version compliant with [RFC6749], section 1.6. 130 Implementations MAY also support additional transport-layer security 131 mechanisms that meet their security requirements. 133 2.1. Revocation Request 135 The client constructs the request by including the following 136 parameters using the "application/x-www-form-urlencoded" format in 137 the HTTP request entity-body: 139 token REQUIRED. The token that the client wants to get revoked. 141 token_type_hint OPTIONAL. A hint about the type of the token 142 submitted for revocation. Clients MAY pass this parameter in 143 order to help the authorization server to optimize the token 144 lookup. If the server is unable to locate the token using 145 the given hint, it MUST extend its search accross all of its 146 supported token types. An authorization server MAY ignore 147 this parameter, particularly if it is able to detect the 148 token type automatically. This specification defines two 149 such values: 151 * access_token: An Access Token as defined in [RFC6749], 152 section 1.4 154 * refresh_token: A Refresh Token as defined in [RFC6749], 155 section 1.5 157 Specific implementations, profiles, and extensions of this 158 specification MAY define other values for this parameter 159 using the registry defined in Section 4.1.2. 161 The client also includes its authentication credentials as described 162 in Section 2.3. of [RFC6749]. 164 For example, a client may request the revocation of a refresh token 165 with the following request: 167 POST /revoke HTTP/1.1 168 Host: server.example.com 169 Content-Type: application/x-www-form-urlencoded 170 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 172 token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token 174 The authorization server first validates the client credentials (in 175 case of a confidential client) and then verifies whether the token 176 was issued to the client making the revocation request. If this 177 validation fails, the request is refused and the client is informed 178 of the error by the authorization server as described below. 180 In the next step, the authorization server invalidates the token. 181 The invalidation takes place immediately, and the token can not be 182 used again after the revocation. In practice there could be a 183 propagation delay, for example, in which some servers know about the 184 invalidation while others do not. Implementations should minimize 185 that window, and clients must not try to use the token after receipt 186 of an HTTP 200 response from the server. 188 Depending on the authorization server's revocation policy, the 189 revocation of a particular token may cause the revocation of related 190 tokens and the underlying authorization grant. If the particular 191 token is a refresh token and the authorization server supports the 192 revocation of access tokens, then the authorization server SHOULD 193 also invalidate all access tokens based on the same authorization 194 grant (see Implementation Note). If the token passed to the request 195 is an access token, the server MAY revoke the respective refresh 196 token as well. 198 Note: A client compliant with [RFC6749] must be prepared to handle 199 unexpected token invalidation at any time. Independent of the 200 revocation mechanism specified in this document, resource owners may 201 revoke authorization grants or the authorization server may 202 invalidate tokens in order to mitigate security threats. Thus having 203 different server policies with respect to cascading the revocation of 204 tokens should not pose interoperability problems. 206 2.2. Revocation Response 208 The authorization server responds with HTTP status code 200 if the 209 token has been revoked sucessfully or if the client submitted an 210 invalid token. 212 Note: invalid tokens do not cause an error response since the client 213 cannot handle such an error in a reasonable way. Moreover, the 214 purpose of the revocation request, invalidating the particular token, 215 is already achieved. 217 The content of the response body is ignored by the client as all 218 necessary information is conveyed in the response code. 220 An invalid token type hint value is ignored by the authorization 221 server and does not influence the revocation response. 223 2.2.1. Error Response 225 The error presentation conforms to the definition in section 5.2 of 226 [RFC6749]. The following additional error code is defined for the 227 token revocation endpoint: 229 unsupported_token_type The authorization server does not support the 230 revocation of the presented token type. I.e. the client 231 tried to revoke an access token on a server not supporting 232 this feature. 234 If the server responds with HTTP status code 503, the client must 235 assume the token still exists and may retry after a reasonable delay. 236 The server may include a "Retry-After" header in the response to 237 indicate how long the service is expected to be unavailable to the 238 requesting client. 240 2.3. Cross-Origin Support 242 The revocation end-point MAY support CORS (Cross-Origin Resource 243 Sharing) if it is aimed at use in combination with user-agent-based 244 applications. 246 In addition, for interoperability with legacy user-agents, it MAY 247 also offer JSONP (Remote JSON - JSONP) by allowing GET requests with 248 an additional parameter: 250 callback OPTIONAL. The qualified name of a JavaScript function. 252 For example, a client may request the revocation of an access token 253 with the following request (line breaks are for display purposes 254 only): 256 https://example.com/revoke?token=agabcdefddddafdd& 257 callback=package.myCallback 259 Successful response: 261 package.myCallback(); 263 Error response: 265 package.myCallback({"error":"unsupported_token_type"}); 267 Clients should be aware that when relying on JSONP, a malicious 268 revocation end-point may attempt to inject malicious code into the 269 client. 271 3. Implementation Note 273 OAuth 2.0 allows deployment flexibility with respect to the style of 274 access tokens. The access tokens may be self-contained so that an 275 resource server needs no further interaction with an authorization 276 server issuing these tokens to perform an authorization decision of 277 the client requesting access to a protected resource. A system 278 design may, however, instead use access tokens that are handles 279 referring to authorization data stored at the authorization server. 280 This consequently requires a resource server to issue a request to 281 the respective authorization server to retrieve the content of the 282 access token every time a client presents an access token. 284 While these are not the only options they illustrate the implications 285 for revocation. In the latter case the authorization server is able 286 to revoke an access token previously issued to a client when the 287 resource server relays a received access token. In the former case 288 some (currently non-standardized) backend interaction between the 289 authorization server and the resource server may be used when 290 immediate access token revocation is desired. Another design 291 alternative is to issue short-lived access tokens, which can be 292 refreshed at any time using the corresponding refresh tokens. This 293 allows the authorization server to impose a limit on the time revoked 294 access tokens are in use. 296 Which approach of token revocation is chosen will depend on the 297 overall system design and on the application service provider's risk 298 analysis. The cost of revocation in terms of required state and 299 communication overhead is ultimately the result of the desired 300 security properties. 302 4. IANA Considerations 304 This specification registers an error value in the OAuth Extension 305 Error registry and establishes the OAuth Token Type registry. 307 4.1. OAuth Extensions Error Registration 309 This specification registers the following error values in the OAuth 310 Extensions Error registry defined in [RFC6749]. 312 4.1.1. The "unsupported_token_type" Error Value 314 Error name unsupported_token_type 316 Error usage location revocation endpoint error response 318 Related protocol extension Token Revocation Endpoint 320 Change controller IETF 322 Specification document(s) [this document] 324 4.1.2. OAuth Token Type Hint Registry 326 This specification establishes the OAuth Token Type Hint registry. 327 Possible values of the parameter "token_type_hint" (see Section 2.1) 328 are registered with a Specification Required ([RFC5226]) after a two- 329 week review period on the TBD@ietf.org mailing list, on the advice of 330 one or more Designated Experts. However, to allow for the allocation 331 of values prior to publication, the Designated Expert(s) may approve 332 registration once they are satisfied that such a specification will 333 be published. Registration requests must be sent to the TBD@ietf.org 334 mailing list for review and comment, with an appropriate subject 335 (e.g., "Request for parameter: example"). Within the review period, 336 the Designated Expert(s) will either approve or deny the registration 337 request, communicating this decision to the review list and IANA. 338 Denials should include an explanation and, if applicable, suggestions 339 as to how to make the request successful. IANA must only accept 340 registry updates from the Designated Expert(s) and should direct all 341 requests for registration to the review mailing list. 343 4.1.2.1. Registration Template 345 Hint Value: The additional value, which can be used to indicate a 346 certain token type to the authorization server. 348 Change controller: For Standards Track RFCs, state "IETF". For 349 others, give the name of the responsible party. Other details 350 (e.g., postal address, email address, home page URI) may also be 351 included. 353 Specification document(s): Reference to the document(s) that specify 354 the type, preferably including a URI that can be used to retrieve 355 a copy of the document(s). An indication of the relevant sections 356 may also be included but is not required. 358 4.1.2.2. Initial Registry Contents 360 The OAuth Token Type Hint registry's initial contents are: 362 o Hint Value: access_token 364 o Change controller: IETF 366 o Specification document(s): [this document] 368 o Hint Value: refresh_token 370 o Change controller: IETF 372 o Specification document(s): [this document] 374 5. Security Considerations 376 If the authorization server does not support access token revocation, 377 access tokens will not be immediately invalidated when the 378 corresponding refresh token is revoked. Deployments must take this 379 into account when conducting their security risk analysis. 381 Cleaning up tokens using revocation contributes to overall security 382 and privacy since it reduces the likelihood for abuse of abandoned 383 tokens. This specification in general does not intend to provide 384 countermeasures against token theft and abuse. For a discussion of 385 respective threats and countermeasures, consult the security 386 considerations given in section 10 of the OAuth core specification 387 [RFC6749] and the OAuth threat model document [RFC6819]. 389 Malicious clients could attempt to use the new endpoint to launch 390 denial of service attacks on the authorization server. Appropriate 391 countermeasures, which should be in place for the token endpoint as 392 well, MUST be applied to the revocation endpoint (see [RFC6819], 393 section 4.4.1.11). Specifically, invalid token type hints may 394 misguide the authorization server and cause additional database 395 lookups. Care MUST be taken to prevent malicious clients from 396 exploiting this feature to launch denial of service attacks. 398 A malicious client may attempt to guess valid tokens on this endpoint 399 by making revocation requests against potential token strings. 400 According to this specification, a client's request must contain a 401 valid client_id, in the case of a public client, or valid client 402 credentials, in the case of a confidential client. The token being 403 revoked must also belong to the requesting client. If an attacker is 404 able to successfully guess a public client's client_id and one of 405 their tokens, or a private client's credentials and one of their 406 tokens, they could do much worse damage by using the token elsewhere 407 than by revoking it. If they chose to revoke the token, the 408 legitimate client will lose its authorization grant and will need to 409 prompt the user again. No further damage is done and the guessed 410 token is now worthless. 412 Since the revocation endpoint is handling security credentials, 413 clients need to obtain its location from a trustworthy source only. 414 Otherwise, an attacker could capture valid security tokens by 415 utilizing a counterfeit revocation endpoint. Moreover in order to 416 detect counterfeit revocation endpoints, clients MUST authenticate 417 the revocation endpoint (certificate validation etc.). 419 6. Acknowledgements 421 We would like to thank Peter Mauritius, Amanda Anganes, Mark Wubben, 422 Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George 423 Fletcher, Sebastian Ebling, Christian Stuebner, Brian Campbell, Igor 424 Faynberg, Lukas Rosenstock, and Justin Richer for their valuable 425 feedback. 427 7. References 428 7.1. Normative References 430 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 431 Requirement Levels", BCP 14, RFC 2119, March 1997. 433 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 434 RFC 2246, January 1999. 436 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 437 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 438 May 2008. 440 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 441 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 443 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 444 6749, October 2012. 446 7.2. Informative References 448 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 449 Threat Model and Security Considerations", RFC 6819, 450 January 2013. 452 [W3C.WD-cors-20120403] 453 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 454 Web Consortium LastCall WD-cors-20120403, April 2012, 455 . 457 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005, . 461 Authors' Addresses 463 Torsten Lodderstedt (editor) 464 Deutsche Telekom AG 466 Email: torsten@lodderstedt.net 468 Stefanie Dronia 470 Email: sdronia@gmx.de 471 Marius Scurtescu 472 Google 474 Email: mscurtescu@google.com