idnits 2.17.1 draft-ietf-oauth-v2-bearer-13.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 document date (October 30, 2011) is 4567 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-16 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-16 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-22 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 2 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: May 2, 2012 independent 6 D. Recordon 7 Facebook 8 October 30, 2011 10 The OAuth 2.0 Authorization Protocol: Bearer Tokens 11 draft-ietf-oauth-v2-bearer-13 13 Abstract 15 This specification describes how to use bearer tokens in HTTP 16 requests to access OAuth 2.0 protected resources. Any party in 17 possession of a bearer token (a "bearer") can use it to get access to 18 granted resources (without demonstrating possession of a 19 cryptographic key). To prevent misuse, the bearer token needs to be 20 protected from disclosure in storage and in transport. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on May 2, 2012. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 5 61 2.1. Authorization Request Header Field . . . . . . . . . . . . 5 62 2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 5 63 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 6 64 3. The WWW-Authenticate Response Header Field . . . . . . . . . . 7 65 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 8 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 4.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 9 68 4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 10 69 4.3. Summary of Recommendations . . . . . . . . . . . . . . . . 11 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 71 5.1. OAuth Access Token Type Registration . . . . . . . . . . . 12 72 5.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 12 73 5.2. Authentication Scheme Registration . . . . . . . . . . . . 12 74 5.2.1. The "Bearer" Authentication Scheme . . . . . . . . . . 12 75 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 76 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 77 6.2. Informative References . . . . . . . . . . . . . . . . . . 14 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 14 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 82 1. Introduction 84 OAuth enables clients to access protected resources by obtaining an 85 access token, which is defined in [I-D.ietf-oauth-v2] as "a string 86 representing an access authorization issued to the client", rather 87 than using the resource owner's credentials directly. 89 Tokens are issued to clients by an authorization server with the 90 approval of the resource owner. The client uses the access token to 91 access the protected resources hosted by the resource server. This 92 specification describes how to make protected resource requests when 93 the OAuth access token is a bearer token. 95 This specification defines the use of bearer tokens with OAuth over 96 HTTP [RFC2616] using TLS [RFC5246]. Other specifications may extend 97 it for use with other transport protocols. 99 1.1. Notational Conventions 101 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 102 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 103 document are to be interpreted as described in [RFC2119]. 105 This document uses the Augmented Backus-Naur Form (ABNF) notation of 106 [I-D.ietf-httpbis-p1-messaging], which is based upon the Augmented 107 Backus-Naur Form (ABNF) notation of [RFC5234]. Additionally, the 108 following rules are included from [I-D.ietf-httpbis-p7-auth]: 109 b64token, auth-param, and realm; from 110 [I-D.ietf-httpbis-p1-messaging]: quoted-string; and from [RFC3986]: 111 URI-Reference. 113 Unless otherwise noted, all the protocol parameter names and values 114 are case sensitive. 116 1.2. Terminology 118 Bearer Token 119 A security token with the property that any party in possession of 120 the token (a "bearer") can use the token in any way that any other 121 party in possession of it can. Using a bearer token does not 122 require a bearer to prove possession of cryptographic key material 123 (proof-of-possession). 125 All other terms are as defined in [I-D.ietf-oauth-v2]. 127 1.3. Overview 129 OAuth provides a method for clients to access a protected resource on 130 behalf of a resource owner. In the general case, before a client can 131 access a protected resource, it must first obtain an authorization 132 grant from the resource owner and then exchange the authorization 133 grant for an access token. The access token represents the grant's 134 scope, duration, and other attributes granted by the authorization 135 grant. The client accesses the protected resource by presenting the 136 access token to the resource server. In some cases, a client can 137 directly present its own credentials to an authorization server to 138 obtain an access token without having to first obtain an 139 authorization grant from a resource owner. 141 The access token provides an abstraction layer, replacing different 142 authorization constructs (e.g. username and password, assertion) for 143 a single token understood by the resource server. This abstraction 144 enables issuing access tokens valid for a short time period, as well 145 as removing the resource server's need to understand a wide range of 146 authentication schemes. 148 +--------+ +---------------+ 149 | |--(A)- Authorization Request ->| Resource | 150 | | | Owner | 151 | |<-(B)-- Authorization Grant ---| | 152 | | +---------------+ 153 | | 154 | | Authorization Grant & +---------------+ 155 | |--(C)--- Client Credentials -->| Authorization | 156 | Client | | Server | 157 | |<-(D)----- Access Token -------| | 158 | | +---------------+ 159 | | 160 | | +---------------+ 161 | |--(E)----- Access Token ------>| Resource | 162 | | | Server | 163 | |<-(F)--- Protected Resource ---| | 164 +--------+ +---------------+ 166 Figure 1: Abstract Protocol Flow 168 The abstract flow illustrated in Figure 1 describes the overall OAuth 169 2.0 protocol architecture. The following steps are specified within 170 this document: 172 E) The client makes a protected resource request to the resource 173 server by presenting the access token. 175 F) The resource server validates the access token, and if valid, 176 serves the request. 178 2. Authenticated Requests 180 Clients MAY use bearer tokens to make authenticated requests to 181 access protected resources. This section defines three methods of 182 sending bearer access tokens in resource requests to resource 183 servers. Clients MUST NOT use more than one method to transmit the 184 token in each request. 186 2.1. Authorization Request Header Field 188 When sending the access token in the "Authorization" request header 189 field defined by [I-D.ietf-httpbis-p7-auth], the client uses the 190 "Bearer" authentication scheme to transmit the access token. 192 For example: 194 GET /resource HTTP/1.1 195 Host: server.example.com 196 Authorization: Bearer vF9dft4qmT 198 The "Authorization" header field uses the framework defined by 199 [I-D.ietf-httpbis-p7-auth] follows: 201 credentials = "Bearer" 1*SP b64token 203 The b64token syntax was chosen over the alternative #auth-param 204 syntax also defined by [I-D.ietf-httpbis-p7-auth] both for simplicity 205 reasons and for compatibility with existing implementations. If 206 additional parameters are desired in the future, a different scheme 207 could be defined. 209 Clients SHOULD make authenticated requests with a bearer token using 210 the "Authorization" request header field with the "Bearer" HTTP 211 authorization scheme. Resource servers MUST support this method. 213 2.2. Form-Encoded Body Parameter 215 When sending the access token in the HTTP request entity-body, the 216 client adds the access token to the request body using the 217 "access_token" parameter. The client MUST NOT use this method unless 218 all of the following conditions are met: 220 o The HTTP request entity-body is single-part. 222 o The entity-body follows the encoding requirements of the 223 "application/x-www-form-urlencoded" content-type as defined by 224 [W3C.REC-html401-19991224]. 226 o The HTTP request entity-header includes the "Content-Type" header 227 field set to "application/x-www-form-urlencoded". 229 o The HTTP request method is one for which the request body has 230 defined semantics. In particular, this means that the "GET" 231 method MUST NOT be used. 233 The entity-body MAY include other request-specific parameters, in 234 which case, the "access_token" parameter MUST be properly separated 235 from the request-specific parameters using "&" character(s) (ASCII 236 code 38). 238 For example, the client makes the following HTTP request using 239 transport-layer security: 241 POST /resource HTTP/1.1 242 Host: server.example.com 243 Content-Type: application/x-www-form-urlencoded 245 access_token=vF9dft4qmT 247 The "application/x-www-form-urlencoded" method SHOULD NOT be used 248 except in application contexts where participating browsers do not 249 have access to the "Authorization" request header field. Resource 250 servers MAY support this method. 252 2.3. URI Query Parameter 254 When sending the access token in the HTTP request URI, the client 255 adds the access token to the request URI query component as defined 256 by [RFC3986] using the "access_token" parameter. 258 For example, the client makes the following HTTP request using 259 transport-layer security: 261 GET /resource?access_token=vF9dft4qmT HTTP/1.1 262 Host: server.example.com 264 The HTTP request URI query can include other request-specific 265 parameters, in which case, the "access_token" parameter MUST be 266 properly separated from the request-specific parameters using "&" 267 character(s) (ASCII code 38). 269 For example: 271 https://server.example.com/resource?x=y&access_token=vF9dft4qmT&p=q 273 Because of the security weaknesses associated with the URI method 274 (see Section 4), it SHOULD NOT be used unless it is the only feasible 275 method. Resource servers MAY support this method. 277 3. The WWW-Authenticate Response Header Field 279 If the protected resource request does not include authentication 280 credentials or does not contain an access token that enables access 281 to the protected resource, the resource server MUST include the HTTP 282 "WWW-Authenticate" response header field; it MAY include it in 283 response to other conditions as well. The "WWW-Authenticate" header 284 field uses the framework defined by [I-D.ietf-httpbis-p7-auth] as 285 follows: 287 challenge = "Bearer" [ 1*SP 1#param ] 289 param = realm / scope / 290 error / error-desc / error-uri / 291 auth-param 293 scope = "scope" "=" quoted-string 294 error = "error" "=" quoted-string 295 error-desc = "error_description" "=" quoted-string 296 error-uri = "error_uri" "=" quoted-string 298 The "scope" attribute is a space-delimited list of scope values 299 indicating the required scope of the access token for accessing the 300 requested resource. The "scope" attribute MUST NOT appear more than 301 once. The "scope" value is intended for programmatic use and is not 302 meant to be displayed to end users. 304 If the protected resource request included an access token and failed 305 authentication, the resource server SHOULD include the "error" 306 attribute to provide the client with the reason why the access 307 request was declined. The parameter value is described in 308 Section 3.1. In addition, the resource server MAY include the 309 "error_description" attribute to provide developers a human-readable 310 explanation that is not meant to be displayed to end users. It also 311 MAY include the "error_uri" attribute with an absolute URI 312 identifying a human-readable web page explaining the error. The 313 "error", "error_description", and "error_uri" attribute MUST NOT 314 appear more than once. 316 Producers of "scope" strings MUST NOT use characters outside the set 317 %x21 / %x23-5B / %x5D-7E for representing the scope values and %x20 318 for the delimiter. Producers of "error" and "error_description" 319 strings MUST NOT use characters outside the set %x20-21 / %x23-5B / 320 %x5D-7E for representing these values. Producers of "error-uri" 321 strings MUST NOT use characters outside the set %x21 / %x23-5B / 322 %x5D-7E for representing these values. Furthermore, "error-uri" 323 strings MUST conform to the URI-reference syntax. In all these 324 cases, no character quoting will occur, as senders are prohibited 325 from using the %5C ('\') character. 327 For example, in response to a protected resource request without 328 authentication: 330 HTTP/1.1 401 Unauthorized 331 WWW-Authenticate: Bearer realm="example" 333 And in response to a protected resource request with an 334 authentication attempt using an expired access token: 336 HTTP/1.1 401 Unauthorized 337 WWW-Authenticate: Bearer realm="example", 338 error="invalid_token", 339 error_description="The access token expired" 341 3.1. Error Codes 343 When a request fails, the resource server responds using the 344 appropriate HTTP status code (typically, 400, 401, or 403), and 345 includes one of the following error codes in the response: 347 invalid_request 348 The request is missing a required parameter, includes an 349 unsupported parameter or parameter value, repeats the same 350 parameter, uses more than one method for including an access 351 token, or is otherwise malformed. The resource server SHOULD 352 respond with the HTTP 400 (Bad Request) status code. 354 invalid_token 355 The access token provided is expired, revoked, malformed, or 356 invalid for other reasons. The resource SHOULD respond with 357 the HTTP 401 (Unauthorized) status code. The client MAY 358 request a new access token and retry the protected resource 359 request. 361 insufficient_scope 362 The request requires higher privileges than provided by the 363 access token. The resource server SHOULD respond with the HTTP 364 403 (Forbidden) status code and MAY include the "scope" 365 attribute with the scope necessary to access the protected 366 resource. 368 If the request lacks any authentication information (i.e. the client 369 was unaware authentication is necessary or attempted using an 370 unsupported authentication method), the resource server SHOULD NOT 371 include an error code or other error information. 373 For example: 375 HTTP/1.1 401 Unauthorized 376 WWW-Authenticate: Bearer realm="example" 378 4. Security Considerations 380 This section describes the relevant security threats regarding token 381 handling when using bearer tokens and describes how to mitigate these 382 threats. 384 4.1. Security Threats 386 The following list presents several common threats against protocols 387 utilizing some form of tokens. This list of threats is based on NIST 388 Special Publication 800-63 [NIST800-63]. Since this document builds 389 on the OAuth 2.0 specification, we exclude a discussion of threats 390 that are described there or in related documents. 392 Token manufacture/modification: An attacker may generate a bogus 393 token or modify the token contents (such as the authentication or 394 attribute statements) of an existing token, causing the resource 395 server to grant inappropriate access to the client. For example, 396 an attacker may modify the token to extend the validity period; a 397 malicious client may modify the assertion to gain access to 398 information that they should not be able to view. 400 Token disclosure: Tokens may contain authentication and attribute 401 statements that include sensitive information. 403 Token redirect: An attacker uses a token generated for consumption 404 by one resource server to gain access to a different resource 405 server that mistakenly believes the token to be for it. 407 Token replay: An attacker attempts to use a token that has already 408 been used with that resource server in the past. 410 4.2. Threat Mitigation 412 A large range of threats can be mitigated by protecting the contents 413 of the token by using a digital signature or a Message Authentication 414 Code (MAC). Alternatively, a bearer token can contain a reference to 415 authorization information, rather than encoding the information 416 directly. Such references MUST be infeasible for an attacker to 417 guess; using a reference may require an extra interaction between a 418 server and the token issuer to resolve the reference to the 419 authorization information. The mechanics of such an interaction are 420 not defined by this specification. 422 This document does not specify the encoding or the contents of the 423 token; hence detailed recommendations for token integrity protection 424 are outside the scope of this document. We assume that the token 425 integrity protection is sufficient to prevent the token from being 426 modified. 428 To deal with token redirect, it is important for the authorization 429 server to include the identity of the intended recipients (the 430 audience), typically a single resource server (or a list of resource 431 servers), in the token. Restricting the use of the token to a 432 specific scope is also recommended. 434 To provide protection against token disclosure, confidentiality 435 protection is applied via TLS [RFC5246] with a ciphersuite that 436 offers confidentiality protection. This requires that the 437 communication interaction between the client and the authorization 438 server, as well as the interaction between the client and the 439 resource server, utilize confidentiality protection. Since TLS is 440 mandatory to implement and to use with this specification, it is the 441 preferred approach for preventing token disclosure via the 442 communication channel. For those cases where the client is prevented 443 from observing the contents of the token, token encryption MUST be 444 applied in addition to the usage of TLS protection. 446 To deal with token capture and replay, the following recommendations 447 are made: First, the lifetime of the token MUST be limited by putting 448 a validity time field inside the protected part of the token. Note 449 that using short-lived (one hour or less) tokens reduces the impact 450 of them being leaked. Second, confidentiality protection of the 451 exchanges between the client and the authorization server and between 452 the client and the resource server MUST be applied, for instance, 453 through the use of TLS [RFC5246]. As a consequence, no eavesdropper 454 along the communication path is able to observe the token exchange. 456 Consequently, such an on-path adversary cannot replay the token. 457 Furthermore, when presenting the token to a resource server, the 458 client MUST verify the identity of that resource server, as per 459 [RFC2818]. Note that the client MUST validate the TLS certificate 460 chain when making these requests to protected resources. Presenting 461 the token to an unauthenticated and unauthorized resource server or 462 failing to validate the certificate chain will allow adversaries to 463 steal the token and gain unauthorized access to protected resources. 465 4.3. Summary of Recommendations 467 Safeguard bearer tokens: Client implementations MUST ensure that 468 bearer tokens are not leaked to unintended parties, as they will 469 be able to use them to gain access to protected resources. This 470 is the primary security consideration when using bearer tokens and 471 underlies all the more specific recommendations that follow. 473 Validate SSL certificate chains: The client MUST validate the TLS 474 certificate chain when making requests to protected resources. 475 Failing to do so may enable DNS hijacking attacks to steal the 476 token and gain unintended access. 478 Always use TLS (https): Clients MUST always use TLS [RFC5246] 479 (https) or equivalent transport security when making requests with 480 bearer tokens. Failing to do so exposes the token to numerous 481 attacks that could give attackers unintended access. 483 Don't store bearer tokens in cookies: Implementations MUST NOT store 484 bearer tokens within cookies that can be sent in the clear (which 485 is the default transmission mode for cookies). Implementations 486 that do store bearer tokens in cookies MUST take precautions 487 against cross site request forgery. 489 Issue short-lived bearer tokens: Token servers SHOULD issue short- 490 lived (one hour or less) bearer tokens, particularly when issuing 491 tokens to clients that run within a web browser or other 492 environments where information leakage may occur. Using short- 493 lived bearer tokens can reduce the impact of them being leaked. 495 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 496 that contain an audience restriction, scoping their use to the 497 intended relying party or set of relying parties. 499 Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be 500 passed in page URLs (for example as query string parameters). 501 Instead, bearer tokens SHOULD be passed in HTTP message headers or 502 message bodies for which confidentiality measures are taken. 503 Browsers, web servers, and other software may not adequately 504 secure URLs in the browser history, web server logs, and other 505 data structures. If bearer tokens are passed in page URLs, 506 attackers might be able to steal them from the history data, logs, 507 or other unsecured locations. 509 5. IANA Considerations 511 5.1. OAuth Access Token Type Registration 513 This specification registers the following access token type in the 514 OAuth Access Token Type Registry. 516 5.1.1. The "Bearer" OAuth Access Token Type 518 Type name: 519 Bearer 521 Additional Token Endpoint Response Parameters: 522 (none) 524 HTTP Authentication Scheme(s): 525 Bearer 527 Change controller: 528 IETF 530 Specification document(s): 531 [[ this document ]] 533 5.2. Authentication Scheme Registration 535 This specification registers the following authentication scheme in 536 the Authentication Scheme Registry defined in 537 [I-D.ietf-httpbis-p7-auth]. 539 5.2.1. The "Bearer" Authentication Scheme 541 Authentication Scheme Name: 542 Bearer 544 Pointer to specification text: 545 [[ this document ]] 547 Notes (optional): 548 (none) 550 6. References 552 6.1. Normative References 554 [I-D.ietf-httpbis-p1-messaging] 555 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 556 Masinter, L., Leach, P., Berners-Lee, T., Reschke, J., and 557 Y. Lafon, "HTTP/1.1, part 1: URIs, Connections, and 558 Message Parsing", draft-ietf-httpbis-p1-messaging-16 (work 559 in progress), August 2011. 561 [I-D.ietf-httpbis-p7-auth] 562 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 563 Masinter, L., Leach, P., Berners-Lee, T., Reschke, J., and 564 Y. Lafon, "HTTP/1.1, part 7: Authentication", 565 draft-ietf-httpbis-p7-auth-16 (work in progress), 566 August 2011. 568 [I-D.ietf-oauth-v2] 569 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 570 2.0 Authorization Protocol", draft-ietf-oauth-v2-22 (work 571 in progress), September 2011. 573 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 574 Requirement Levels", BCP 14, RFC 2119, March 1997. 576 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 577 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 578 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 580 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 582 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 583 Resource Identifier (URI): Generic Syntax", STD 66, 584 RFC 3986, January 2005. 586 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 587 Specifications: ABNF", STD 68, RFC 5234, January 2008. 589 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 590 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 592 [W3C.REC-html401-19991224] 593 Raggett, D., Jacobs, I., and A. Hors, "HTML 4.01 594 Specification", World Wide Web Consortium 595 Recommendation REC-html401-19991224, December 1999, 596 . 598 6.2. Informative References 600 [NIST800-63] 601 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 602 and E. Nabbus, "NIST Special Publication 800-63-1, 603 INFORMATION SECURITY", December 2008. 605 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 606 Leach, P., Luotonen, A., and L. Stewart, "HTTP 607 Authentication: Basic and Digest Access Authentication", 608 RFC 2617, June 1999. 610 Appendix A. Acknowledgements 612 The following people contributed to preliminary versions of this 613 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland 614 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 615 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 616 concepts within are a product of the OAuth community, the WRAP 617 community, and the OAuth Working Group. 619 The OAuth Working Group has dozens of very active contributors who 620 proposed ideas and wording for this document, including: Michael 621 Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, John Bradley, 622 Brian Campbell, Leah Culver, Bill de hOra, Brian Ellin, Igor 623 Faynberg, Stephen Farrell, George Fletcher, Tim Freeman, Evan 624 Gilbert, Yaron Y. Goland, Thomas Hardjono, Justin Hart, Phil Hunt, 625 John Kemp, Eran Hammer-Lahav, Chasen Le Hara, Barry Leiba, Michael B. 626 Jones, Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, 627 William J. Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, 628 Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius 629 Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian 630 Stuebner, Paul Tarjan, Hannes Tschofenig, Franklin Tse, and Shane 631 Weeden. 633 Appendix B. Document History 635 [[ to be removed by the RFC editor before publication as an RFC ]] 637 -13 639 o At the request of Hannes Tschofenig, made ABNF changes to make it 640 clear that no special WWW-Authenticate response header field 641 parsers are needed. The "scope", "error-description", and 642 "error-uri" parameters are all now defined as quoted-string in the 643 ABNF (as "error" already was). Restrictions on these values that 644 were formerly described in the ABNFs are now described in 645 normative text instead. 647 -12 649 o Made non-normative editorial changes that Hannes Tschofenig 650 requested be applied prior to forwarding the specification to the 651 IESG. 653 o Added rationale for the choice of the b64token syntax. 655 o Added rationale stating that receivers are free to parse the 656 "scope" attribute using a standard quoted-string parser, since it 657 will correctly process all legal "scope" values. 659 o Added additional active working group contributors to the 660 Acknowledgements section. 662 -11 664 o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. 666 -10 668 o Removed the #auth-param option from Authorization header syntax 669 (leaving only the b64token syntax). 671 o Restricted the "scope" value character set to %x21 / %x23-5B / 672 %x5D-7E (printable ASCII characters excluding double-quote and 673 backslash). Indicated that scope is intended for programmatic use 674 and is not meant to be displayed to end users. 676 o Restricted the character set for "error_description" strings to SP 677 / VCHAR and indicated that they are not meant to be displayed to 678 end users. 680 o Included more description in the Abstract, since Hannes Tschofenig 681 indicated that the RFC editor would require this. 683 o Changed "Access Grant" to "Authorization Grant", as was done in 684 the core spec. 686 o Simplified the introduction to the Authenticated Requests section. 688 -09 690 o Incorporated working group last call comments. Specific changes 691 were: 693 o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than 694 [RFC2617]. 696 o Update credentials definition to conform to 697 [I-D.ietf-httpbis-p7-auth]. 699 o Further clarified that query parameters may occur in any order. 701 o Specify that error_description is UTF-8 encoded (matching the core 702 specification). 704 o Registered "Bearer" Authentication Scheme in Authentication Scheme 705 Registry defined by [I-D.ietf-httpbis-p7-auth]. 707 o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- 708 p7-auth drafts. 710 o Other wording improvements not introducing normative changes. 712 -08 714 o Updated references to oauth-v2 and HTTPbis drafts. 716 -07 718 o Added missing comma in error response example. 720 -06 722 o Changed parameter name "bearer_token" to "access_token", per 723 working group consensus. 725 o Changed HTTP status code for "invalid_request" error code from 726 HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input 727 from HTTP working group experts. 729 -05 731 o Removed OAuth Errors Registry, per design team input. 733 o Changed HTTP status code for "invalid_request" error code from 734 HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP 735 usage [[ change pending working group consensus ]]. 737 o Added missing quotation marks in error-uri definition. 739 o Added note to add language and encoding information to 740 error_description if the core specification does. 742 o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined 743 in [RFC5234]. 745 o Use auth-param instead of repeating its definition, which is ( 746 token "=" ( token / quoted-string ) ). 748 o Clarify security considerations about including an audience 749 restriction in the token and include a recommendation to issue 750 scoped bearer tokens in the summary of recommendations. 752 -04 754 o Edits responding to working group last call feedback on -03. 755 Specific edits enumerated below. 757 o Added Bearer Token definition in Terminology section. 759 o Changed parameter name "oauth_token" to "bearer_token". 761 o Added realm parameter to "WWW-Authenticate" response to comply 762 with [RFC2617]. 764 o Removed "[ RWS 1#auth-param ]" from "credentials" definition since 765 it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. 767 o Removed restriction that the "bearer_token" (formerly 768 "oauth_token") parameter be the last parameter in the entity-body 769 and the HTTP request URI query. 771 o Do not require WWW-Authenticate Response in a reply to a malformed 772 request, as an HTTP 400 Bad Request response without a WWW- 773 Authenticate header is likely the right response in some cases of 774 malformed requests. 776 o Removed OAuth Parameters registry extension. 778 o Numerous editorial improvements suggested by working group 779 members. 781 -03 783 o Restored the WWW-Authenticate response header functionality 784 deleted from the framework specification in draft 12 based upon 785 the specification text from draft 11. 787 o Augmented the OAuth Parameters registry by adding two additional 788 parameter usage locations: "resource request" and "resource 789 response". 791 o Registered the "oauth_token" OAuth parameter with usage location 792 "resource request". 794 o Registered the "error" OAuth parameter. 796 o Created the OAuth Error registry and registered errors. 798 o Changed the "OAuth2" OAuth access token type name to "Bearer". 800 -02 802 o Incorporated feedback received on draft 01. Most changes were to 803 the security considerations section. No normative changes were 804 made. Specific changes included: 806 o Changed terminology from "token reuse" to "token capture and 807 replay". 809 o Removed sentence "Encrypting the token contents is another 810 alternative" from the security considerations since it was 811 redundant and potentially confusing. 813 o Corrected some references to "resource server" to be 814 "authorization server" in the security considerations. 816 o Generalized security considerations language about obtaining 817 consent of the resource owner. 819 o Broadened scope of security considerations description for 820 recommendation "Don't pass bearer tokens in page URLs". 822 o Removed unused reference to OAuth 1.0. 824 o Updated reference to framework specification and updated David 825 Recordon's e-mail address. 827 o Removed security considerations text on authenticating clients. 829 o Registered the "OAuth2" OAuth access token type and "oauth_token" 830 parameter. 832 -01 834 o First public draft, which incorporates feedback received on -00 835 including enhanced Security Considerations content. This version 836 is intended to accompany OAuth 2.0 draft 11. 838 -00 839 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 841 Authors' Addresses 843 Michael B. Jones 844 Microsoft 846 Email: mbj@microsoft.com 847 URI: http://self-issued.info/ 849 Dick Hardt 850 independent 852 Email: dick.hardt@gmail.com 853 URI: http://dickhardt.org/ 855 David Recordon 856 Facebook 858 Email: dr@fb.com 859 URI: http://www.davidrecordon.com/