idnits 2.17.00 (12 Aug 2021) /tmp/idnits56333/draft-ietf-oauth-v2-bearer-19.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 (April 23, 2012) is 3679 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: draft-ietf-httpbis-p1-messaging has been published as RFC 7230 == Outdated reference: draft-ietf-httpbis-p7-auth has been published as RFC 7235 == Outdated reference: draft-ietf-oauth-v2 has been published as RFC 6749 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Downref: Normative reference to an Informational RFC: RFC 2818 ** 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: October 25, 2012 independent 6 D. Recordon 7 Facebook 8 April 23, 2012 10 The OAuth 2.0 Authorization Protocol: Bearer Tokens 11 draft-ietf-oauth-v2-bearer-19 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 October 25, 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. Example Access Token Response . . . . . . . . . . . . . . . . 10 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 68 5.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 10 69 5.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 11 70 5.3. Summary of Recommendations . . . . . . . . . . . . . . . . 13 71 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 72 6.1. OAuth Access Token Type Registration . . . . . . . . . . . 14 73 6.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 14 74 6.2. Authentication Scheme Registration . . . . . . . . . . . . 14 75 6.2.1. The "Bearer" Authentication Scheme . . . . . . . . . . 14 76 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 77 7.1. Normative References . . . . . . . . . . . . . . . . . . . 14 78 7.2. Informative References . . . . . . . . . . . . . . . . . . 16 79 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 80 Appendix B. Document History . . . . . . . . . . . . . . . . . . 17 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 83 1. Introduction 85 OAuth enables clients to access protected resources by obtaining an 86 access token, which is defined in OAuth 2.0 Authorization 87 [I-D.ietf-oauth-v2] as "a string representing an access authorization 88 issued to the client", rather than using the resource owner's 89 credentials directly. 91 Tokens are issued to clients by an authorization server with the 92 approval of the resource owner. The client uses the access token to 93 access the protected resources hosted by the resource server. This 94 specification describes how to make protected resource requests when 95 the OAuth access token is a bearer token. 97 This specification defines the use of bearer tokens over HTTP/1.1 98 [I-D.ietf-httpbis-p1-messaging] using TLS [RFC5246] to access 99 protected resources. TLS is mandatory to implement and use with this 100 specification; other specifications may extend this specification for 101 use with other transport protocols. While designed for use with 102 access tokens resulting from OAuth 2.0 Authorization 103 [I-D.ietf-oauth-v2] flows to access OAuth protected resources, this 104 specification actually defines a general HTTP authorization method 105 that can be used with bearer tokens from any source to access any 106 resources protected by those bearer tokens. The Bearer 107 authentication scheme is intended primarily for server authentication 108 using the WWW-Authenticate and Authorization HTTP headers, but does 109 not preclude its use for proxy authentication. 111 1.1. Notational Conventions 113 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 114 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 115 document are to be interpreted as described in Key words for use in 116 RFCs to Indicate Requirement Levels [RFC2119]. 118 This document uses the Augmented Backus-Naur Form (ABNF) notation of 119 [RFC5234]. Additionally, the following rules are included from 120 HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth]: auth-param, auth-scheme, 121 and b64token; and from Uniform Resource Identifier (URI) [RFC3986]: 122 URI-Reference. 124 Unless otherwise noted, all the protocol parameter names and values 125 are case sensitive. 127 1.2. Terminology 128 Bearer Token 129 A security token with the property that any party in possession of 130 the token (a "bearer") can use the token in any way that any other 131 party in possession of it can. Using a bearer token does not 132 require a bearer to prove possession of cryptographic key material 133 (proof-of-possession). 135 All other terms are as defined in OAuth 2.0 Authorization 136 [I-D.ietf-oauth-v2]. 138 1.3. Overview 140 OAuth provides a method for clients to access a protected resource on 141 behalf of a resource owner. In the general case, before a client can 142 access a protected resource, it must first obtain an authorization 143 grant from the resource owner and then exchange the authorization 144 grant for an access token. The access token represents the grant's 145 scope, duration, and other attributes granted by the authorization 146 grant. The client accesses the protected resource by presenting the 147 access token to the resource server. In some cases, a client can 148 directly present its own credentials to an authorization server to 149 obtain an access token without having to first obtain an 150 authorization grant from a resource owner. 152 The access token provides an abstraction, replacing different 153 authorization constructs (e.g. username and password, assertion) for 154 a single token understood by the resource server. This abstraction 155 enables issuing access tokens valid for a short time period, as well 156 as removing the resource server's need to understand a wide range of 157 authentication schemes. 159 +--------+ +---------------+ 160 | |--(A)- Authorization Request ->| Resource | 161 | | | Owner | 162 | |<-(B)-- Authorization Grant ---| | 163 | | +---------------+ 164 | | 165 | | Authorization Grant & +---------------+ 166 | |--(C)--- Client Credentials -->| Authorization | 167 | Client | | Server | 168 | |<-(D)----- Access Token -------| | 169 | | +---------------+ 170 | | 171 | | +---------------+ 172 | |--(E)----- Access Token ------>| Resource | 173 | | | Server | 174 | |<-(F)--- Protected Resource ---| | 175 +--------+ +---------------+ 177 Figure 1: Abstract Protocol Flow 179 The abstract flow illustrated in Figure 1 describes the overall OAuth 180 2.0 protocol architecture. The following steps are specified within 181 this document: 183 E) The client makes a protected resource request to the resource 184 server by presenting the access token. 186 F) The resource server validates the access token, and if valid, 187 serves the request. 189 This document also imposes semantic requirements upon the access 190 token returned in Step D. 192 2. Authenticated Requests 194 This section defines three methods of sending bearer access tokens in 195 resource requests to resource servers. Clients MUST NOT use more 196 than one method to transmit the token in each request. 198 2.1. Authorization Request Header Field 200 When sending the access token in the "Authorization" request header 201 field defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth], the 202 client uses the "Bearer" authentication scheme to transmit the access 203 token. 205 For example: 206 GET /resource HTTP/1.1 207 Host: server.example.com 208 Authorization: Bearer mF_9.B5f-4.1JqM 210 The "Authorization" header field uses the framework defined by 211 HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] as follows: 212 credentials = "Bearer" 1*SP b64token 214 The b64token syntax was chosen over the alternative #auth-param 215 syntax also defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] 216 both for simplicity and for compatibility with existing 217 implementations. If additional parameters are needed in the future, 218 a different scheme would need to be defined. 220 Clients SHOULD make authenticated requests with a bearer token using 221 the "Authorization" request header field with the "Bearer" HTTP 222 authorization scheme. Resource servers compliant with this 223 specification MUST support this method. 225 2.2. Form-Encoded Body Parameter 227 When sending the access token in the HTTP request entity-body, the 228 client adds the access token to the request body using the 229 "access_token" parameter. The client MUST NOT use this method unless 230 all of the following conditions are met: 232 o The HTTP request entity-header includes the "Content-Type" header 233 field set to "application/x-www-form-urlencoded". 235 o The entity-body follows the encoding requirements of the 236 "application/x-www-form-urlencoded" content-type as defined by 237 HTML 4.01 [W3C.REC-html401-19991224]. 239 o The HTTP request entity-body is single-part. 241 o The content to be encoded in the entity-body MUST consist entirely 242 of ASCII [USASCII] characters. 244 o The HTTP request method is one for which the request body has 245 defined semantics. In particular, this means that the "GET" 246 method MUST NOT be used. 248 The entity-body MAY include other request-specific parameters, in 249 which case, the "access_token" parameter MUST be properly separated 250 from the request-specific parameters using "&" character(s) (ASCII 251 code 38). 253 For example, the client makes the following HTTP request using 254 transport-layer security: 255 POST /resource HTTP/1.1 256 Host: server.example.com 257 Content-Type: application/x-www-form-urlencoded 259 access_token=mF_9.B5f-4.1JqM 261 The "application/x-www-form-urlencoded" method SHOULD NOT be used 262 except in application contexts where participating browsers do not 263 have access to the "Authorization" request header field. Resource 264 servers compliant with this specification MAY support this method. 266 2.3. URI Query Parameter 268 When sending the access token in the HTTP request URI, the client 269 adds the access token to the request URI query component as defined 270 by Uniform Resource Identifier (URI) [RFC3986] using the 271 "access_token" parameter. 273 For example, the client makes the following HTTP request using 274 transport-layer security: 275 GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1 276 Host: server.example.com 278 The HTTP request URI query can include other request-specific 279 parameters, in which case, the "access_token" parameter MUST be 280 properly separated from the request-specific parameters using "&" 281 character(s) (ASCII code 38). 283 For example: 284 https://server.example.com/resource?x=y&access_token=mF_9.B5f-4.1JqM&p=q 286 Because of the security weaknesses associated with the URI method 287 (see Section 5), including the high likelihood that the URL 288 containing the access token will be logged, it SHOULD NOT be used 289 unless it is impossible to transport the access token in the 290 "Authorization" request header field or the HTTP request entity-body. 291 Resource servers compliant with this specification MAY support this 292 method. 294 3. The WWW-Authenticate Response Header Field 296 If the protected resource request does not include authentication 297 credentials or does not contain an access token that enables access 298 to the protected resource, the resource server MUST include the HTTP 299 "WWW-Authenticate" response header field; it MAY include it in 300 response to other conditions as well. The "WWW-Authenticate" header 301 field uses the framework defined by HTTP/1.1, Part 7 302 [I-D.ietf-httpbis-p7-auth]. 304 All challenges defined by this specification MUST use the auth-scheme 305 value "Bearer". This scheme MUST be followed by one or more auth- 306 param values. The auth-param attributes used or defined by this 307 specification are as follows. Other auth-param attributes MAY be 308 used as well. 310 A "realm" attribute MAY be included to indicate the scope of 311 protection in the manner described in HTTP/1.1, Part 7 312 [I-D.ietf-httpbis-p7-auth]. The "realm" attribute MUST NOT appear 313 more than once. 315 The "scope" attribute is defined in Section 3.3 of OAuth 2.0 316 Authorization [I-D.ietf-oauth-v2]. The "scope" attribute is a space- 317 delimited list of case sensitive scope values indicating the required 318 scope of the access token for accessing the requested resource. 319 "scope" values are implementation defined; there is no centralized 320 registry for them; allowed values are defined by the authorization 321 server. The order of "scope" values is not significant. In some 322 cases, the "scope" value will be used when requesting a new access 323 token with sufficient scope of access to utilize the protected 324 resource. Use of the "scope" attribute is OPTIONAL. The "scope" 325 attribute MUST NOT appear more than once. The "scope" value is 326 intended for programmatic use and is not meant to be displayed to end 327 users. 329 Two example scope values follow; these are taken from the OpenID 330 Connect [OpenID.Messages] and OATC Online Multimedia Authorization 331 Protocol [OMAP] OAuth 2.0 use cases, respectively: 332 scope="openid profile email" 333 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 335 If the protected resource request included an access token and failed 336 authentication, the resource server SHOULD include the "error" 337 attribute to provide the client with the reason why the access 338 request was declined. The parameter value is described in 339 Section 3.1. In addition, the resource server MAY include the 340 "error_description" attribute to provide developers a human-readable 341 explanation that is not meant to be displayed to end users. It also 342 MAY include the "error_uri" attribute with an absolute URI 343 identifying a human-readable web page explaining the error. The 344 "error", "error_description", and "error_uri" attributes MUST NOT 345 appear more than once. 347 Values for the "scope" attribute MUST NOT include characters outside 348 the set %x21 / %x23-5B / %x5D-7E for representing scope values and 349 %x20 for delimiters between scope values. Values for the "error" and 350 "error_description" attributes MUST NOT include characters outside 351 the set %x20-21 / %x23-5B / %x5D-7E. Values for the "error_uri" 352 attribute MUST conform to the URI-Reference syntax, and thus MUST NOT 353 include characters outside the set %x21 / %x23-5B / %x5D-7E. 355 For example, in response to a protected resource request without 356 authentication: 357 HTTP/1.1 401 Unauthorized 358 WWW-Authenticate: Bearer realm="example" 360 And in response to a protected resource request with an 361 authentication attempt using an expired access token: 362 HTTP/1.1 401 Unauthorized 363 WWW-Authenticate: Bearer realm="example", 364 error="invalid_token", 365 error_description="The access token expired" 367 3.1. Error Codes 369 When a request fails, the resource server responds using the 370 appropriate HTTP status code (typically, 400, 401, 403, or 405), and 371 includes one of the following error codes in the response: 373 invalid_request 374 The request is missing a required parameter, includes an 375 unsupported parameter or parameter value, repeats the same 376 parameter, uses more than one method for including an access 377 token, or is otherwise malformed. The resource server SHOULD 378 respond with the HTTP 400 (Bad Request) status code. 380 invalid_token 381 The access token provided is expired, revoked, malformed, or 382 invalid for other reasons. The resource SHOULD respond with 383 the HTTP 401 (Unauthorized) status code. The client MAY 384 request a new access token and retry the protected resource 385 request. 387 insufficient_scope 388 The request requires higher privileges than provided by the 389 access token. The resource server SHOULD respond with the HTTP 390 403 (Forbidden) status code and MAY include the "scope" 391 attribute with the scope necessary to access the protected 392 resource. 394 If the request lacks any authentication information (i.e. the client 395 was unaware authentication is necessary or attempted using an 396 unsupported authentication method), the resource server SHOULD NOT 397 include an error code or other error information. 399 For example: 400 HTTP/1.1 401 Unauthorized 401 WWW-Authenticate: Bearer realm="example" 403 4. Example Access Token Response 405 Typically a bearer token is returned to the client as part of an 406 OAuth 2.0 [I-D.ietf-oauth-v2] access token response. An example of 407 such a response is: 408 HTTP/1.1 200 OK 409 Content-Type: application/json;charset=UTF-8 410 Cache-Control: no-store 411 Pragma: no-cache 413 { 414 "access_token":"mF_9.B5f-4.1JqM", 415 "token_type":"Bearer", 416 "expires_in":3600, 417 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" 418 } 420 5. Security Considerations 422 This section describes the relevant security threats regarding token 423 handling when using bearer tokens and describes how to mitigate these 424 threats. 426 5.1. Security Threats 428 The following list presents several common threats against protocols 429 utilizing some form of tokens. This list of threats is based on NIST 430 Special Publication 800-63 [NIST800-63]. Since this document builds 431 on the OAuth 2.0 specification, we exclude a discussion of threats 432 that are described there or in related documents. 434 Token manufacture/modification: An attacker may generate a bogus 435 token or modify the token contents (such as the authentication or 436 attribute statements) of an existing token, causing the resource 437 server to grant inappropriate access to the client. For example, 438 an attacker may modify the token to extend the validity period; a 439 malicious client may modify the assertion to gain access to 440 information that they should not be able to view. 442 Token disclosure: Tokens may contain authentication and attribute 443 statements that include sensitive information. 445 Token redirect: An attacker uses a token generated for consumption 446 by one resource server to gain access to a different resource 447 server that mistakenly believes the token to be for it. 449 Token replay: An attacker attempts to use a token that has already 450 been used with that resource server in the past. 452 5.2. Threat Mitigation 454 A large range of threats can be mitigated by protecting the contents 455 of the token by using a digital signature or a Message Authentication 456 Code (MAC). Alternatively, a bearer token can contain a reference to 457 authorization information, rather than encoding the information 458 directly. Such references MUST be infeasible for an attacker to 459 guess; using a reference may require an extra interaction between a 460 server and the token issuer to resolve the reference to the 461 authorization information. The mechanics of such an interaction are 462 not defined by this specification. 464 This document does not specify the encoding or the contents of the 465 token; hence detailed recommendations about the means of guaranteeing 466 token integrity protection are outside the scope of this document. 467 The token integrity protection MUST be sufficient to prevent the 468 token from being modified. 470 To deal with token redirect, it is important for the authorization 471 server to include the identity of the intended recipients (the 472 audience), typically a single resource server (or a list of resource 473 servers), in the token. Restricting the use of the token to a 474 specific scope is also RECOMMENDED. 476 The authorization server MUST implement TLS. Which version(s) ought 477 to be implemented will vary over time, and depend on the widespread 478 deployment and known security vulnerabilities at the time of 479 implementation. At the time of this writing, TLS version 1.2 480 [RFC5246] is the most recent version, but has very limited actual 481 deployment, and might not be readily available in implementation 482 toolkits. TLS version 1.0 [RFC2246] is the most widely deployed 483 version, and will give the broadest interoperability. 485 To protect against token disclosure, confidentiality protection MUST 486 be applied using TLS [RFC5246] with a ciphersuite that provides 487 confidentiality and integrity protection. This requires that the 488 communication interaction between the client and the authorization 489 server, as well as the interaction between the client and the 490 resource server, utilize confidentiality and integrity protection. 491 Since TLS is mandatory to implement and to use with this 492 specification, it is the preferred approach for preventing token 493 disclosure via the communication channel. For those cases where the 494 client is prevented from observing the contents of the token, token 495 encryption MUST be applied in addition to the usage of TLS 496 protection. As a further defense against token disclosure, the 497 client MUST validate the TLS certificate chain when making requests 498 to protected resources, including checking the Certificate Revocation 499 List (CRL) [RFC5280]. 501 Cookies are typically transmitted in the clear. Thus, any 502 information contained in them is at risk of disclosure. Therefore, 503 bearer tokens MUST NOT be stored in cookies that can be sent in the 504 clear. See HTTP State Management Mechanism [RFC6265] for security 505 considerations about cookies. 507 In some deployments, including those utilizing load balancers, the 508 TLS connection to the resource server terminates prior to the actual 509 server that provides the resource. This could leave the token 510 unprotected between the front end server where the TLS connection 511 terminates and the back end server that provides the resource. In 512 such deployments, sufficient measures MUST be employed to ensure 513 confidentiality of the token between the front end and back end 514 servers; encryption of the token is one possible such measure. 516 To deal with token capture and replay, the following recommendations 517 are made: First, the lifetime of the token MUST be limited; one means 518 of achieving this is by putting a validity time field inside the 519 protected part of the token. Note that using short-lived (one hour 520 or less) tokens reduces the impact of them being leaked. Second, 521 confidentiality protection of the exchanges between the client and 522 the authorization server and between the client and the resource 523 server MUST be applied. As a consequence, no eavesdropper along the 524 communication path is able to observe the token exchange. 525 Consequently, such an on-path adversary cannot replay the token. 526 Furthermore, when presenting the token to a resource server, the 527 client MUST verify the identity of that resource server, as per 528 Section 3.1 of HTTP Over TLS [RFC2818]. Note that the client MUST 529 validate the TLS certificate chain when making these requests to 530 protected resources. Presenting the token to an unauthenticated and 531 unauthorized resource server or failing to validate the certificate 532 chain will allow adversaries to steal the token and gain unauthorized 533 access to protected resources. 535 5.3. Summary of Recommendations 537 Safeguard bearer tokens: Client implementations MUST ensure that 538 bearer tokens are not leaked to unintended parties, as they will 539 be able to use them to gain access to protected resources. This 540 is the primary security consideration when using bearer tokens and 541 underlies all the more specific recommendations that follow. 543 Validate TLS certificate chains: The client MUST validate the TLS 544 certificate chain when making requests to protected resources. 545 Failing to do so may enable DNS hijacking attacks to steal the 546 token and gain unintended access. 548 Always use TLS (https): Clients MUST always use TLS [RFC5246] 549 (https) or equivalent transport security when making requests with 550 bearer tokens. Failing to do so exposes the token to numerous 551 attacks that could give attackers unintended access. 553 Don't store bearer tokens in cookies: Implementations MUST NOT store 554 bearer tokens within cookies that can be sent in the clear (which 555 is the default transmission mode for cookies). Implementations 556 that do store bearer tokens in cookies MUST take precautions 557 against cross site request forgery. 559 Issue short-lived bearer tokens: Token servers SHOULD issue short- 560 lived (one hour or less) bearer tokens, particularly when issuing 561 tokens to clients that run within a web browser or other 562 environments where information leakage may occur. Using short- 563 lived bearer tokens can reduce the impact of them being leaked. 565 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 566 that contain an audience restriction, scoping their use to the 567 intended relying party or set of relying parties. 569 Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be 570 passed in page URLs (for example as query string parameters). 571 Instead, bearer tokens SHOULD be passed in HTTP message headers or 572 message bodies for which confidentiality measures are taken. 573 Browsers, web servers, and other software may not adequately 574 secure URLs in the browser history, web server logs, and other 575 data structures. If bearer tokens are passed in page URLs, 576 attackers might be able to steal them from the history data, logs, 577 or other unsecured locations. 579 6. IANA Considerations 581 6.1. OAuth Access Token Type Registration 583 This specification registers the following access token type in the 584 OAuth Access Token Type Registry. 586 6.1.1. The "Bearer" OAuth Access Token Type 588 Type name: 589 Bearer 591 Additional Token Endpoint Response Parameters: 592 (none) 594 HTTP Authentication Scheme(s): 595 Bearer 597 Change controller: 598 IETF 600 Specification document(s): 601 [[ this document ]] 603 6.2. Authentication Scheme Registration 605 This specification registers the following authentication scheme in 606 the Authentication Scheme Registry defined in HTTP/1.1, Part 7 607 [I-D.ietf-httpbis-p7-auth]. 609 6.2.1. The "Bearer" Authentication Scheme 611 Authentication Scheme Name: 612 Bearer 614 Pointer to specification text: 615 [[ this document ]] 617 Notes (optional): 618 (none) 620 7. References 622 7.1. Normative References 624 [I-D.ietf-httpbis-p1-messaging] 625 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 626 1: URIs, Connections, and Message Parsing", 627 draft-ietf-httpbis-p1-messaging-19 (work in progress), 628 March 2012. 630 [I-D.ietf-httpbis-p7-auth] 631 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 632 7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in 633 progress), March 2012. 635 [I-D.ietf-oauth-v2] 636 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 637 2.0 Authorization Protocol", draft-ietf-oauth-v2-25 (work 638 in progress), March 2012. 640 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 641 Requirement Levels", BCP 14, RFC 2119, March 1997. 643 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 644 RFC 2246, January 1999. 646 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 648 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 649 Resource Identifier (URI): Generic Syntax", STD 66, 650 RFC 3986, January 2005. 652 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 653 Specifications: ABNF", STD 68, RFC 5234, January 2008. 655 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 656 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 658 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 659 Housley, R., and W. Polk, "Internet X.509 Public Key 660 Infrastructure Certificate and Certificate Revocation List 661 (CRL) Profile", RFC 5280, May 2008. 663 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 664 April 2011. 666 [USASCII] American National Standards Institute, "Coded Character 667 Set -- 7-bit American Standard Code for Information 668 Interchange", ANSI X3.4, 1986. 670 [W3C.REC-html401-19991224] 671 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 672 Specification", World Wide Web Consortium 673 Recommendation REC-html401-19991224, December 1999, 674 . 676 7.2. Informative References 678 [NIST800-63] 679 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 680 and E. Nabbus, "NIST Special Publication 800-63-1, 681 INFORMATION SECURITY", December 2008. 683 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 684 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 685 and B. Boyer, "Online Multimedia Authorization Protocol: 686 An Industry Standard for Authorized Access to Internet 687 Multimedia Resources", April 2012. 689 [OpenID.Messages] 690 Sakimura, N., Recordon, D., Bradley, J., de Medeiros, B., 691 Jones, M., and E. Jay, "OpenID Connect Messages 1.0", 692 April 2012. 694 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 695 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 696 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 698 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 699 Leach, P., Luotonen, A., and L. Stewart, "HTTP 700 Authentication: Basic and Digest Access Authentication", 701 RFC 2617, June 1999. 703 Appendix A. Acknowledgements 705 The following people contributed to preliminary versions of this 706 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland 707 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 708 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 709 concepts within are a product of the OAuth community, the WRAP 710 community, and the OAuth Working Group. 712 The OAuth Working Group has dozens of very active contributors who 713 proposed ideas and wording for this document, including: Michael 714 Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, John Bradley, 715 Brian Campbell, Leah Culver, Bill de hOra, Brian Ellin, Igor 716 Faynberg, Stephen Farrell, George Fletcher, Tim Freeman, Evan 717 Gilbert, Yaron Y. Goland, Thomas Hardjono, Justin Hart, Phil Hunt, 718 John Kemp, Eran Hammer, Chasen Le Hara, Barry Leiba, Michael B. 719 Jones, Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, 720 William J. Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, 721 Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius 722 Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian 723 Stuebner, Paul Tarjan, Hannes Tschofenig, Franklin Tse, and Shane 724 Weeden. 726 Appendix B. Document History 728 [[ to be removed by the RFC editor before publication as an RFC ]] 730 -19 732 o Addressed DISCUSS issues and comments raised for which resultions 733 have been agreed to. No normative changes were made. Changes 734 made were: 736 o Use ABNF from RFC 5234. 738 o Added sentence "The Bearer authentication scheme is intended 739 primarily for server authentication using the WWW-Authenticate and 740 Authorization HTTP headers, but does not preclude its use for 741 proxy authentication" to the introduction. 743 o In the introduction, state that this document also imposes 744 semantic requirements upon the access token. 746 o Reference the "scope" definition in the OAuth core spec. 748 o Added "scope" examples. 750 o Reference RFC 6265 for security considerations about cookies. 752 -18 754 o Changed example bearer token value from vF9dft4qmT to mF_9.B5f- 755 4.1JqM. 757 o Added example access token response returning a Bearer token. 759 -17 761 o Restore RFC 2818 reference for server identity verification and 762 add RFC 5280 reference for certificate revocation lists, per Gen- 763 ART review comments. 765 -16 766 o Use the HTTPbis auth-param syntax for Bearer challenge attributes. 768 o Dropped the sentence "The "realm" value is intended for 769 programmatic use and is not meant to be displayed to end users". 771 o Reordered form-encoded body parameter description bullets for 772 better readability. 774 o Added [USASCII] reference. 776 -15 778 o Clarified that form-encoded content must consist entirely of ASCII 779 characters. 781 o Added TLS version requirements. 783 o Applied editorial improvements suggested by Mark Nottingham during 784 the APPS area review. 786 -14 788 o Changes made in response to review comments by Security Area 789 Director Stephen Farrell. Specifically: 791 o Strengthened warnings about passing an access token as a query 792 parameter and more precisely described the limitations placed upon 793 the use of this method. 795 o Clarified that the "realm" attribute MAY included to indicate the 796 scope of protection in the manner described in HTTP/1.1, Part 7 797 [I-D.ietf-httpbis-p7-auth]. 799 o Normatively stated that "the token integrity protection MUST be 800 sufficient to prevent the token from being modified". 802 o Added statement that "TLS is mandatory to implement and use with 803 this specification" to the introduction. 805 o Stated that TLS MUST be used with "a ciphersuite that provides 806 confidentiality and integrity protection". 808 o Added "As a further defense against token disclosure, the client 809 MUST validate the TLS certificate chain when making requests to 810 protected resources" to the Threat Mitigation section. 812 o Clarified that putting a validity time field inside the protected 813 part of the token is one means, but not the only means, of 814 limiting the lifetime of the token. 816 o Dropped the confusing phrase "for instance, through the use of 817 TLS" from the sentence about confidentiality protection of the 818 exchanges. 820 o Reference RFC 6125 for identity verification, rather than RFC 821 2818. 823 o Stated that the token MUST be protected between front end and back 824 end servers when the TLS connection terminates at a front end 825 server that is distinct from the actual server that provides the 826 resource. 828 o Stated that bearer tokens MUST NOT be stored in cookies that can 829 be sent in the clear in the Threat Mitigation section. 831 o Replaced sole remaining reference to [RFC2616] with HTTPbis 832 [I-D.ietf-httpbis-p1-messaging] reference. 834 o Replaced all references where the reference is used as if it were 835 part of the sentence (such as "defined by [I-D.whatever]") with 836 ones where the specification name is used, followed by the 837 reference (such as "defined by Whatever [I-D.whatever]"). 839 o Other on-normative editorial improvements. 841 -13 843 o At the request of Hannes Tschofenig, made ABNF changes to make it 844 clear that no special WWW-Authenticate response header field 845 parsers are needed. The "scope", "error-description", and 846 "error-uri" parameters are all now defined as quoted-string in the 847 ABNF (as "error" already was). Restrictions on these values that 848 were formerly described in the ABNFs are now described in 849 normative text instead. 851 -12 853 o Made non-normative editorial changes that Hannes Tschofenig 854 requested be applied prior to forwarding the specification to the 855 IESG. 857 o Added rationale for the choice of the b64token syntax. 859 o Added rationale stating that receivers are free to parse the 860 "scope" attribute using a standard quoted-string parser, since it 861 will correctly process all legal "scope" values. 863 o Added additional active working group contributors to the 864 Acknowledgements section. 866 -11 868 o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. 870 -10 872 o Removed the #auth-param option from Authorization header syntax 873 (leaving only the b64token syntax). 875 o Restricted the "scope" value character set to %x21 / %x23-5B / 876 %x5D-7E (printable ASCII characters excluding double-quote and 877 backslash). Indicated that scope is intended for programmatic use 878 and is not meant to be displayed to end users. 880 o Restricted the character set for "error_description" strings to SP 881 / VCHAR and indicated that they are not meant to be displayed to 882 end users. 884 o Included more description in the Abstract, since Hannes Tschofenig 885 indicated that the RFC editor would require this. 887 o Changed "Access Grant" to "Authorization Grant", as was done in 888 the core spec. 890 o Simplified the introduction to the Authenticated Requests section. 892 -09 894 o Incorporated working group last call comments. Specific changes 895 were: 897 o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than 898 [RFC2617]. 900 o Update credentials definition to conform to 901 [I-D.ietf-httpbis-p7-auth]. 903 o Further clarified that query parameters may occur in any order. 905 o Specify that error_description is UTF-8 encoded (matching the core 906 specification). 908 o Registered "Bearer" Authentication Scheme in Authentication Scheme 909 Registry defined by [I-D.ietf-httpbis-p7-auth]. 911 o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- 912 p7-auth drafts. 914 o Other wording improvements not introducing normative changes. 916 -08 918 o Updated references to oauth-v2 and HTTPbis drafts. 920 -07 922 o Added missing comma in error response example. 924 -06 926 o Changed parameter name "bearer_token" to "access_token", per 927 working group consensus. 929 o Changed HTTP status code for "invalid_request" error code from 930 HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input 931 from HTTP working group experts. 933 -05 935 o Removed OAuth Errors Registry, per design team input. 937 o Changed HTTP status code for "invalid_request" error code from 938 HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP 939 usage [[ change pending working group consensus ]]. 941 o Added missing quotation marks in error-uri definition. 943 o Added note to add language and encoding information to 944 error_description if the core specification does. 946 o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined 947 in [RFC5234]. 949 o Use auth-param instead of repeating its definition, which is ( 950 token "=" ( token / quoted-string ) ). 952 o Clarify security considerations about including an audience 953 restriction in the token and include a recommendation to issue 954 scoped bearer tokens in the summary of recommendations. 956 -04 957 o Edits responding to working group last call feedback on -03. 958 Specific edits enumerated below. 960 o Added Bearer Token definition in Terminology section. 962 o Changed parameter name "oauth_token" to "bearer_token". 964 o Added realm parameter to "WWW-Authenticate" response to comply 965 with [RFC2617]. 967 o Removed "[ RWS 1#auth-param ]" from "credentials" definition since 968 it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. 970 o Removed restriction that the "bearer_token" (formerly 971 "oauth_token") parameter be the last parameter in the entity-body 972 and the HTTP request URI query. 974 o Do not require WWW-Authenticate Response in a reply to a malformed 975 request, as an HTTP 400 Bad Request response without a WWW- 976 Authenticate header is likely the right response in some cases of 977 malformed requests. 979 o Removed OAuth Parameters registry extension. 981 o Numerous editorial improvements suggested by working group 982 members. 984 -03 986 o Restored the WWW-Authenticate response header functionality 987 deleted from the framework specification in draft 12 based upon 988 the specification text from draft 11. 990 o Augmented the OAuth Parameters registry by adding two additional 991 parameter usage locations: "resource request" and "resource 992 response". 994 o Registered the "oauth_token" OAuth parameter with usage location 995 "resource request". 997 o Registered the "error" OAuth parameter. 999 o Created the OAuth Error registry and registered errors. 1001 o Changed the "OAuth2" OAuth access token type name to "Bearer". 1003 -02 1004 o Incorporated feedback received on draft 01. Most changes were to 1005 the security considerations section. No normative changes were 1006 made. Specific changes included: 1008 o Changed terminology from "token reuse" to "token capture and 1009 replay". 1011 o Removed sentence "Encrypting the token contents is another 1012 alternative" from the security considerations since it was 1013 redundant and potentially confusing. 1015 o Corrected some references to "resource server" to be 1016 "authorization server" in the security considerations. 1018 o Generalized security considerations language about obtaining 1019 consent of the resource owner. 1021 o Broadened scope of security considerations description for 1022 recommendation "Don't pass bearer tokens in page URLs". 1024 o Removed unused reference to OAuth 1.0. 1026 o Updated reference to framework specification and updated David 1027 Recordon's e-mail address. 1029 o Removed security considerations text on authenticating clients. 1031 o Registered the "OAuth2" OAuth access token type and "oauth_token" 1032 parameter. 1034 -01 1036 o First public draft, which incorporates feedback received on -00 1037 including enhanced Security Considerations content. This version 1038 is intended to accompany OAuth 2.0 draft 11. 1040 -00 1042 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 1044 Authors' Addresses 1046 Michael B. Jones 1047 Microsoft 1049 Email: mbj@microsoft.com 1050 URI: http://self-issued.info/ 1052 Dick Hardt 1053 independent 1055 Email: dick.hardt@gmail.com 1056 URI: http://dickhardt.org/ 1058 David Recordon 1059 Facebook 1061 Email: dr@fb.com 1062 URI: http://www.davidrecordon.com/