idnits 2.17.1 draft-ietf-oauth-v2-bearer-01.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 (December 1, 2010) is 4889 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: 'RFC5849' is defined on line 418, but no explicit reference was found in the text == 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) ** Obsolete normative reference: RFC 5849 (Obsoleted by RFC 6749) Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones, Ed. 3 Internet-Draft Microsoft 4 Intended status: Standards Track D. Hardt 5 Expires: June 4, 2011 independent 6 D. Recordon 7 Facebook 8 December 1, 2010 10 The OAuth 2.0 Protocol: Bearer Tokens 11 draft-ietf-oauth-v2-bearer-01 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 June 4, 2011. 35 Copyright Notice 37 Copyright (c) 2010 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 5. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 66 5.1. Normative References . . . . . . . . . . . . . . . . . . . 9 67 5.2. Informative References . . . . . . . . . . . . . . . . . . 10 68 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 69 Appendix B. Document History . . . . . . . . . . . . . . . . . . 11 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 72 1. Introduction 74 OAuth enables clients to access protected resources by obtaining an 75 access token, which is defined in [OAuth2] as "a string representing 76 an access authorization issued to the client", rather than using the 77 resource owner's credentials. 79 Tokens are issued to clients by an authorization server with the 80 approval of the resource owner. The client uses the access token to 81 access the protected resources hosted by the resource server. This 82 specification describes how to make protected resource requests by 83 treating an OAuth access token as a bearer token. 85 This specification defines the use of bearer tokens with OAuth over 86 HTTP [RFC2616] using TLS [RFC2818]. Other specifications may extend 87 it for use with other transport protocols. 89 1.1. Notational Conventions 91 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 92 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 93 document are to be interpreted as described in [RFC2119]. 95 This document uses the Augmented Backus-Naur Form (ABNF) notation of 96 [I-D.ietf-httpbis-p1-messaging]. Additionally, the following rules 97 are included from [RFC2617]: auth-param; and from 98 [I-D.ietf-httpbis-p1-messaging]: RWS. 100 Unless otherwise noted, all the protocol parameter names and values 101 are case sensitive. 103 1.2. Terminology 105 All terms are as defined in The OAuth 2.0 Protocol [OAuth2]. 107 1.3. Overview 109 OAuth provides a method for clients to access a protected resource on 110 behalf of a resource owner. Before a client can access a protected 111 resource, it must first obtain authorization (access grant) from the 112 resource owner, then exchange the access grant for an access token 113 (representing the grant's scope, duration, and other attributes). 114 The client accesses the protected resource by presenting the access 115 token to the resource server. 117 The access token provides an abstraction layer, replacing different 118 authorization constructs (e.g. username and password, assertion) for 119 a single token understood by the resource server. This abstraction 120 enables issuing access tokens valid for a short time period, as well 121 as removing the resource server's need to understand a wide range of 122 authentication schemes. 124 +--------+ +---------------+ 125 | |--(A)- Authorization Request ->| Resource | 126 | | | Owner | 127 | |<-(B)----- Access Grant -------| | 128 | | +---------------+ 129 | | 130 | | Access Grant & +---------------+ 131 | |--(C)--- Client Credentials -->| Authorization | 132 | Client | | Server | 133 | |<-(D)----- Access Token -------| | 134 | | +---------------+ 135 | | 136 | | +---------------+ 137 | |--(E)----- Access Token ------>| Resource | 138 | | | Server | 139 | |<-(F)--- Protected Resource ---| | 140 +--------+ +---------------+ 142 Figure 1: Abstract Protocol Flow 144 The abstract flow illustrated in Figure 1 describes the overall OAuth 145 2.0 protocol architecture. The following steps are specified within 146 this document: 148 E) The client makes a protected resource request to the resource 149 server by presenting the access token. 151 F) The resource server validates the access token, and if valid, 152 serves the request. 154 2. Authenticated Requests 156 Clients make authenticated token requests using the "Authorization" 157 request header field. Resource servers MUST accept authenticated 158 requests using the "OAuth2" HTTP authentication scheme as described 159 in Section 2.1, and MAY support additional methods. 161 Alternatively, clients MAY attempt to include the access token in the 162 HTTP body when using the "application/x-www-form-urlencoded" content 163 type as described in Section 2.2 or using the HTTP request URI in the 164 query component as described in Section 2.3. Resource servers MAY 165 support these alternative methods. 167 Clients SHOULD only use the request body or URI when the 168 "Authorization" request header field is not available, and MUST NOT 169 use more than one method to transport the token in each request. 170 Because of the Security Considerations (Section 3) associated with 171 the URI method, it SHOULD only be used if no other method is 172 feasible. 174 2.1. The Authorization Request Header Field 176 The "Authorization" request header field is used by clients to make 177 authenticated token requests. The client uses the "OAuth2" 178 authentication scheme to include the access token in the request. 180 For example: 182 GET /resource HTTP/1.1 183 Host: server.example.com 184 Authorization: OAuth2 vF9dft4qmT 186 The "Authorization" header field uses the framework defined by 187 [RFC2617] as follows: 189 credentials = "OAuth2" RWS access-token [ RWS 1#auth-param ] 190 access-token = 1*( quoted-char / <"> ) 192 quoted-char = "!" / "#" / "$" / "%" / "&" / "'" / "(" 193 / ")" / "*" / "+" / "-" / "." / "/" / DIGIT 194 / ":" / "<" / "=" / ">" / "?" / "@" / ALPHA 195 / "[" / "]" / "^" / "_" / "`" / "{" / "|" 196 / "}" / "~" / "\" / "," / ";" 198 2.2. Form-Encoded Body Parameter 200 When including the access token in the HTTP request entity-body, the 201 client adds the access token to the request body using the 202 "oauth_token" parameter. The client can use this method only if the 203 following REQUIRED conditions are met: 205 o The HTTP request entity-body is single-part. 207 o The entity-body follows the encoding requirements of the 208 "application/x-www-form-urlencoded" content-type as defined by 209 [W3C.REC-html401-19991224]. 211 o The HTTP request entity-header includes the "Content-Type" header 212 field set to "application/x-www-form-urlencoded". 214 o The HTTP request method is one for which a body is permitted to be 215 present in the request. In particular, this means that the "GET" 216 method MAY NOT be used. 218 The entity-body can include other request-specific parameters, in 219 which case, the "oauth_token" parameters SHOULD be appended following 220 the request-specific parameters, properly separated by an "&" 221 character (ASCII code 38). 223 For example, the client makes the following HTTP request using 224 transport-layer security: 226 POST /resource HTTP/1.1 227 Host: server.example.com 228 Content-Type: application/x-www-form-urlencoded 230 oauth_token=vF9dft4qmT 232 The "application/x-www-form-urlencoded" method should typically only 233 be used in application contexts where participating browsers do not 234 have access to the "Authorization" request header field. 236 2.3. URI Query Parameter 238 When including the access token in the HTTP request URI, the client 239 adds the access token to the request URI query component as defined 240 by [RFC3986] using the "oauth_token" parameter. 242 For example, the client makes the following HTTP request using 243 transport-layer security: 245 GET /resource?oauth_token=vF9dft4qmT HTTP/1.1 246 Host: server.example.com 248 The HTTP request URI query can include other request-specific 249 parameters, in which case, the "oauth_token" parameters SHOULD be 250 appended following the request-specific parameters, properly 251 separated by an "&" character (ASCII code 38). 253 For example: 255 http://example.com/resource?x=y&oauth_token=vF9dft4qmT 257 Because of the Security Considerations (Section 3) associated with 258 the URI method, it SHOULD only be used if no other method is 259 feasible. 261 3. Security Considerations 263 This section describes the relevant security threats regarding token 264 handling when using bearer tokens and describes how to mitigate these 265 threats. 267 3.1. Security Threats 269 The following list presents several common threats against protocols 270 utilizing some form of tokens. This list of threats is based on NIST 271 Special Publication 800-63 [NIST800-63]. Since this document builds 272 on the OAuth 2.0 specification, we exclude a discussion of threats 273 that are described there or in related documents. 275 Token manufacture/modification: An attacker may generate a bogus 276 token or modify the token contents (such as the authentication or 277 attribute statements) of an existing token, causing the resource 278 server to grant inappropriate access to the client. For example, 279 an attacker may modify the token to extend the validity period; a 280 malicious client may modify the assertion to gain access to 281 information that they should not be able to view. 283 Token disclosure: Tokens may contain authentication and attribute 284 statements that include sensitive information. 286 Token redirect: An attacker uses the token generated for consumption 287 by resource server to obtain access to another resource server. 289 Token reuse: An attacker attempts to use a token that has already 290 been used once with that resource server in the past. 292 3.2. Threat Mitigation 294 A large range of threats can be mitigated by protecting the contents 295 of the token by using a digital signature or a keyed message digest. 296 Alternatively, the contents of the token could be passed by reference 297 rather than by value (requiring a separate message exchange to 298 resolve the reference to the token contents). 300 This document does not specify the encoding or the contents of the 301 token; hence detailed recommendations for token integrity protection 302 are outside the scope of this document. We assume that the token 303 integrity protection is sufficient to prevent the token from being 304 modified. 306 To deal with token redirect, it is important for the authorization 307 server to include the identity of the intended recipients, namely a 308 single resource server (or a list of resource servers). Restricting 309 the use of the token to a specific scope is also recommended. 311 To provide protection against token disclosure, confidentiality 312 protection is applied via TLS with a ciphersuite that offers 313 confidentiality protection. This requires that the communication 314 interaction between the client and the authorization server, as well 315 as the interaction between the client and the resource server, 316 utilize confidentiality protection. Encrypting the token contents is 317 another alternative. Since TLS is mandatory to implement and to use 318 with this specification, it is the preferred approach for preventing 319 token disclosure via the communication channel. For those rare cases 320 where the client is prevented from observing the contents of the 321 token, token encryption has to be applied in addition to the usage of 322 TLS protection. 324 To deal with token reuse, the following recommendations are made: 325 First, the lifetime of the token has to be limited by putting a 326 validity time field inside the protected part of the token. Note 327 that using short-lived (one hour or less) tokens significantly 328 reduces the impact of one of them being leaked. Second, 329 confidentiality protection of the exchanges between the client and 330 the authorization server and between the client and the resource 331 server MUST be applied. As a consequence, no eavesdropper along the 332 communication path is able to observe the token exchange. 333 Consequently, such an on-path adversary cannot replay the token. 334 Furthermore, the resource server MUST ensure that it only hands out 335 tokens to clients it has authenticated first and authorized. For 336 this purpose, the client MUST be authenticated and authorized by the 337 resource server. The authorization server MUST also receive a 338 confirmation (the consent of the resource owner) prior to providing a 339 token to the client. Furthermore, when presenting the token to a 340 resource server, the client MUST verify the identity of that resource 341 server. Note that the client MUST validate the TLS certificate chain 342 when making these requests to protected resources. Presenting the 343 token to an unauthenticated and unauthorized resource server or 344 failing to validate the certificate chain will allow adversaries to 345 steal the token and gain unauthorized access to protected resources. 347 3.3. Summary of Recommendations 349 Safeguard bearer tokens Client implementations MUST ensure that 350 bearer tokens are not leaked to unintended parties, as they will 351 be able to use them to gain access to protected resources. This 352 is the primary security consideration when using bearer tokens 353 with OAuth and underlies all the more specific recommendations 354 that follow. 356 Validate SSL certificate chains The client must validate the TLS 357 certificate chain when making requests to protected resources. 358 Failing to do so may enable DNS hijacking attacks to steal the 359 token and gain unintended access. 361 Always use TLS (https) Clients MUST always use TLS (https) when 362 making requests with bearer tokens. Failing to do so exposes the 363 token to numerous attacks that could give attackers unintended 364 access. 366 Don't store bearer tokens in cookies As cookies are generally sent 367 in the clear, implementations MUST NOT store bearer tokens within 368 them. 370 Issue short-lived bearer tokens Using short-lived (one hour or less) 371 bearer tokens can reduce the impact of one of them being leaked. 372 The User-Agent flow should only issue short lived access tokens. 374 Don't pass bearer tokens in page URLs Browsers may not adequately 375 secure URLs in the browser history. If bearer tokens are passed 376 in page URLs (typically as query string parameters), attackers 377 might be able to steal them from the history data. Instead, pass 378 browser tokens in message bodies for which confidentiality 379 measures are taken. 381 4. IANA Considerations 383 This document neither establishes new IANA registries nor adds new 384 values to existing registries. 386 5. References 388 5.1. Normative References 390 [I-D.ietf-httpbis-p1-messaging] 391 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 392 Masinter, L., Leach, P., Berners-Lee, T., and J. Reschke, 393 "HTTP/1.1, part 1: URIs, Connections, and Message 394 Parsing", draft-ietf-httpbis-p1-messaging-09 (work in 395 progress), March 2010. 397 [OAuth2] Hammer-Lahav, E., Ed., Recordon, D., and D. Hardt, "The 398 OAuth 2.0 Protocol", 2010. 400 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 401 Requirement Levels", BCP 14, RFC 2119, March 1997. 403 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 404 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 405 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 407 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 408 Leach, P., Luotonen, A., and L. Stewart, "HTTP 409 Authentication: Basic and Digest Access Authentication", 410 RFC 2617, June 1999. 412 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 414 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 415 Resource Identifier (URI): Generic Syntax", STD 66, 416 RFC 3986, January 2005. 418 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 419 April 2010. 421 [W3C.REC-html401-19991224] 422 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 423 Specification", World Wide Web Consortium 424 Recommendation REC-html401-19991224, December 1999, 425 . 427 5.2. Informative References 429 [NIST800-63] 430 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 431 and E. Nabbus, "NIST Special Publication 800-63-1, 432 INFORMATION SECURITY", December 2008. 434 Appendix A. Acknowledgements 436 The following people contributed to preliminary versions of this 437 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland 438 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 439 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 440 concepts within are a product of the OAuth community, WRAP community, 441 and the OAuth Working Group. 443 The OAuth Working Group has dozens of very active contributors who 444 proposed ideas and wording for this document, including: [[ If your 445 name is missing or you think someone should be added here, please 446 send Mike Jones a note - don't be shy! ]] 448 Michael Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah 449 Culver, Bill de hOra, Brian Ellin, Igor Faynberg, George Fletcher, 450 Tim Freeman, Evan Gilbert, Justin Hart, John Kemp, Eran Hammer-Lahav, 451 Chasen Le Hara, Michael B. Jones, Torsten Lodderstedt, Eve Maler, 452 James Manger, Laurence Miao, Chuck Mortimore, Justin Richer, Peter 453 Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, 454 Justin Smith, Jeremy Suriel, Christian Stuebner, Paul Tarjan, and 455 Franklin Tse. 457 Appendix B. Document History 459 [[ to be removed by RFC editor before publication as an RFC ]] 461 -01 463 o First public draft, which incorporates feedback received on -00 464 including enhanced Security Considerations content. This version 465 is intended to accompany OAuth 2.0 draft 11. 467 -00 469 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 471 Authors' Addresses 473 Michael B. Jones (editor) 474 Microsoft 476 Email: mbj@microsoft.com 477 URI: http://self-issued.info/ 479 Dick Hardt 480 independent 482 Email: dick.hardt@gmail.com 483 URI: http://dickhardt.org/ 485 David Recordon 486 Facebook 488 Email: davidrecordon@facebook.com 489 URI: http://www.davidrecordon.com/