idnits 2.17.1 draft-ietf-oauth-v2-bearer-02.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: o The HTTP request method is one for which a body is permitted to be present in the request. In particular, this means that the "GET" method MAY NOT be used. -- The document date (January 28, 2011) is 4837 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) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-09 -- Possible downref: Non-RFC (?) normative reference: ref. 'OAuth2' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track D. Hardt 5 Expires: August 1, 2011 independent 6 D. Recordon 7 Facebook 8 January 28, 2011 10 The OAuth 2.0 Protocol: Bearer Tokens 11 draft-ietf-oauth-v2-bearer-02 13 Abstract 15 This specification describes how to use bearer tokens when accessing 16 OAuth 2.0 protected resources. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 1, 2011. 35 Copyright Notice 37 Copyright (c) 2011 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 54 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 4 57 2.1. The Authorization Request Header Field . . . . . . . . . . 5 58 2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 5 59 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 6 60 3. Security Considerations . . . . . . . . . . . . . . . . . . . 7 61 3.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 7 62 3.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 7 63 3.3. Summary of Recommendations . . . . . . . . . . . . . . . . 8 64 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 65 4.1. OAuth Access Token Type Registration . . . . . . . . . . . 9 66 4.1.1. The "OAuth2" OAuth Access Token Type . . . . . . . . . 9 67 4.2. OAuth Parameters Registration . . . . . . . . . . . . . . 10 68 4.2.1. The "oauth_token" OAuth Parameter . . . . . . . . . . 10 69 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 5.1. Normative References . . . . . . . . . . . . . . . . . . . 10 71 5.2. Informative References . . . . . . . . . . . . . . . . . . 11 72 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 11 73 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 76 1. Introduction 78 OAuth enables clients to access protected resources by obtaining an 79 access token, which is defined in [OAuth2] as "a string representing 80 an access authorization issued to the client", rather than using the 81 resource owner's credentials. 83 Tokens are issued to clients by an authorization server with the 84 approval of the resource owner. The client uses the access token to 85 access the protected resources hosted by the resource server. This 86 specification describes how to make protected resource requests by 87 treating an OAuth access token as a bearer token. 89 This specification defines the use of bearer tokens with OAuth over 90 HTTP [RFC2616] using TLS [RFC2818]. Other specifications may extend 91 it for use with other transport protocols. 93 1.1. Notational Conventions 95 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 96 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 97 document are to be interpreted as described in [RFC2119]. 99 This document uses the Augmented Backus-Naur Form (ABNF) notation of 100 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 101 are included from [RFC2617]: auth-param; and from 102 [I-D.ietf-httpbis-p1-messaging]: RWS. 104 Unless otherwise noted, all the protocol parameter names and values 105 are case sensitive. 107 1.2. Terminology 109 All terms are as defined in [OAuth2]. 111 1.3. Overview 113 OAuth provides a method for clients to access a protected resource on 114 behalf of a resource owner. Before a client can access a protected 115 resource, it must first obtain authorization (access grant) from the 116 resource owner and then exchange the access grant for an access token 117 (representing the grant's scope, duration, and other attributes). 118 The client accesses the protected resource by presenting the access 119 token to the resource server. 121 The access token provides an abstraction layer, replacing different 122 authorization constructs (e.g. username and password, assertion) for 123 a single token understood by the resource server. This abstraction 124 enables issuing access tokens valid for a short time period, as well 125 as removing the resource server's need to understand a wide range of 126 authentication schemes. 128 +--------+ +---------------+ 129 | |--(A)- Authorization Request ->| Resource | 130 | | | Owner | 131 | |<-(B)----- Access Grant -------| | 132 | | +---------------+ 133 | | 134 | | Access Grant & +---------------+ 135 | |--(C)--- Client Credentials -->| Authorization | 136 | Client | | Server | 137 | |<-(D)----- Access Token -------| | 138 | | +---------------+ 139 | | 140 | | +---------------+ 141 | |--(E)----- Access Token ------>| Resource | 142 | | | Server | 143 | |<-(F)--- Protected Resource ---| | 144 +--------+ +---------------+ 146 Figure 1: Abstract Protocol Flow 148 The abstract flow illustrated in Figure 1 describes the overall OAuth 149 2.0 protocol architecture. The following steps are specified within 150 this document: 152 E) The client makes a protected resource request to the resource 153 server by presenting the access token. 155 F) The resource server validates the access token, and if valid, 156 serves the request. 158 2. Authenticated Requests 160 Clients make authenticated token requests using the "Authorization" 161 request header field. Resource servers MUST accept authenticated 162 requests using the "OAuth2" HTTP authentication scheme as described 163 in Section 2.1, and MAY support additional methods. 165 Alternatively, clients MAY attempt to include the access token in the 166 HTTP body when using the "application/x-www-form-urlencoded" content 167 type as described in Section 2.2 or using the HTTP request URI in the 168 query component as described in Section 2.3. Resource servers MAY 169 support these alternative methods. 171 Clients SHOULD only use the request body or URI when the 172 "Authorization" request header field is not available, and MUST NOT 173 use more than one method to transport the token in each request. 174 Because of the Security Considerations (Section 3) associated with 175 the URI method, it SHOULD only be used if no other method is 176 feasible. 178 2.1. The Authorization Request Header Field 180 The "Authorization" request header field is used by clients to make 181 authenticated token requests. The client uses the "OAuth2" 182 authentication scheme to include the access token in the request. 184 For example: 186 GET /resource HTTP/1.1 187 Host: server.example.com 188 Authorization: OAuth2 vF9dft4qmT 190 The "Authorization" header field uses the framework defined by 191 [RFC2617] as follows: 193 credentials = "OAuth2" RWS access-token [ RWS 1#auth-param ] 194 access-token = 1*( quoted-char / <"> ) 196 quoted-char = "!" / "#" / "$" / "%" / "&" / "'" / "(" 197 / ")" / "*" / "+" / "-" / "." / "/" / DIGIT 198 / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA 199 / "[" / "]" / "^" / "_" / "`" / "{" / "|" 200 / "}" / "~" / "\" / "," / ";" 202 2.2. Form-Encoded Body Parameter 204 When including the access token in the HTTP request entity-body, the 205 client adds the access token to the request body using the 206 "oauth_token" parameter. The client can use this method only if the 207 following REQUIRED conditions are met: 209 o The HTTP request entity-body is single-part. 211 o The entity-body follows the encoding requirements of the 212 "application/x-www-form-urlencoded" content-type as defined by 213 [W3C.REC-html401-19991224]. 215 o The HTTP request entity-header includes the "Content-Type" header 216 field set to "application/x-www-form-urlencoded". 218 o The HTTP request method is one for which a body is permitted to be 219 present in the request. In particular, this means that the "GET" 220 method MAY NOT be used. 222 The entity-body can include other request-specific parameters, in 223 which case, the "oauth_token" parameters SHOULD be appended following 224 the request-specific parameters, properly separated by an "&" 225 character (ASCII code 38). 227 For example, the client makes the following HTTP request using 228 transport-layer security: 230 POST /resource HTTP/1.1 231 Host: server.example.com 232 Content-Type: application/x-www-form-urlencoded 234 oauth_token=vF9dft4qmT 236 The "application/x-www-form-urlencoded" method should typically only 237 be used in application contexts where participating browsers do not 238 have access to the "Authorization" request header field. 240 2.3. URI Query Parameter 242 When including the access token in the HTTP request URI, the client 243 adds the access token to the request URI query component as defined 244 by [RFC3986] using the "oauth_token" parameter. 246 For example, the client makes the following HTTP request using 247 transport-layer security: 249 GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 250 Host: server.example.com 252 The HTTP request URI query can include other request-specific 253 parameters, in which case, the "oauth_token" parameters SHOULD be 254 appended following the request-specific parameters, properly 255 separated by an "&" character (ASCII code 38). 257 For example: 259 http://example.com/resource?x=y&oauth_token=vF9dft4qmT 261 Because of the Security Considerations (Section 3) associated with 262 the URI method, it SHOULD only be used if no other method is 263 feasible. 265 3. Security Considerations 267 This section describes the relevant security threats regarding token 268 handling when using bearer tokens and describes how to mitigate these 269 threats. 271 3.1. Security Threats 273 The following list presents several common threats against protocols 274 utilizing some form of tokens. This list of threats is based on NIST 275 Special Publication 800-63 [NIST800-63]. Since this document builds 276 on the OAuth 2.0 specification, we exclude a discussion of threats 277 that are described there or in related documents. 279 Token manufacture/modification: An attacker may generate a bogus 280 token or modify the token contents (such as the authentication or 281 attribute statements) of an existing token, causing the resource 282 server to grant inappropriate access to the client. For example, 283 an attacker may modify the token to extend the validity period; a 284 malicious client may modify the assertion to gain access to 285 information that they should not be able to view. 287 Token disclosure: Tokens may contain authentication and attribute 288 statements that include sensitive information. 290 Token redirect: An attacker uses the token generated for consumption 291 by resource server to obtain access to another resource server. 293 Token replay: An attacker attempts to use a token that has already 294 been used with that resource server in the past. 296 3.2. Threat Mitigation 298 A large range of threats can be mitigated by protecting the contents 299 of the token by using a digital signature or a keyed message digest. 300 Alternatively, the contents of the token could be passed by reference 301 rather than by value (requiring a separate message exchange to 302 resolve the reference to the token contents). 304 This document does not specify the encoding or the contents of the 305 token; hence detailed recommendations for token integrity protection 306 are outside the scope of this document. We assume that the token 307 integrity protection is sufficient to prevent the token from being 308 modified. 310 To deal with token redirect, it is important for the authorization 311 server to include the identity of the intended recipients, namely a 312 single resource server (or a list of resource servers). Restricting 313 the use of the token to a specific scope is also recommended. 315 To provide protection against token disclosure, confidentiality 316 protection is applied via TLS with a ciphersuite that offers 317 confidentiality protection. This requires that the communication 318 interaction between the client and the authorization server, as well 319 as the interaction between the client and the resource server, 320 utilize confidentiality protection. Since TLS is mandatory to 321 implement and to use with this specification, it is the preferred 322 approach for preventing token disclosure via the communication 323 channel. For those cases where the client is prevented from 324 observing the contents of the token, token encryption has to be 325 applied in addition to the usage of TLS protection. 327 To deal with token capture and replay, the following recommendations 328 are made: First, the lifetime of the token has to be limited by 329 putting a validity time field inside the protected part of the token. 330 Note that using short-lived (one hour or less) tokens significantly 331 reduces the impact of one of them being leaked. Second, 332 confidentiality protection of the exchanges between the client and 333 the authorization server and between the client and the resource 334 server MUST be applied. As a consequence, no eavesdropper along the 335 communication path is able to observe the token exchange. 336 Consequently, such an on-path adversary cannot replay the token. 337 Furthermore, when presenting the token to a resource server, the 338 client MUST verify the identity of that resource server. Note that 339 the client MUST validate the TLS certificate chain when making these 340 requests to protected resources. Presenting the token to an 341 unauthenticated and unauthorized resource server or failing to 342 validate the certificate chain will allow adversaries to steal the 343 token and gain unauthorized access to protected resources. 345 3.3. Summary of Recommendations 347 Safeguard bearer tokens Client implementations MUST ensure that 348 bearer tokens are not leaked to unintended parties, as they will 349 be able to use them to gain access to protected resources. This 350 is the primary security consideration when using bearer tokens 351 with OAuth and underlies all the more specific recommendations 352 that follow. 354 Validate SSL certificate chains The client must validate the TLS 355 certificate chain when making requests to protected resources. 356 Failing to do so may enable DNS hijacking attacks to steal the 357 token and gain unintended access. 359 Always use TLS (https) Clients MUST always use TLS (https) when 360 making requests with bearer tokens. Failing to do so exposes the 361 token to numerous attacks that could give attackers unintended 362 access. 364 Don't store bearer tokens in cookies As cookies are generally sent 365 in the clear, implementations MUST NOT store bearer tokens within 366 them. 368 Issue short-lived bearer tokens Using short-lived (one hour or less) 369 bearer tokens can reduce the impact of one of them being leaked. 370 The User-Agent flow should only issue short lived access tokens. 372 Don't pass bearer tokens in page URLs Browsers, web servers, and 373 other software may not adequately secure URLs in the browser 374 history, web server logs, and other data structures. If bearer 375 tokens are passed in page URLs (typically as query string 376 parameters), attackers might be able to steal them from the 377 history data, logs, or other unsecured locations. Instead, pass 378 browser tokens in message bodies for which confidentiality 379 measures are taken. 381 4. IANA Considerations 383 4.1. OAuth Access Token Type Registration 385 This specification registers the following access token type in the 386 OAuth Access Token Type Registry. 388 4.1.1. The "OAuth2" OAuth Access Token Type 390 Type name: 391 OAuth2 393 Additional Token Request Parameters: 394 oauth_token 396 HTTP Authentication Scheme(s): 397 OAuth2 399 Change controller: 400 IETF 402 Specification document(s): 403 [[ this document ]] 405 4.2. OAuth Parameters Registration 407 This specification registers the following parameters in the OAuth 408 Parameters Registry established by [OAuth2]. 410 4.2.1. The "oauth_token" OAuth Parameter 412 Parameter name: oauth_token 414 Parameter usage location: Token requests 416 Change controller: IETF 418 Specification document(s): [[ this document ]] 420 Related information: None 422 5. References 424 5.1. Normative References 426 [I-D.ietf-httpbis-p1-messaging] 427 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 428 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 429 "HTTP/1.1, part 1: URIs, Connections, and Message 430 Parsing", draft-ietf-httpbis-p1-messaging-09 (work in 431 progress), March 2010. 433 [OAuth2] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The 434 OAuth 2.0 Protocol Framework", 2011. 436 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 437 Requirement Levels", BCP 14, RFC 2119, March 1997. 439 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 440 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 441 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 443 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 444 Leach, P., Luotonen, A., and L. Stewart, "HTTP 445 Authentication: Basic and Digest Access Authentication", 446 RFC 2617, June 1999. 448 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 450 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 451 Resource Identifier (URI): Generic Syntax", STD 66, 452 RFC 3986, January 2005. 454 [W3C.REC-html401-19991224] 455 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 456 Specification", World Wide Web Consortium 457 Recommendation REC-html401-19991224, December 1999, 458 . 460 5.2. Informative References 462 [NIST800-63] 463 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 464 and E. Nabbus, "NIST Special Publication 800-63-1, 465 INFORMATION SECURITY", December 2008. 467 Appendix A. Acknowledgements 469 The following people contributed to preliminary versions of this 470 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland 471 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 472 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 473 concepts within are a product of the OAuth community, the WRAP 474 community, and the OAuth Working Group. 476 The OAuth Working Group has dozens of very active contributors who 477 proposed ideas and wording for this document, including: Michael 478 Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah Culver, Bill 479 de hOra, Brian Ellin, Igor Faynberg, George Fletcher, Tim Freeman, 480 Evan Gilbert, Justin Hart, John Kemp, Eran Hammer-Lahav, Chasen Le 481 Hara, Michael B. Jones, Torsten Lodderstedt, Eve Maler, James Manger, 482 Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin Richer, Peter 483 Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, 484 Justin Smith, Jeremy Suriel, Christian Stuebner, Paul Tarjan, and 485 Franklin Tse. 487 Appendix B. Document History 489 [[ to be removed by RFC editor before publication as an RFC ]] 491 -02 493 o Incorporated feedback received on draft 01. Most changes were to 494 the security considerations section. No normative changes were 495 made. Specific changes included: 497 o Changed terminology from "token reuse" to "token capture and 498 replay". 500 o Removed sentence "Encrypting the token contents is another 501 alternative" from the security considerations since it was 502 redundant and potentially confusing. 504 o Corrected some references to "resource server" to be 505 "authorization server" in the security considerations. 507 o Generalized security considerations language about obtaining 508 consent of the resource owner. 510 o Broadened scope of security considerations description for 511 recommendation "Don't pass bearer tokens in page URLs". 513 o Removed unused reference to OAuth 1.0. 515 o Updated reference to framework specification and updated David 516 Recordon's e-mail address. 518 o Removed security considerations text on authenticating clients. 520 o Registered the "OAuth2" OAuth access token type and "oauth_token" 521 parameter. 523 -01 525 o First public draft, which incorporates feedback received on -00 526 including enhanced Security Considerations content. This version 527 is intended to accompany OAuth 2.0 draft 11. 529 -00 531 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 533 Authors' Addresses 535 Michael B. Jones 536 Microsoft 538 Email: mbj@microsoft.com 539 URI: http://self-issued.info/ 540 Dick Hardt 541 independent 543 Email: dick.hardt@gmail.com 544 URI: http://dickhardt.org/ 546 David Recordon 547 Facebook 549 Email: dr@fb.com 550 URI: http://www.davidrecordon.com/