idnits 2.17.1 draft-ietf-oauth-v2-bearer-17.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 (February 16, 2012) is 4443 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-18 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-18 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-23 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- 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 (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track D. Hardt 5 Expires: August 19, 2012 independent 6 D. Recordon 7 Facebook 8 February 16, 2012 10 The OAuth 2.0 Authorization Protocol: Bearer Tokens 11 draft-ietf-oauth-v2-bearer-17 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 the associated resources (without demonstrating possession of a 19 cryptographic key). To prevent misuse, bearer tokens need 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 August 19, 2012. 39 Copyright Notice 41 Copyright (c) 2012 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 . . . . . . . . . . . . . . . 6 63 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 7 64 3. The WWW-Authenticate Response Header Field . . . . . . . . . . 7 65 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 9 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 10 67 4.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 10 68 4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 10 69 4.3. Summary of Recommendations . . . . . . . . . . . . . . . . 12 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 71 5.1. OAuth Access Token Type Registration . . . . . . . . . . . 13 72 5.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 13 73 5.2. Authentication Scheme Registration . . . . . . . . . . . . 14 74 5.2.1. The "Bearer" Authentication Scheme . . . . . . . . . . 14 75 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 76 6.1. Normative References . . . . . . . . . . . . . . . . . . . 14 77 6.2. Informative References . . . . . . . . . . . . . . . . . . 15 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 82 1. Introduction 84 OAuth enables clients to access protected resources by obtaining an 85 access token, which is defined in OAuth 2.0 Authorization 86 [I-D.ietf-oauth-v2] as "a string representing an access authorization 87 issued to the client", rather than using the resource owner's 88 credentials directly. 90 Tokens are issued to clients by an authorization server with the 91 approval of the resource owner. The client uses the access token to 92 access the protected resources hosted by the resource server. This 93 specification describes how to make protected resource requests when 94 the OAuth access token is a bearer token. 96 This specification defines the use of bearer tokens over HTTP/1.1 97 [I-D.ietf-httpbis-p1-messaging] using TLS [RFC5246] to access 98 protected resources. TLS is mandatory to implement and use with this 99 specification; other specifications may extend this specification for 100 use with other transport protocols. While designed for use with 101 access tokens resulting from OAuth 2.0 Authorization 102 [I-D.ietf-oauth-v2] flows to access OAuth protected resources, this 103 specification actually defines a general HTTP authorization method 104 that can be used with bearer tokens from any source to access any 105 resources protected by those bearer tokens. 107 1.1. Notational Conventions 109 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 110 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 111 document are to be interpreted as described in Key words for use in 112 RFCs to Indicate Requirement Levels [RFC2119]. 114 This document uses the Augmented Backus-Naur Form (ABNF) notation of 115 HTTP/1.1, Part 1 [I-D.ietf-httpbis-p1-messaging], which is based upon 116 the Augmented Backus-Naur Form (ABNF) [RFC5234] notation. 117 Additionally, the following rules are included from HTTP/1.1, Part 7 118 [I-D.ietf-httpbis-p7-auth]: auth-param, auth-scheme, and b64token; 119 and from Uniform Resource Identifier (URI) [RFC3986]: URI-Reference. 121 Unless otherwise noted, all the protocol parameter names and values 122 are case sensitive. 124 1.2. Terminology 125 Bearer Token 126 A security token with the property that any party in possession of 127 the token (a "bearer") can use the token in any way that any other 128 party in possession of it can. Using a bearer token does not 129 require a bearer to prove possession of cryptographic key material 130 (proof-of-possession). 132 All other terms are as defined in OAuth 2.0 Authorization 133 [I-D.ietf-oauth-v2]. 135 1.3. Overview 137 OAuth provides a method for clients to access a protected resource on 138 behalf of a resource owner. In the general case, before a client can 139 access a protected resource, it must first obtain an authorization 140 grant from the resource owner and then exchange the authorization 141 grant for an access token. The access token represents the grant's 142 scope, duration, and other attributes granted by the authorization 143 grant. The client accesses the protected resource by presenting the 144 access token to the resource server. In some cases, a client can 145 directly present its own credentials to an authorization server to 146 obtain an access token without having to first obtain an 147 authorization grant from a resource owner. 149 The access token provides an abstraction, replacing different 150 authorization constructs (e.g. username and password, assertion) for 151 a single token understood by the resource server. This abstraction 152 enables issuing access tokens valid for a short time period, as well 153 as removing the resource server's need to understand a wide range of 154 authentication schemes. 156 +--------+ +---------------+ 157 | |--(A)- Authorization Request ->| Resource | 158 | | | Owner | 159 | |<-(B)-- Authorization Grant ---| | 160 | | +---------------+ 161 | | 162 | | Authorization Grant & +---------------+ 163 | |--(C)--- Client Credentials -->| Authorization | 164 | Client | | Server | 165 | |<-(D)----- Access Token -------| | 166 | | +---------------+ 167 | | 168 | | +---------------+ 169 | |--(E)----- Access Token ------>| Resource | 170 | | | Server | 171 | |<-(F)--- Protected Resource ---| | 172 +--------+ +---------------+ 174 Figure 1: Abstract Protocol Flow 176 The abstract flow illustrated in Figure 1 describes the overall OAuth 177 2.0 protocol architecture. The following steps are specified within 178 this document: 180 E) The client makes a protected resource request to the resource 181 server by presenting the access token. 183 F) The resource server validates the access token, and if valid, 184 serves the request. 186 2. Authenticated Requests 188 This section defines three methods of sending bearer access tokens in 189 resource requests to resource servers. Clients MUST NOT use more 190 than one method to transmit the token in each request. 192 2.1. Authorization Request Header Field 194 When sending the access token in the "Authorization" request header 195 field defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth], the 196 client uses the "Bearer" authentication scheme to transmit the access 197 token. 199 For example: 201 GET /resource HTTP/1.1 202 Host: server.example.com 203 Authorization: Bearer vF9dft4qmT 205 The "Authorization" header field uses the framework defined by 206 HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] as follows: 208 credentials = "Bearer" 1*SP b64token 210 The b64token syntax was chosen over the alternative #auth-param 211 syntax also defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] 212 both for simplicity and for compatibility with existing 213 implementations. If additional parameters are needed in the future, 214 a different scheme would need to be defined. 216 Clients SHOULD make authenticated requests with a bearer token using 217 the "Authorization" request header field with the "Bearer" HTTP 218 authorization scheme. Resource servers MUST support this method. 220 2.2. Form-Encoded Body Parameter 222 When sending the access token in the HTTP request entity-body, the 223 client adds the access token to the request body using the 224 "access_token" parameter. The client MUST NOT use this method unless 225 all of the following conditions are met: 227 o The HTTP request entity-header includes the "Content-Type" header 228 field set to "application/x-www-form-urlencoded". 230 o The entity-body follows the encoding requirements of the 231 "application/x-www-form-urlencoded" content-type as defined by 232 HTML 4.01 [W3C.REC-html401-19991224]. 234 o The HTTP request entity-body is single-part. 236 o The content to be encoded in the entity-body MUST consist entirely 237 of ASCII [USASCII] characters. 239 o The HTTP request method is one for which the request body has 240 defined semantics. In particular, this means that the "GET" 241 method MUST NOT be used. 243 The entity-body MAY include other request-specific parameters, in 244 which case, the "access_token" parameter MUST be properly separated 245 from the request-specific parameters using "&" character(s) (ASCII 246 code 38). 248 For example, the client makes the following HTTP request using 249 transport-layer security: 251 POST /resource HTTP/1.1 252 Host: server.example.com 253 Content-Type: application/x-www-form-urlencoded 255 access_token=vF9dft4qmT 257 The "application/x-www-form-urlencoded" method SHOULD NOT be used 258 except in application contexts where participating browsers do not 259 have access to the "Authorization" request header field. Resource 260 servers MAY support this method. 262 2.3. URI Query Parameter 264 When sending the access token in the HTTP request URI, the client 265 adds the access token to the request URI query component as defined 266 by Uniform Resource Identifier (URI) [RFC3986] using the 267 "access_token" parameter. 269 For example, the client makes the following HTTP request using 270 transport-layer security: 272 GET /resource?access_token=vF9dft4qmT HTTP/1.1 273 Host: server.example.com 275 The HTTP request URI query can include other request-specific 276 parameters, in which case, the "access_token" parameter MUST be 277 properly separated from the request-specific parameters using "&" 278 character(s) (ASCII code 38). 280 For example: 282 https://server.example.com/resource?x=y&access_token=vF9dft4qmT&p=q 284 Because of the security weaknesses associated with the URI method 285 (see Section 4), including the high likelihood that the URL 286 containing the access token will be logged, it SHOULD NOT be used 287 unless it is impossible to transport the access token in the 288 "Authorization" request header field or the HTTP request entity-body. 289 Resource servers MAY support this method. 291 3. The WWW-Authenticate Response Header Field 293 If the protected resource request does not include authentication 294 credentials or does not contain an access token that enables access 295 to the protected resource, the resource server MUST include the HTTP 296 "WWW-Authenticate" response header field; it MAY include it in 297 response to other conditions as well. The "WWW-Authenticate" header 298 field uses the framework defined by HTTP/1.1, Part 7 299 [I-D.ietf-httpbis-p7-auth]. 301 All challenges defined by this specification MUST use the auth-scheme 302 value "Bearer". This scheme MUST be followed by one or more auth- 303 param values. The auth-param attributes used or defined by this 304 specification are as follows. Other auth-param attributes MAY be 305 used as well. 307 A "realm" attribute MAY be included to indicate the scope of 308 protection in the manner described in HTTP/1.1, Part 7 309 [I-D.ietf-httpbis-p7-auth]. The "realm" attribute MUST NOT appear 310 more than once. 312 The "scope" attribute is a space-delimited list of scope values 313 indicating the required scope of the access token for accessing the 314 requested resource. In some cases, the "scope" value will be used 315 when requesting a new access token with sufficient scope of access to 316 utilize the protected resource. Use of the "scope" attribute is 317 OPTIONAL. The "scope" attribute MUST NOT appear more than once. The 318 "scope" value is intended for programmatic use and is not meant to be 319 displayed to end users. 321 If the protected resource request included an access token and failed 322 authentication, the resource server SHOULD include the "error" 323 attribute to provide the client with the reason why the access 324 request was declined. The parameter value is described in 325 Section 3.1. In addition, the resource server MAY include the 326 "error_description" attribute to provide developers a human-readable 327 explanation that is not meant to be displayed to end users. It also 328 MAY include the "error_uri" attribute with an absolute URI 329 identifying a human-readable web page explaining the error. The 330 "error", "error_description", and "error_uri" attributes MUST NOT 331 appear more than once. 333 Values for the "scope" attribute MUST NOT include characters outside 334 the set %x21 / %x23-5B / %x5D-7E for representing scope values and 335 %x20 for delimiters between scope values. Values for the "error" and 336 "error_description" attributes MUST NOT include characters outside 337 the set %x20-21 / %x23-5B / %x5D-7E. Values for the "error_uri" 338 attribute MUST conform to the URI-Reference syntax, and thus MUST NOT 339 include characters outside the set %x21 / %x23-5B / %x5D-7E. 341 For example, in response to a protected resource request without 342 authentication: 344 HTTP/1.1 401 Unauthorized 345 WWW-Authenticate: Bearer realm="example" 347 And in response to a protected resource request with an 348 authentication attempt using an expired access token: 350 HTTP/1.1 401 Unauthorized 351 WWW-Authenticate: Bearer realm="example", 352 error="invalid_token", 353 error_description="The access token expired" 355 3.1. Error Codes 357 When a request fails, the resource server responds using the 358 appropriate HTTP status code (typically, 400, 401, 403, or 405), and 359 includes one of the following error codes in the response: 361 invalid_request 362 The request is missing a required parameter, includes an 363 unsupported parameter or parameter value, repeats the same 364 parameter, uses more than one method for including an access 365 token, or is otherwise malformed. The resource server SHOULD 366 respond with the HTTP 400 (Bad Request) status code. 368 invalid_token 369 The access token provided is expired, revoked, malformed, or 370 invalid for other reasons. The resource SHOULD respond with 371 the HTTP 401 (Unauthorized) status code. The client MAY 372 request a new access token and retry the protected resource 373 request. 375 insufficient_scope 376 The request requires higher privileges than provided by the 377 access token. The resource server SHOULD respond with the HTTP 378 403 (Forbidden) status code and MAY include the "scope" 379 attribute with the scope necessary to access the protected 380 resource. 382 If the request lacks any authentication information (i.e. the client 383 was unaware authentication is necessary or attempted using an 384 unsupported authentication method), the resource server SHOULD NOT 385 include an error code or other error information. 387 For example: 389 HTTP/1.1 401 Unauthorized 390 WWW-Authenticate: Bearer realm="example" 392 4. Security Considerations 394 This section describes the relevant security threats regarding token 395 handling when using bearer tokens and describes how to mitigate these 396 threats. 398 4.1. Security Threats 400 The following list presents several common threats against protocols 401 utilizing some form of tokens. This list of threats is based on NIST 402 Special Publication 800-63 [NIST800-63]. Since this document builds 403 on the OAuth 2.0 specification, we exclude a discussion of threats 404 that are described there or in related documents. 406 Token manufacture/modification: An attacker may generate a bogus 407 token or modify the token contents (such as the authentication or 408 attribute statements) of an existing token, causing the resource 409 server to grant inappropriate access to the client. For example, 410 an attacker may modify the token to extend the validity period; a 411 malicious client may modify the assertion to gain access to 412 information that they should not be able to view. 414 Token disclosure: Tokens may contain authentication and attribute 415 statements that include sensitive information. 417 Token redirect: An attacker uses a token generated for consumption 418 by one resource server to gain access to a different resource 419 server that mistakenly believes the token to be for it. 421 Token replay: An attacker attempts to use a token that has already 422 been used with that resource server in the past. 424 4.2. Threat Mitigation 426 A large range of threats can be mitigated by protecting the contents 427 of the token by using a digital signature or a Message Authentication 428 Code (MAC). Alternatively, a bearer token can contain a reference to 429 authorization information, rather than encoding the information 430 directly. Such references MUST be infeasible for an attacker to 431 guess; using a reference may require an extra interaction between a 432 server and the token issuer to resolve the reference to the 433 authorization information. The mechanics of such an interaction are 434 not defined by this specification. 436 This document does not specify the encoding or the contents of the 437 token; hence detailed recommendations about the means of guaranteeing 438 token integrity protection are outside the scope of this document. 439 The token integrity protection MUST be sufficient to prevent the 440 token from being modified. 442 To deal with token redirect, it is important for the authorization 443 server to include the identity of the intended recipients (the 444 audience), typically a single resource server (or a list of resource 445 servers), in the token. Restricting the use of the token to a 446 specific scope is also RECOMMENDED. 448 The authorization server MUST implement TLS. Which version(s) ought 449 to be implemented will vary over time, and depend on the widespread 450 deployment and known security vulnerabilities at the time of 451 implementation. At the time of this writing, TLS version 1.2 452 [RFC5246] is the most recent version, but has very limited actual 453 deployment, and might not be readily available in implementation 454 toolkits. TLS version 1.0 [RFC2246] is the most widely deployed 455 version, and will give the broadest interoperability. 457 To protect against token disclosure, confidentiality protection MUST 458 be applied using TLS [RFC5246] with a ciphersuite that provides 459 confidentiality and integrity protection. This requires that the 460 communication interaction between the client and the authorization 461 server, as well as the interaction between the client and the 462 resource server, utilize confidentiality and integrity protection. 463 Since TLS is mandatory to implement and to use with this 464 specification, it is the preferred approach for preventing token 465 disclosure via the communication channel. For those cases where the 466 client is prevented from observing the contents of the token, token 467 encryption MUST be applied in addition to the usage of TLS 468 protection. As a further defense against token disclosure, the 469 client MUST validate the TLS certificate chain when making requests 470 to protected resources, including checking the Certificate Revocation 471 List (CRL) [RFC5280]. 473 Cookies are typically transmitted in the clear. Thus, any 474 information contained in them is at risk of disclosure. Therefore, 475 bearer tokens MUST NOT be stored in cookies that can be sent in the 476 clear. 478 In some deployments, including those utilizing load balancers, the 479 TLS connection to the resource server terminates prior to the actual 480 server that provides the resource. This could leave the token 481 unprotected between the front end server where the TLS connection 482 terminates and the back end server that provides the resource. In 483 such deployments, sufficient measures MUST be employed to ensure 484 confidentiality of the token between the front end and back end 485 servers; encryption of the token is one possible such measure. 487 To deal with token capture and replay, the following recommendations 488 are made: First, the lifetime of the token MUST be limited; one means 489 of achieving this is by putting a validity time field inside the 490 protected part of the token. Note that using short-lived (one hour 491 or less) tokens reduces the impact of them being leaked. Second, 492 confidentiality protection of the exchanges between the client and 493 the authorization server and between the client and the resource 494 server MUST be applied. As a consequence, no eavesdropper along the 495 communication path is able to observe the token exchange. 496 Consequently, such an on-path adversary cannot replay the token. 497 Furthermore, when presenting the token to a resource server, the 498 client MUST verify the identity of that resource server, as per 499 Section 3.1 of HTTP Over TLS [RFC2818]. Note that the client MUST 500 validate the TLS certificate chain when making these requests to 501 protected resources. Presenting the token to an unauthenticated and 502 unauthorized resource server or failing to validate the certificate 503 chain will allow adversaries to steal the token and gain unauthorized 504 access to protected resources. 506 4.3. Summary of Recommendations 508 Safeguard bearer tokens: Client implementations MUST ensure that 509 bearer tokens are not leaked to unintended parties, as they will 510 be able to use them to gain access to protected resources. This 511 is the primary security consideration when using bearer tokens and 512 underlies all the more specific recommendations that follow. 514 Validate SSL certificate chains: The client MUST validate the TLS 515 certificate chain when making requests to protected resources. 516 Failing to do so may enable DNS hijacking attacks to steal the 517 token and gain unintended access. 519 Always use TLS (https): Clients MUST always use TLS [RFC5246] 520 (https) or equivalent transport security when making requests with 521 bearer tokens. Failing to do so exposes the token to numerous 522 attacks that could give attackers unintended access. 524 Don't store bearer tokens in cookies: Implementations MUST NOT store 525 bearer tokens within cookies that can be sent in the clear (which 526 is the default transmission mode for cookies). Implementations 527 that do store bearer tokens in cookies MUST take precautions 528 against cross site request forgery. 530 Issue short-lived bearer tokens: Token servers SHOULD issue short- 531 lived (one hour or less) bearer tokens, particularly when issuing 532 tokens to clients that run within a web browser or other 533 environments where information leakage may occur. Using short- 534 lived bearer tokens can reduce the impact of them being leaked. 536 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 537 that contain an audience restriction, scoping their use to the 538 intended relying party or set of relying parties. 540 Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be 541 passed in page URLs (for example as query string parameters). 542 Instead, bearer tokens SHOULD be passed in HTTP message headers or 543 message bodies for which confidentiality measures are taken. 544 Browsers, web servers, and other software may not adequately 545 secure URLs in the browser history, web server logs, and other 546 data structures. If bearer tokens are passed in page URLs, 547 attackers might be able to steal them from the history data, logs, 548 or other unsecured locations. 550 5. IANA Considerations 552 5.1. OAuth Access Token Type Registration 554 This specification registers the following access token type in the 555 OAuth Access Token Type Registry. 557 5.1.1. The "Bearer" OAuth Access Token Type 559 Type name: 560 Bearer 562 Additional Token Endpoint Response Parameters: 563 (none) 565 HTTP Authentication Scheme(s): 566 Bearer 568 Change controller: 569 IETF 571 Specification document(s): 572 [[ this document ]] 574 5.2. Authentication Scheme Registration 576 This specification registers the following authentication scheme in 577 the Authentication Scheme Registry defined in HTTP/1.1, Part 7 578 [I-D.ietf-httpbis-p7-auth]. 580 5.2.1. The "Bearer" Authentication Scheme 582 Authentication Scheme Name: 583 Bearer 585 Pointer to specification text: 586 [[ this document ]] 588 Notes (optional): 589 (none) 591 6. References 593 6.1. Normative References 595 [I-D.ietf-httpbis-p1-messaging] 596 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 597 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 598 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 599 Message Parsing", draft-ietf-httpbis-p1-messaging-18 (work 600 in progress), January 2012. 602 [I-D.ietf-httpbis-p7-auth] 603 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 604 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 605 J. Reschke, "HTTP/1.1, part 7: Authentication", 606 draft-ietf-httpbis-p7-auth-18 (work in progress), 607 January 2012. 609 [I-D.ietf-oauth-v2] 610 Hammer, E., Recordon, D., and D. Hardt, "The OAuth 2.0 611 Authorization Protocol", draft-ietf-oauth-v2-23 (work in 612 progress), January 2012. 614 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 615 Requirement Levels", BCP 14, RFC 2119, March 1997. 617 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 618 RFC 2246, January 1999. 620 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 622 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 623 Resource Identifier (URI): Generic Syntax", STD 66, 624 RFC 3986, January 2005. 626 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 627 Specifications: ABNF", STD 68, RFC 5234, January 2008. 629 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 630 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 632 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 633 Housley, R., and W. Polk, "Internet X.509 Public Key 634 Infrastructure Certificate and Certificate Revocation List 635 (CRL) Profile", RFC 5280, May 2008. 637 [USASCII] American National Standards Institute, "Coded Character 638 Set -- 7-bit American Standard Code for Information 639 Interchange", ANSI X3.4, 1986. 641 [W3C.REC-html401-19991224] 642 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 643 Specification", World Wide Web Consortium 644 Recommendation REC-html401-19991224, December 1999, 645 . 647 6.2. Informative References 649 [NIST800-63] 650 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 651 and E. Nabbus, "NIST Special Publication 800-63-1, 652 INFORMATION SECURITY", December 2008. 654 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 655 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 656 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 658 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 659 Leach, P., Luotonen, A., and L. Stewart, "HTTP 660 Authentication: Basic and Digest Access Authentication", 661 RFC 2617, June 1999. 663 Appendix A. Acknowledgements 665 The following people contributed to preliminary versions of this 666 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland 667 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 668 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 669 concepts within are a product of the OAuth community, the WRAP 670 community, and the OAuth Working Group. 672 The OAuth Working Group has dozens of very active contributors who 673 proposed ideas and wording for this document, including: Michael 674 Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, John Bradley, 675 Brian Campbell, Leah Culver, Bill de hOra, Brian Ellin, Igor 676 Faynberg, Stephen Farrell, George Fletcher, Tim Freeman, Evan 677 Gilbert, Yaron Y. Goland, Thomas Hardjono, Justin Hart, Phil Hunt, 678 John Kemp, Eran Hammer, Chasen Le Hara, Barry Leiba, Michael B. 679 Jones, Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, 680 William J. Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, 681 Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius 682 Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian 683 Stuebner, Paul Tarjan, Hannes Tschofenig, Franklin Tse, and Shane 684 Weeden. 686 Appendix B. Document History 688 [[ to be removed by the RFC editor before publication as an RFC ]] 690 -17 692 o Restore RFC 2818 reference for server identity verification and 693 add RFC 5280 reference for certificate revocation lists, per Gen- 694 ART review comments. 696 -16 698 o Use the HTTPbis auth-param syntax for Bearer challenge attributes. 700 o Dropped the sentence "The "realm" value is intended for 701 programmatic use and is not meant to be displayed to end users". 703 o Reordered form-encoded body parameter description bullets for 704 better readability. 706 o Added [USASCII] reference. 708 -15 710 o Clarified that form-encoded content must consist entirely of ASCII 711 characters. 713 o Added TLS version requirements. 715 o Applied editorial improvements suggested by Mark Nottingham during 716 the APPS area review. 718 -14 720 o Changes made in response to review comments by Security Area 721 Director Stephen Farrell. Specifically: 723 o Strengthened warnings about passing an access token as a query 724 parameter and more precisely described the limitations placed upon 725 the use of this method. 727 o Clarified that the "realm" attribute MAY included to indicate the 728 scope of protection in the manner described in HTTP/1.1, Part 7 729 [I-D.ietf-httpbis-p7-auth]. 731 o Normatively stated that "the token integrity protection MUST be 732 sufficient to prevent the token from being modified". 734 o Added statement that "TLS is mandatory to implement and use with 735 this specification" to the introduction. 737 o Stated that TLS MUST be used with "a ciphersuite that provides 738 confidentiality and integrity protection". 740 o Added "As a further defense against token disclosure, the client 741 MUST validate the TLS certificate chain when making requests to 742 protected resources" to the Threat Mitigation section. 744 o Clarified that putting a validity time field inside the protected 745 part of the token is one means, but not the only means, of 746 limiting the lifetime of the token. 748 o Dropped the confusing phrase "for instance, through the use of 749 TLS" from the sentence about confidentiality protection of the 750 exchanges. 752 o Reference RFC 6125 for identity verification, rather than RFC 753 2818. 755 o Stated that the token MUST be protected between front end and back 756 end servers when the TLS connection terminates at a front end 757 server that is distinct from the actual server that provides the 758 resource. 760 o Stated that bearer tokens MUST NOT be stored in cookies that can 761 be sent in the clear in the Threat Mitigation section. 763 o Replaced sole remaining reference to [RFC2616] with HTTPbis 764 [I-D.ietf-httpbis-p1-messaging] reference. 766 o Replaced all references where the reference is used as if it were 767 part of the sentence (such as "defined by [I-D.whatever]") with 768 ones where the specification name is used, followed by the 769 reference (such as "defined by Whatever [I-D.whatever]"). 771 o Other on-normative editorial improvements. 773 -13 775 o At the request of Hannes Tschofenig, made ABNF changes to make it 776 clear that no special WWW-Authenticate response header field 777 parsers are needed. The "scope", "error-description", and 778 "error-uri" parameters are all now defined as quoted-string in the 779 ABNF (as "error" already was). Restrictions on these values that 780 were formerly described in the ABNFs are now described in 781 normative text instead. 783 -12 785 o Made non-normative editorial changes that Hannes Tschofenig 786 requested be applied prior to forwarding the specification to the 787 IESG. 789 o Added rationale for the choice of the b64token syntax. 791 o Added rationale stating that receivers are free to parse the 792 "scope" attribute using a standard quoted-string parser, since it 793 will correctly process all legal "scope" values. 795 o Added additional active working group contributors to the 796 Acknowledgements section. 798 -11 800 o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. 802 -10 804 o Removed the #auth-param option from Authorization header syntax 805 (leaving only the b64token syntax). 807 o Restricted the "scope" value character set to %x21 / %x23-5B / 808 %x5D-7E (printable ASCII characters excluding double-quote and 809 backslash). Indicated that scope is intended for programmatic use 810 and is not meant to be displayed to end users. 812 o Restricted the character set for "error_description" strings to SP 813 / VCHAR and indicated that they are not meant to be displayed to 814 end users. 816 o Included more description in the Abstract, since Hannes Tschofenig 817 indicated that the RFC editor would require this. 819 o Changed "Access Grant" to "Authorization Grant", as was done in 820 the core spec. 822 o Simplified the introduction to the Authenticated Requests section. 824 -09 826 o Incorporated working group last call comments. Specific changes 827 were: 829 o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than 830 [RFC2617]. 832 o Update credentials definition to conform to 833 [I-D.ietf-httpbis-p7-auth]. 835 o Further clarified that query parameters may occur in any order. 837 o Specify that error_description is UTF-8 encoded (matching the core 838 specification). 840 o Registered "Bearer" Authentication Scheme in Authentication Scheme 841 Registry defined by [I-D.ietf-httpbis-p7-auth]. 843 o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- 844 p7-auth drafts. 846 o Other wording improvements not introducing normative changes. 848 -08 850 o Updated references to oauth-v2 and HTTPbis drafts. 852 -07 854 o Added missing comma in error response example. 856 -06 858 o Changed parameter name "bearer_token" to "access_token", per 859 working group consensus. 861 o Changed HTTP status code for "invalid_request" error code from 862 HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input 863 from HTTP working group experts. 865 -05 867 o Removed OAuth Errors Registry, per design team input. 869 o Changed HTTP status code for "invalid_request" error code from 870 HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP 871 usage [[ change pending working group consensus ]]. 873 o Added missing quotation marks in error-uri definition. 875 o Added note to add language and encoding information to 876 error_description if the core specification does. 878 o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined 879 in [RFC5234]. 881 o Use auth-param instead of repeating its definition, which is ( 882 token "=" ( token / quoted-string ) ). 884 o Clarify security considerations about including an audience 885 restriction in the token and include a recommendation to issue 886 scoped bearer tokens in the summary of recommendations. 888 -04 890 o Edits responding to working group last call feedback on -03. 891 Specific edits enumerated below. 893 o Added Bearer Token definition in Terminology section. 895 o Changed parameter name "oauth_token" to "bearer_token". 897 o Added realm parameter to "WWW-Authenticate" response to comply 898 with [RFC2617]. 900 o Removed "[ RWS 1#auth-param ]" from "credentials" definition since 901 it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. 903 o Removed restriction that the "bearer_token" (formerly 904 "oauth_token") parameter be the last parameter in the entity-body 905 and the HTTP request URI query. 907 o Do not require WWW-Authenticate Response in a reply to a malformed 908 request, as an HTTP 400 Bad Request response without a WWW- 909 Authenticate header is likely the right response in some cases of 910 malformed requests. 912 o Removed OAuth Parameters registry extension. 914 o Numerous editorial improvements suggested by working group 915 members. 917 -03 919 o Restored the WWW-Authenticate response header functionality 920 deleted from the framework specification in draft 12 based upon 921 the specification text from draft 11. 923 o Augmented the OAuth Parameters registry by adding two additional 924 parameter usage locations: "resource request" and "resource 925 response". 927 o Registered the "oauth_token" OAuth parameter with usage location 928 "resource request". 930 o Registered the "error" OAuth parameter. 932 o Created the OAuth Error registry and registered errors. 934 o Changed the "OAuth2" OAuth access token type name to "Bearer". 936 -02 938 o Incorporated feedback received on draft 01. Most changes were to 939 the security considerations section. No normative changes were 940 made. Specific changes included: 942 o Changed terminology from "token reuse" to "token capture and 943 replay". 945 o Removed sentence "Encrypting the token contents is another 946 alternative" from the security considerations since it was 947 redundant and potentially confusing. 949 o Corrected some references to "resource server" to be 950 "authorization server" in the security considerations. 952 o Generalized security considerations language about obtaining 953 consent of the resource owner. 955 o Broadened scope of security considerations description for 956 recommendation "Don't pass bearer tokens in page URLs". 958 o Removed unused reference to OAuth 1.0. 960 o Updated reference to framework specification and updated David 961 Recordon's e-mail address. 963 o Removed security considerations text on authenticating clients. 965 o Registered the "OAuth2" OAuth access token type and "oauth_token" 966 parameter. 968 -01 970 o First public draft, which incorporates feedback received on -00 971 including enhanced Security Considerations content. This version 972 is intended to accompany OAuth 2.0 draft 11. 974 -00 976 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 978 Authors' Addresses 980 Michael B. Jones 981 Microsoft 983 Email: mbj@microsoft.com 984 URI: http://self-issued.info/ 986 Dick Hardt 987 independent 989 Email: dick.hardt@gmail.com 990 URI: http://dickhardt.org/ 992 David Recordon 993 Facebook 995 Email: dr@fb.com 996 URI: http://www.davidrecordon.com/