idnits 2.17.1 draft-ietf-oauth-revocation-07.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 305 has weird spacing: '...or name unsup...' == Line 307 has weird spacing: '...ocation revoc...' -- The document date (April 15, 2013) is 4027 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) == Missing Reference: 'RFC5226' is mentioned on line 319, but not defined ** Obsolete undefined reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 3 errors (**), 0 flaws (~~), 4 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: October 17, 2013 M. Scurtescu 6 Google 7 April 15, 2013 9 Token Revocation 10 draft-ietf-oauth-revocation-07 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 October 17, 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. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 5.1. OAuth Extensions Error Registration . . . . . . . . . . . 7 71 5.1.1. The "unsupported_token_type" Error Value . . . . . . 7 72 5.1.2. OAuth Token Type Hint Registry . . . . . . . . . . . 7 73 5.1.2.1. Registration Template . . . . . . . . . . . . . . 8 74 5.1.2.2. Initial Registry Contents . . . . . . . . . . . . 8 75 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 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. 117 The means to obtain the location of the revocation endpoint is out of 118 scope of this specification. For example, the client developer may 119 consult the server's documentation or automatic discovery may be 120 used. As this endpoint is handling security credentials, the 121 endpoint location need be obtained from a trustworthy source. 123 Since requests to the token revocation endpoint result in the 124 transmission of plain text credentials in the HTTP request, the 125 authorization server MUST require the use of a transport-layer 126 security mechanism when sending requests to the token revocation 127 endpoints. The authorization server MUST support TLS 1.0 128 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 129 replacements, and MAY support additional transport-layer mechanisms 130 meeting its security requirements. 132 2.1. Revocation Request 134 The client constructs the request by including the following 135 parameters using the "application/x-www-form-urlencoded" format in 136 the HTTP request entity-body: 138 token REQUIRED. The token that the client wants to get revoked. 140 token_type_hint OPTIONAL. A hint about the type of the token 141 submitted for revocation. Clients MAY pass this parameter in 142 order to help the authorization server to optimize the token 143 lookup. If the server is unable to locate the token using 144 the given hint, it MUST extend its search accross all of its 145 supported token types. An authorization server MAY ignore 146 this parameter, particularly if it is able to detect the 147 token type automatically. This specification defines two 148 such values: 150 * access_token An Access Token as defined in [RFC6749] 151 section 1.4 153 * refresh_token A Refresh Token as defined in [RFC6749] 154 section 1.5 156 Specific implementations, profiles, and extensions of this 157 specification MAY define other values for this parameter 158 using the registry defined in Section 5.1.2. 160 The client also includes its authentication credentials as described 161 in Section 2.3. of [RFC6749]. 163 For example, a client may request the revocation of a refresh token 164 with the following request (line breaks are for display purposes 165 only): 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 client MUST assume the revocation is immediate upon receipt of an 182 HTTP 200 response from the server. The client MUST NOT use the token 183 again after the revocation. 185 Depending on the authorization server's revocation policy, the 186 revocation of a particular token may cause the revocation of related 187 tokens and the underlying authorization grant. If the particular 188 token is a refresh token and the authorization server supports the 189 revocation of access tokens, then the authorization server SHOULD 190 also invalidate all access tokens based on the same authorization 191 grant (see Implementation Note). If the token passed to the request 192 is an access token, the server MAY decide to revoke the respective 193 refresh token as well. 195 Note: A client compliant with [RFC6749] MUST be prepared to handle 196 unexpected token invalidation at any time. Independent of the 197 revocation mechanism specified in this document, resource owners may 198 decide to revoke authorization grants or the authorization server may 199 invalidate tokens in order to mitigate security threats. Thus having 200 different server policies with respect to cascading the revocation of 201 tokens should not pose interoperability problems. 203 2.2. Revocation Response 205 The authorization server responds with HTTP status code 200 if the 206 token has been revoked sucessfully or if the client submited an 207 invalid token. The content of the response body does not matter as 208 all information is conveyed in the response code. 210 2.2.1. Error Response 212 The error presentation conforms to the defintion in section 5.2 of 213 [RFC6749]. The following additional error code is defined for the 214 token revocation endpoint: 216 unsupported_token_type The authorization server does not support the 217 revocation of the presented token type. I.e. the client 218 tried to revoke an access token on a server not supporting 219 this feature. 221 If the server responds with HTTP status code 503, the client must 222 assume the token still exists and may retry after a reasonable delay. 223 The server may include a "Retry-After" header in the response to 224 indicate how long the service is expected to be unavailable to the 225 requesting client. 227 2.3. Cross-Origin Support 229 The revocation end-point MAY support CORS [W3C.WD-cors-20120403] if 230 it is aimed at use in combination with user-agent-based applications. 232 In addition, for interoperability with legacy user-agents, it MAY 233 also offer JSONP [jsonp] by allowing GET requests with an additional 234 parameter: 236 callback OPTIONAL. The qualified name of a JavaScript function. 238 For example, a client may request the revocation of an access token 239 with the following request (line breaks are for display purposes 240 only): 242 https://example.com/revoke?token=agabcdefddddafdd& 243 callback=package.myCallback 245 Successful response: 247 package.myCallback(); 249 Error response: 251 package.myCallback({"error":"unsupported_token_type"}); 253 Clients should be aware that when relying on JSONP, a malicious 254 revocation end-point may attempt to inject malicious code into the 255 client. 257 3. Implementation Note 259 OAuth 2.0 allows deployment flexibility with respect to the style of 260 access tokens. The access tokens may be self-contained so that an 261 resource server needs no further interaction with an authorization 262 server issuing these tokens to perform an authorization decision of 263 the client requesting access to a protected resource. A system 264 design may, however, instead use access tokens that are handles 265 referring to authorization data stored at the authorization server. 266 This consequently requires a resource server to issue a request to 267 the respective authorization server to retrieve the content of the 268 access token every time a client presents an access token. 270 While these are not the only options they illustrate the implications 271 for revocation. In the latter case the authorization server is able 272 to revoke an access token previously issued to a client when the 273 resource server relays a received access token. In the former case 274 some (currently non-standardized) backend interaction between the 275 authorization server and the resource server may be used when 276 immediate access token revocation is desired. Another design 277 alternative is to issue short-lived access tokens, which can be 278 refreshed at any time using the corresponding refresh tokens. This 279 allows the authorization server to impose a limit on the time revoked 280 access tokens are in use. 282 Which approach of token revocation is chosen will depend on the 283 overall system design and on the application service provider's risk 284 analysis. The cost of revocation in terms of required state and 285 communication overhead is ultimately the result of the desired 286 security properties. 288 4. Acknowledgements 290 We would like to thank Peter, Mauritius, Amanda Anganes, Mark Wubben, 291 Hannes Tschofenig, Michiel de Jong, Doug Foiles, Paul Madsen, George 292 Fletcher, Sebastian Ebling, Christian Stuebner, Brian Campbell, Igor 293 Faynberg, Lukas Rosenstock, and Justin Richer for their valuable 294 feedback. 296 5. IANA Considerations 298 5.1. OAuth Extensions Error Registration 300 This specification registers the following error values in the OAuth 301 Extensions Error registry defined in [RFC6749]. 303 5.1.1. The "unsupported_token_type" Error Value 305 Error name unsupported_token_type 307 Error usage location revocation endpoint error response 309 Related protocol extension Token Revocation Endpoint 311 Change controller IETF 313 Specification document(s) [this document] 315 5.1.2. OAuth Token Type Hint Registry 317 This specification establishes the OAuth Token Type Hint registry. 318 Possible values of the parameter "token_type_hint" (see Section 2.1) 319 are registered with a Specification Required ([RFC5226]) after a two- 320 week review period on the TBD@ietf.org mailing list, on the advice of 321 one or more Designated Experts. However, to allow for the allocation 322 of values prior to publication, the Designated Expert(s) may approve 323 registration once they are satisfied that such a specification will 324 be published. Registration requests must be sent to the TBD@ietf.org 325 mailing list for review and comment, with an appropriate subject 326 (e.g., "Request for parameter: example"). Within the review period, 327 the Designated Expert(s) will either approve or deny the registration 328 request, communicating this decision to the review list and IANA. 329 Denials should include an explanation and, if applicable, suggestions 330 as to how to make the request successful. IANA must only accept 331 registry updates from the Designated Expert(s) and should direct all 332 requests for registration to the review mailing list. 334 5.1.2.1. Registration Template 336 Hint Value: The additional value, which can be used to indicate a 337 certain token type to the authorization server. 339 Change controller: For Standards Track RFCs, state "IETF". For 340 others, give the name of the responsible party. Other details 341 (e.g., postal address, email address, home page URI) may also be 342 included. 344 Specification document(s): Reference to the document(s) that specify 345 the type, preferably including a URI that can be used to retrieve 346 a copy of the document(s). An indication of the relevant sections 347 may also be included but is not required. 349 5.1.2.2. Initial Registry Contents 351 The OAuth Token Type Hint registry's initial contents are: 353 o Hint Value: access_token 355 o Change controller: IETF 357 o Specification document(s): [this document] 359 o Response type name: refresh_token 361 o Change controller: IETF 363 o Specification document(s): [this document] 365 6. Security Considerations 367 If the authorization server does not support access token revocation, 368 access tokens will not be immediately invalidated when the 369 corresponding refresh token is revoked. Deployments must take this 370 into account when conducting their security risk analysis. 372 Cleaning up tokens using revocation contributes to overall security 373 and privacy since it reduces the likelihood for abuse of abandoned 374 tokens. This specification in general does not intend to provide 375 countermeasures against token theft and abuse. For a discussion of 376 respective threats and countermeasures, consult the security 377 considerations given in section 10 of the OAuth core specification 378 [RFC6749] and the OAuth threat model document [RFC6819]. 380 Malicious clients could attempt to use the new endpoint to launch 381 denial of service attacks on the authorization server. Appropriate 382 countermeasures, which should be in place for the token endpoint as 383 well, MUST be applied to the revocation endpoint (see [RFC6819], 384 section 4.4.1.11). 386 A malicious client may attempt to guess valid tokens on this endpoint 387 by making revocation requests against potential token strings. 388 According to this specification, a client's request must contain a 389 valid client_id, in the case of a public client, or valid client 390 credentials, in the case of a confidential client. The token being 391 revoked must also belong to the requesting client. If an attacker is 392 able to successfully guess a public client's client_id and one of 393 their tokens, or a private client's credentials and one of their 394 tokens, they could do much worse damage by using the token elsewhere 395 than by revoking it. If they chose to revoke the token, the 396 legitimate client will lose its authorization grant and will need to 397 prompt the user again. No further damage is done and the guessed 398 token is now worthless. 400 Since the revocation endpoint is handling security credentials, 401 clients need to obtain its location from a trustworthy source only. 402 Otherwise, an attacker could capture valid security tokens by 403 utilizing a counterfeit revocation endpoint. 405 7. References 407 7.1. Normative References 409 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 410 Requirement Levels", BCP 14, RFC 2119, March 1997. 412 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 413 RFC 2246, January 1999. 415 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 416 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 418 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 419 6749, October 2012. 421 7.2. Informative References 423 [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 424 Threat Model and Security Considerations", RFC 6819, 425 January 2013. 427 [W3C.WD-cors-20120403] 428 Kesteren, A., "Cross-Origin Resource Sharing", World Wide 429 Web Consortium LastCall WD-cors-20120403, April 2012, 430 . 432 [jsonp] Ippolito, B., "Remote JSON - JSONP", December 2005, . 436 [portable-contacts] 437 Smarr, J., "Portable Contacts 1.0 Draft C", August 2008, 438 . 440 Authors' Addresses 442 Torsten Lodderstedt (editor) 443 Deutsche Telekom AG 445 Email: torsten@lodderstedt.net 447 Stefanie Dronia 449 Email: sdronia@gmx.de 451 Marius Scurtescu 452 Google 454 Email: mscurtescu@google.com