idnits 2.17.1 draft-ietf-oauth-revocation-09.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 298 has weird spacing: '...or name unsup...' == Line 300 has weird spacing: '...ocation revoc...' -- The document date (May 19, 2013) is 3989 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 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 3 errors (**), 0 flaws (~~), 3 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: November 20, 2013 M. Scurtescu 6 Google 7 May 19, 2013 9 OAuth 2.0 Token Revocation 10 draft-ietf-oauth-revocation-09 12 Abstract 14 This document proposes an additional endpoint for OAuth authorization 15 servers, which allows clients to notify the authorization server that 16 a previously obtained refresh or access token is no longer needed. 17 This allows the authorization server to cleanup security credentials. 18 A revocation request will invalidate the actual token and, if 19 applicable, other tokens based on the same authorization grant. 21 Requirements Language 23 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 24 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 25 document are to be interpreted as described in RFC 2119 [RFC2119]. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on November 20, 2013. 44 Copyright Notice 46 Copyright (c) 2013 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 2. Token Revocation . . . . . . . . . . . . . . . . . . . . . . 3 63 2.1. Revocation Request . . . . . . . . . . . . . . . . . . . 3 64 2.2. Revocation Response . . . . . . . . . . . . . . . . . . . 5 65 2.2.1. Error Response . . . . . . . . . . . . . . . . . . . 5 66 2.3. Cross-Origin Support . . . . . . . . . . . . . . . . . . 5 67 3. Implementation Note . . . . . . . . . . . . . . . . . . . . . 6 68 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 69 4.1. OAuth Extensions Error Registration . . . . . . . . . . . 7 70 4.1.1. The "unsupported_token_type" Error Value . . . . . . 7 71 4.1.2. OAuth Token Type Hint Registry . . . . . . . . . . . 7 72 4.1.2.1. Registration Template . . . . . . . . . . . . . . 8 73 4.1.2.2. Initial Registry Contents . . . . . . . . . . . . 8 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 75 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9 76 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 78 7.2. Informative References . . . . . . . . . . . . . . . . . 10 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 81 1. Introduction 83 The OAuth 2.0 core specification [RFC6749] defines several ways for a 84 client to obtain refresh and access tokens. This specification 85 supplements the core specification with a mechanism to revoke both 86 types of tokens. A token is a string representing an authorization 87 grant issued by the resource owner to the client. A revocation 88 request will invalidate the actual token and, if applicable, other 89 tokens based on the same authorization grant and the authorization 90 grant itself. 92 From an end-user's perspective, OAuth is often used to log into a 93 certain site or application. This revocation mechanism allows a 94 client to invalidate its tokens if the end-user logs out, changes 95 identity, or uninstalls the respective application. Notifying the 96 authorization server that the token is no longer needed allows the 97 authorization server to clean up data associated with that token 98 (e.g. session data) and the underlying authorization grant. This 99 behavior prevents a situation where there is still a valid 100 authorization grant for a particular client which the end user is not 101 aware of. This way, token revocation prevents abuse of abandoned 102 tokens and facilitates a better end-user experience since invalidated 103 authorization grants will no longer turn up in a list of 104 authorization grants the authorization server might present to the 105 end-user. 107 2. Token Revocation 109 Implementations MUST support the revocation of refresh tokens and 110 SHOULD support the revocation of access tokens (see Implementation 111 Note). 113 The client requests the revocation of a particular token by making an 114 HTTP POST request to the token revocation endpoint URL. This URL MAY 115 include a query component. The means to obtain the location of the 116 revocation endpoint is out of scope of this specification. For 117 example, the client developer may consult the server's documentation 118 or automatic discovery may be used. As this endpoint is handling 119 security credentials, the endpoint location needs to be obtained from 120 a trustworthy source. 122 Since requests to the token revocation endpoint result in the 123 transmission of plain text credentials in the HTTP request, the 124 authorization server MUST require the use of a transport-layer 125 security mechanism when sending requests to the token revocation 126 endpoints. The authorization server MUST support TLS 1.0 127 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 128 replacements, and MAY support additional transport-layer mechanisms 129 meeting its security requirements. 131 2.1. Revocation Request 133 The client constructs the request by including the following 134 parameters using the "application/x-www-form-urlencoded" format in 135 the HTTP request entity-body: 137 token REQUIRED. The token that the client wants to get revoked. 139 token_type_hint OPTIONAL. A hint about the type of the token 140 submitted for revocation. Clients MAY pass this parameter in 141 order to help the authorization server to optimize the token 142 lookup. If the server is unable to locate the token using 143 the given hint, it MUST extend its search accross all of its 144 supported token types. An authorization server MAY ignore 145 this parameter, particularly if it is able to detect the 146 token type automatically. This specification defines two 147 such values: 149 * access_token: An Access Token as defined in [RFC6749] 150 section 1.4 152 * refresh_token: A Refresh Token as defined in [RFC6749] 153 section 1.5 155 Specific implementations, profiles, and extensions of this 156 specification MAY define other values for this parameter 157 parameter using the registry defined in Section 4.1.2. 159 The client also includes its authentication credentials as described 160 in Section 2.3. of [RFC6749]. 162 For example, a client may request the revocation of a refresh token 163 with the following request: 165 POST /revoke HTTP/1.1 166 Host: server.example.com 167 Content-Type: application/x-www-form-urlencoded 168 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 170 token=45ghiukldjahdnhzdauz&token_type_hint=refresh_token 172 The authorization server first validates the client credentials (in 173 case of a confidential client) and then verifies whether the token 174 was issued to the client making the revocation request. If this 175 validation fails, the request is refused and the client is informed 176 of the error by the authorization server as described below. 178 In the next step, the authorization server invalidates the token. 179 The client MUST assume the revocation is immediate upon the receipt 180 of an HTTP 200 response from the server. The client MUST NOT use the 181 token again after the revocation. 183 Depending on the authorization server's revocation policy, the 184 revocation of a particular token may cause the revocation of related 185 tokens and the underlying authorization grant. If the particular 186 token is a refresh token and the authorization server supports the 187 revocation of access tokens, then the authorization server SHOULD 188 also invalidate all access tokens based on the same authorization 189 grant (see Implementation Note). If the token passed to the request 190 is an access token, the server MAY decide to revoke the respective 191 refresh token as well. 193 Note: A client compliant with [RFC6749] MUST be prepared to handle 194 unexpected token invalidation at any time. Independent of the 195 revocation mechanism specified in this document, resource owners may 196 decide to revoke authorization grants or the authorization server may 197 invalidate tokens in order to mitigate security threats. Thus having 198 different server policies with respect to cascading the revocation of 199 tokens should not pose interoperability problems. 201 2.2. Revocation Response 203 The authorization server responds with HTTP status code 200 if the 204 token has been revoked sucessfully or if the client submitted an 205 invalid token. The content of the response body does not matter as 206 all information is conveyed in the response code. 208 An invalid token type hint value is ignored by the authorization 209 server and does not influence the revocation response. 211 2.2.1. Error Response 213 The error presentation conforms to the defintion in section 5.2 of 214 [RFC6749]. The following additional error code is defined for the 215 token revocation endpoint: 217 unsupported_token_type The authorization server does not support the 218 revocation of the presented token type. I.e. the client 219 tried to revoke an access token on a server not supporting 220 this feature. 222 If the server responds with HTTP status code 503, the client must 223 assume the token still exists and may retry after a reasonable delay. 224 The server may include a "Retry-After" header in the response to 225 indicate how long the service is expected to be unavailable to the 226 requesting client. 228 2.3. Cross-Origin Support 230 The revocation end-point MAY support CORS [W3C.WD-cors-20120403] if 231 it is aimed at use in combination with user-agent-based applications. 233 In addition, for interoperability with legacy user-agents, it MAY 234 also offer JSONP [jsonp] by allowing GET requests with an additional 235 parameter: 237 callback OPTIONAL. The qualified name of a JavaScript function. 239 For example, a client may request the revocation of an access token 240 with the following request (line breaks are for display purposes 241 only): 243 https://example.com/revoke?token=agabcdefddddafdd& 244 callback=package.myCallback 246 Successful response: 248 package.myCallback(); 250 Error response: 252 package.myCallback({"error":"unsupported_token_type"}); 254 Clients should be aware that when relying on JSONP, a malicious 255 revocation end-point may attempt to inject malicious code into the 256 client. 258 3. Implementation Note 260 OAuth 2.0 allows deployment flexibility with respect to the style of 261 access tokens. The access tokens may be self-contained so that an 262 resource server needs no further interaction with an authorization 263 server issuing these tokens to perform an authorization decision of 264 the client requesting access to a protected resource. A system 265 design may, however, instead use access tokens that are handles 266 referring to authorization data stored at the authorization server. 267 This consequently requires a resource server to issue a request to 268 the respective authorization server to retrieve the content of the 269 access token every time a client presents an access token. 271 While these are not the only options they illustrate the implications 272 for revocation. In the latter case the authorization server is able 273 to revoke an access token previously issued to a client when the 274 resource server relays a received access token. In the former case 275 some (currently non-standardized) backend interaction between the 276 authorization server and the resource server may be used when 277 immediate access token revocation is desired. Another design 278 alternative is to issue short-lived access tokens, which can be 279 refreshed at any time using the corresponding refresh tokens. This 280 allows the authorization server to impose a limit on the time revoked 281 access tokens are in use. 283 Which approach of token revocation is chosen will depend on the 284 overall system design and on the application service provider's risk 285 analysis. The cost of revocation in terms of required state and 286 communication overhead is ultimately the result of the desired 287 security properties. 289 4. IANA Considerations 291 4.1. OAuth Extensions Error Registration 293 This specification registers the following error values in the OAuth 294 Extensions Error registry defined in [RFC6749]. 296 4.1.1. The "unsupported_token_type" Error Value 298 Error name unsupported_token_type 300 Error usage location revocation endpoint error response 302 Related protocol extension Token Revocation Endpoint 304 Change controller IETF 306 Specification document(s) [this document] 308 4.1.2. OAuth Token Type Hint Registry 310 This specification establishes the OAuth Token Type Hint registry. 311 Possible values of the parameter "token_type_hint" (see Section 2.1) 312 are registered with a Specification Required ([RFC5226]) after a two- 313 week review period on the TBD@ietf.org mailing list, on the advice of 314 one or more Designated Experts. However, to allow for the allocation 315 of values prior to publication, the Designated Expert(s) may approve 316 registration once they are satisfied that such a specification will 317 be published. Registration requests must be sent to the TBD@ietf.org 318 mailing list for review and comment, with an appropriate subject 319 (e.g., "Request for parameter: example"). Within the review period, 320 the Designated Expert(s) will either approve or deny the registration 321 request, communicating this decision to the review list and IANA. 322 Denials should include an explanation and, if applicable, suggestions 323 as to how to make the request successful. IANA must only accept 324 registry updates from the Designated Expert(s) and should direct all 325 requests for registration to the review mailing list. 327 4.1.2.1. Registration Template 329 Hint Value: The additional value, which can be used to indicate a 330 certain token type to the authorization server. 332 Change controller: For Standards Track RFCs, state "IETF". For 333 others, give the name of the responsible party. Other details 334 (e.g., postal address, email address, home page URI) may also be 335 included. 337 Specification document(s): Reference to the document(s) that specify 338 the type, preferably including a URI that can be used to retrieve 339 a copy of the document(s). An indication of the relevant sections 340 may also be included but is not required. 342 4.1.2.2. Initial Registry Contents 344 The OAuth Token Type Hint registry's initial contents are: 346 o Hint Value: access_token 348 o Change controller: IETF 350 o Specification document(s): [this document] 352 o Hint Value: refresh_token 354 o Change controller: IETF 356 o Specification document(s): [this document] 358 5. Security Considerations 360 If the authorization server does not support access token revocation, 361 access tokens will not be immediately invalidated when the 362 corresponding refresh token is revoked. Deployments must take this 363 into account when conducting their security risk analysis. 365 Cleaning up tokens using revocation contributes to overall security 366 and privacy since it reduces the likelihood for abuse of abandoned 367 tokens. This specification in general does not intend to provide 368 countermeasures against token theft and abuse. For a discussion of 369 respective threats and countermeasures, consult the security 370 considerations given in section 10 of the OAuth core specification 371 [RFC6749] and the OAuth threat model document [RFC6819]. 373 Malicious clients could attempt to use the new endpoint to launch 374 denial of service attacks on the authorization server. Appropriate 375 countermeasures, which should be in place for the token endpoint as 376 well, MUST be applied to the revocation endpoint (see [RFC6819], 377 section 4.4.1.11). Specifically, invalid token type hints may 378 misguide the authorization server and cause additional database 379 lookups. Care MUST be taken to prevent malicious clients from 380 exploiting this feature to launch denial of service attacks. 382 A malicious client may attempt to guess valid tokens on this endpoint 383 by making revocation requests against potential token strings. 384 According to this specification, a client's request must contain a 385 valid client_id, in the case of a public client, or valid client 386 credentials, in the case of a confidential client. The token being 387 revoked must also belong to the requesting client. If an attacker is 388 able to successfully guess a public client's client_id and one of 389 their tokens, or a private client's credentials and one of their 390 tokens, they could do much worse damage by using the token elsewhere 391 than by revoking it. If they chose to revoke the token, the 392 legitimate client will lose its authorization grant and will need to 393 prompt the user again. No further damage is done and the guessed 394 token is now worthless. 396 Since the revocation endpoint is handling security credentials, 397 clients need to obtain its location from a trustworthy source only. 398 Otherwise, an attacker could capture valid security tokens by 399 utilizing a counterfeit revocation endpoint. Moreover in order to 400 detect counterfeit revocation endpoints, clients MUST authenticate 401 the revocation endpoint (certificate validation etc.). 403 6. Acknowledgements 405 We would like to thank Peter Mauritius, Amanda Anganes, Mark Wubben, 406 Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George 407 Fletcher, Sebastian Ebling, Christian Stuebner, Brian Campbell, Igor 408 Faynberg, Lukas Rosenstock, and Justin Richer for their valuable 409 feedback. 411 7. References 413 7.1. Normative References 415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 416 Requirement Levels", BCP 14, RFC 2119, March 1997. 418 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 419 RFC 2246, January 1999. 421 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 422 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 423 May 2008. 425 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 426 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 428 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 429 6749, October 2012. 431 7.2. Informative References 433 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 434 Threat Model and Security Considerations", RFC 6819, 435 January 2013. 437 [W3C.WD-cors-20120403] 438 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 439 Web Consortium LastCall WD-cors-20120403, April 2012, 440 . 442 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005, . 446 Authors' Addresses 448 Torsten Lodderstedt (editor) 449 Deutsche Telekom AG 451 Email: torsten@lodderstedt.net 453 Stefanie Dronia 455 Email: sdronia@gmx.de 457 Marius Scurtescu 458 Google 460 Email: mscurtescu@google.com