idnits 2.17.1 draft-ietf-oauth-v2-bearer-22.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 use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (July 12, 2012) is 4304 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) == Missing Reference: 'I-D.ietf-httpbis-p7-auth' is mentioned on line 1065, but not defined == Missing Reference: 'I-D.ietf-httpbis-p1-messaging' is mentioned on line 928, but not defined == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-29 ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' Summary: 5 errors (**), 0 flaws (~~), 5 warnings (==), 2 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: January 13, 2013 independent 6 D. Recordon 7 Facebook 8 July 12, 2012 10 The OAuth 2.0 Authorization Framework: Bearer Token Usage 11 draft-ietf-oauth-v2-bearer-22 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 January 13, 2013. 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 . . . . . . . . . . 8 65 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 9 66 4. Example Access Token Response . . . . . . . . . . . . . . . . 10 67 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 68 5.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 11 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. OAuth Extensions Error Registration . . . . . . . . . . . 14 75 6.2.1. The "invalid_request" Error Value . . . . . . . . . . 15 76 6.2.2. The "invalid_token" Error Value . . . . . . . . . . . 15 77 6.2.3. The "insufficient_scope" Error Value . . . . . . . . . 15 78 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 79 7.1. Normative References . . . . . . . . . . . . . . . . . . . 16 80 7.2. Informative References . . . . . . . . . . . . . . . . . . 17 81 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 82 Appendix B. Document History . . . . . . . . . . . . . . . . . . 18 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 85 1. Introduction 87 OAuth enables clients to access protected resources by obtaining an 88 access token, which is defined in OAuth 2.0 Authorization 89 [I-D.ietf-oauth-v2] as "a string representing an access authorization 90 issued to the client", rather than using the resource owner's 91 credentials directly. 93 Tokens are issued to clients by an authorization server with the 94 approval of the resource owner. The client uses the access token to 95 access the protected resources hosted by the resource server. This 96 specification describes how to make protected resource requests when 97 the OAuth access token is a bearer token. 99 This specification defines the use of bearer tokens over HTTP/1.1 100 [RFC2616] using TLS [RFC5246] to access protected resources. TLS is 101 mandatory to implement and use with this specification; other 102 specifications may extend this specification for use with other 103 protocols. While designed for use with access tokens resulting from 104 OAuth 2.0 Authorization [I-D.ietf-oauth-v2] flows to access OAuth 105 protected resources, this specification actually defines a general 106 HTTP authorization method that can be used with bearer tokens from 107 any source to access any resources protected by those bearer tokens. 108 The Bearer authentication scheme is intended primarily for server 109 authentication using the WWW-Authenticate and Authorization HTTP 110 headers, but does not preclude its use for proxy authentication. 112 1.1. Notational Conventions 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in Key words for use in 117 RFCs to Indicate Requirement Levels [RFC2119]. 119 This document uses the Augmented Backus-Naur Form (ABNF) notation of 120 [RFC5234]. Additionally, the following rules are included from 121 HTTP/1.1 [RFC2617]: auth-param and auth-scheme; and from Uniform 122 Resource Identifier (URI) [RFC3986]: 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 | | +---------------+ 166 | |--(C)-- Authorization Grant -->| 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 OAuth 2.0 flow illustrated in Figure 1 describes the 180 interaction between the four roles. The following steps are 181 specified within this document: 183 E) The client requests the protected resource from the resource 184 server and authenticates 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 [RFC2617], the client uses the "Bearer" 202 authentication scheme to transmit the access token. 204 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 [RFC2617] as follows: 213 b64token = 1*( ALPHA / DIGIT / 214 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 215 credentials = "Bearer" 1*SP b64token 217 Clients SHOULD make authenticated requests with a bearer token using 218 the "Authorization" request header field with the "Bearer" HTTP 219 authorization scheme. Resource servers MUST support this method. 221 2.2. Form-Encoded Body Parameter 223 When sending the access token in the HTTP request entity-body, the 224 client adds the access token to the request body using the 225 "access_token" parameter. The client MUST NOT use this method unless 226 all of the following conditions are met: 228 o The HTTP request entity-header includes the "Content-Type" header 229 field set to "application/x-www-form-urlencoded". 231 o The entity-body follows the encoding requirements of the 232 "application/x-www-form-urlencoded" content-type as defined by 233 HTML 4.01 [W3C.REC-html401-19991224]. 235 o The HTTP request entity-body is single-part. 237 o The content to be encoded in the entity-body MUST consist entirely 238 of ASCII [USASCII] characters. 240 o The HTTP request method is one for which the request body has 241 defined semantics. In particular, this means that the "GET" 242 method MUST NOT be used. 244 The entity-body MAY include other request-specific parameters, in 245 which case, the "access_token" parameter MUST be properly separated 246 from the request-specific parameters using "&" character(s) (ASCII 247 code 38). 249 For example, the client makes the following HTTP request using 250 transport-layer security: 252 POST /resource HTTP/1.1 253 Host: server.example.com 254 Content-Type: application/x-www-form-urlencoded 256 access_token=mF_9.B5f-4.1JqM 258 The "application/x-www-form-urlencoded" method SHOULD NOT be used 259 except in application contexts where participating browsers do not 260 have access to the "Authorization" request header field. Resource 261 servers MAY support this method. 263 2.3. URI Query Parameter 265 When sending the access token in the HTTP request URI, the client 266 adds the access token to the request URI query component as defined 267 by Uniform Resource Identifier (URI) [RFC3986] using the 268 "access_token" parameter. 270 For example, the client makes the following HTTP request using 271 transport-layer security: 273 GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1 274 Host: server.example.com 276 The HTTP request URI query can include other request-specific 277 parameters, in which case, the "access_token" parameter MUST be 278 properly separated from the request-specific parameters using "&" 279 character(s) (ASCII code 38). 281 For example: 283 https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q 285 Clients using the URI Query Parameter method SHOULD also send a 286 Cache-Control header containing the "no-store" option. Server 287 success (2XX status) responses to these requests SHOULD contain a 288 Cache-Control header with the "private" option. 290 Because of the security weaknesses associated with the URI method 291 (see Section 5), including the high likelihood that the URL 292 containing the access token will be logged, it SHOULD NOT be used 293 unless it is impossible to transport the access token in the 294 "Authorization" request header field or the HTTP request entity-body. 295 Resource servers MAY support this method. 297 This method is included to document current use; its use is not 298 recommended, both due to its security deficiencies (see Section 5) 299 and because it uses a reserved query parameter name, which is counter 300 to URI namespace best practices, per the Architecture of the World 301 Wide Web [W3C.REC-webarch-20041215]. 303 3. The WWW-Authenticate Response Header Field 305 If the protected resource request does not include authentication 306 credentials or does not contain an access token that enables access 307 to the protected resource, the resource server MUST include the HTTP 308 "WWW-Authenticate" response header field; it MAY include it in 309 response to other conditions as well. The "WWW-Authenticate" header 310 field uses the framework defined by HTTP/1.1 [RFC2617]. 312 All challenges defined by this specification MUST use the auth-scheme 313 value "Bearer". This scheme MUST be followed by one or more auth- 314 param values. The auth-param attributes used or defined by this 315 specification are as follows. Other auth-param attributes MAY be 316 used as well. 318 A "realm" attribute MAY be included to indicate the scope of 319 protection in the manner described in HTTP/1.1 [RFC2617]. The 320 "realm" attribute MUST NOT appear more than once. 322 The "scope" attribute is defined in Section 3.3 of OAuth 2.0 323 Authorization [I-D.ietf-oauth-v2]. The "scope" attribute is a space- 324 delimited list of case sensitive scope values indicating the required 325 scope of the access token for accessing the requested resource. 326 "scope" values are implementation defined; there is no centralized 327 registry for them; allowed values are defined by the authorization 328 server. The order of "scope" values is not significant. In some 329 cases, the "scope" value will be used when requesting a new access 330 token with sufficient scope of access to utilize the protected 331 resource. Use of the "scope" attribute is OPTIONAL. The "scope" 332 attribute MUST NOT appear more than once. The "scope" value is 333 intended for programmatic use and is not meant to be displayed to end 334 users. 336 Two example scope values follow; these are taken from the OpenID 337 Connect [OpenID.Messages] and OATC Online Multimedia Authorization 338 Protocol [OMAP] OAuth 2.0 use cases, respectively: 340 scope="openid profile email" 341 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 343 If the protected resource request included an access token and failed 344 authentication, the resource server SHOULD include the "error" 345 attribute to provide the client with the reason why the access 346 request was declined. The parameter value is described in 347 Section 3.1. In addition, the resource server MAY include the 348 "error_description" attribute to provide developers a human-readable 349 explanation that is not meant to be displayed to end users. It also 350 MAY include the "error_uri" attribute with an absolute URI 351 identifying a human-readable web page explaining the error. The 352 "error", "error_description", and "error_uri" attributes MUST NOT 353 appear more than once. 355 Values for the "scope" attribute MUST NOT include characters outside 356 the set %x21 / %x23-5B / %x5D-7E specified in Section A.4 of OAuth 357 2.0 Authorization [I-D.ietf-oauth-v2] for representing scope values 358 and %x20 for delimiters between scope values. Values for the "error" 359 and "error_description" attributes MUST NOT include characters 360 outside the set %x20-21 / %x23-5B / %x5D-7E specified in Sections A.7 361 and A.8 of OAuth 2.0 Authorization. Values for the "error_uri" 362 attribute MUST conform to the URI-Reference syntax, and thus MUST NOT 363 include characters outside the set %x21 / %x23-5B / %x5D-7E specified 364 in Section A.9 of OAuth 2.0 Authorization. 366 For example, in response to a protected resource request without 367 authentication: 369 HTTP/1.1 401 Unauthorized 370 WWW-Authenticate: Bearer realm="example" 372 And in response to a protected resource request with an 373 authentication attempt using an expired access token: 375 HTTP/1.1 401 Unauthorized 376 WWW-Authenticate: Bearer realm="example", 377 error="invalid_token", 378 error_description="The access token expired" 380 3.1. Error Codes 382 When a request fails, the resource server responds using the 383 appropriate HTTP status code (typically, 400, 401, 403, or 405), and 384 includes one of the following error codes in the response: 386 invalid_request 387 The request is missing a required parameter, includes an 388 unsupported parameter or parameter value, repeats the same 389 parameter, uses more than one method for including an access 390 token, or is otherwise malformed. The resource server SHOULD 391 respond with the HTTP 400 (Bad Request) status code. 393 invalid_token 394 The access token provided is expired, revoked, malformed, or 395 invalid for other reasons. The resource SHOULD respond with 396 the HTTP 401 (Unauthorized) status code. The client MAY 397 request a new access token and retry the protected resource 398 request. 400 insufficient_scope 401 The request requires higher privileges than provided by the 402 access token. The resource server SHOULD respond with the HTTP 403 403 (Forbidden) status code and MAY include the "scope" 404 attribute with the scope necessary to access the protected 405 resource. 407 If the request lacks any authentication information (e.g., the client 408 was unaware authentication is necessary or attempted using an 409 unsupported authentication method), the resource server SHOULD NOT 410 include an error code or other error information. 412 For example: 414 HTTP/1.1 401 Unauthorized 415 WWW-Authenticate: Bearer realm="example" 417 4. Example Access Token Response 419 Typically a bearer token is returned to the client as part of an 420 OAuth 2.0 [I-D.ietf-oauth-v2] access token response. An example of 421 such a response is: 423 HTTP/1.1 200 OK 424 Content-Type: application/json;charset=UTF-8 425 Cache-Control: no-store 426 Pragma: no-cache 428 { 429 "access_token":"mF_9.B5f-4.1JqM", 430 "token_type":"Bearer", 431 "expires_in":3600, 432 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" 433 } 435 5. Security Considerations 437 This section describes the relevant security threats regarding token 438 handling when using bearer tokens and describes how to mitigate these 439 threats. 441 5.1. Security Threats 443 The following list presents several common threats against protocols 444 utilizing some form of tokens. This list of threats is based on NIST 445 Special Publication 800-63 [NIST800-63]. Since this document builds 446 on the OAuth 2.0 Authorization specification, we exclude a discussion 447 of threats that are described there or in related documents. 449 Token manufacture/modification: An attacker may generate a bogus 450 token or modify the token contents (such as the authentication or 451 attribute statements) of an existing token, causing the resource 452 server to grant inappropriate access to the client. For example, 453 an attacker may modify the token to extend the validity period; a 454 malicious client may modify the assertion to gain access to 455 information that they should not be able to view. 457 Token disclosure: Tokens may contain authentication and attribute 458 statements that include sensitive information. 460 Token redirect: An attacker uses a token generated for consumption 461 by one resource server to gain access to a different resource 462 server that mistakenly believes the token to be for it. 464 Token replay: An attacker attempts to use a token that has already 465 been used with that resource server in the past. 467 5.2. Threat Mitigation 469 A large range of threats can be mitigated by protecting the contents 470 of the token by using a digital signature or a Message Authentication 471 Code (MAC). Alternatively, a bearer token can contain a reference to 472 authorization information, rather than encoding the information 473 directly. Such references MUST be infeasible for an attacker to 474 guess; using a reference may require an extra interaction between a 475 server and the token issuer to resolve the reference to the 476 authorization information. The mechanics of such an interaction are 477 not defined by this specification. 479 This document does not specify the encoding or the contents of the 480 token; hence detailed recommendations about the means of guaranteeing 481 token integrity protection are outside the scope of this document. 482 The token integrity protection MUST be sufficient to prevent the 483 token from being modified. 485 To deal with token redirect, it is important for the authorization 486 server to include the identity of the intended recipients (the 487 audience), typically a single resource server (or a list of resource 488 servers), in the token. Restricting the use of the token to a 489 specific scope is also RECOMMENDED. 491 The authorization server MUST implement TLS. Which version(s) ought 492 to be implemented will vary over time, and depend on the widespread 493 deployment and known security vulnerabilities at the time of 494 implementation. At the time of this writing, TLS version 1.2 495 [RFC5246] is the most recent version, but has very limited actual 496 deployment, and might not be readily available in implementation 497 toolkits. TLS version 1.0 [RFC2246] is the most widely deployed 498 version, and will give the broadest interoperability. 500 To protect against token disclosure, confidentiality protection MUST 501 be applied using TLS [RFC5246] with a ciphersuite that provides 502 confidentiality and integrity protection. This requires that the 503 communication interaction between the client and the authorization 504 server, as well as the interaction between the client and the 505 resource server, utilize confidentiality and integrity protection. 506 Since TLS is mandatory to implement and to use with this 507 specification, it is the preferred approach for preventing token 508 disclosure via the communication channel. For those cases where the 509 client is prevented from observing the contents of the token, token 510 encryption MUST be applied in addition to the usage of TLS 511 protection. As a further defense against token disclosure, the 512 client MUST validate the TLS certificate chain when making requests 513 to protected resources, including checking the Certificate Revocation 514 List (CRL) [RFC5280]. 516 Cookies are typically transmitted in the clear. Thus, any 517 information contained in them is at risk of disclosure. Therefore, 518 bearer tokens MUST NOT be stored in cookies that can be sent in the 519 clear. See HTTP State Management Mechanism [RFC6265] for security 520 considerations about cookies. 522 In some deployments, including those utilizing load balancers, the 523 TLS connection to the resource server terminates prior to the actual 524 server that provides the resource. This could leave the token 525 unprotected between the front end server where the TLS connection 526 terminates and the back end server that provides the resource. In 527 such deployments, sufficient measures MUST be employed to ensure 528 confidentiality of the token between the front end and back end 529 servers; encryption of the token is one possible such measure. 531 To deal with token capture and replay, the following recommendations 532 are made: First, the lifetime of the token MUST be limited; one means 533 of achieving this is by putting a validity time field inside the 534 protected part of the token. Note that using short-lived (one hour 535 or less) tokens reduces the impact of them being leaked. Second, 536 confidentiality protection of the exchanges between the client and 537 the authorization server and between the client and the resource 538 server MUST be applied. As a consequence, no eavesdropper along the 539 communication path is able to observe the token exchange. 540 Consequently, such an on-path adversary cannot replay the token. 541 Furthermore, when presenting the token to a resource server, the 542 client MUST verify the identity of that resource server, as per 543 Section 3.1 of HTTP Over TLS [RFC2818]. Note that the client MUST 544 validate the TLS certificate chain when making these requests to 545 protected resources. Presenting the token to an unauthenticated and 546 unauthorized resource server or failing to validate the certificate 547 chain will allow adversaries to steal the token and gain unauthorized 548 access to protected resources. 550 5.3. Summary of Recommendations 552 Safeguard bearer tokens: Client implementations MUST ensure that 553 bearer tokens are not leaked to unintended parties, as they will 554 be able to use them to gain access to protected resources. This 555 is the primary security consideration when using bearer tokens and 556 underlies all the more specific recommendations that follow. 558 Validate TLS certificate chains: The client MUST validate the TLS 559 certificate chain when making requests to protected resources. 560 Failing to do so may enable DNS hijacking attacks to steal the 561 token and gain unintended access. 563 Always use TLS (https): Clients MUST always use TLS [RFC5246] 564 (https) or equivalent transport security when making requests with 565 bearer tokens. Failing to do so exposes the token to numerous 566 attacks that could give attackers unintended access. 568 Don't store bearer tokens in cookies: Implementations MUST NOT store 569 bearer tokens within cookies that can be sent in the clear (which 570 is the default transmission mode for cookies). Implementations 571 that do store bearer tokens in cookies MUST take precautions 572 against cross site request forgery. 574 Issue short-lived bearer tokens: Token servers SHOULD issue short- 575 lived (one hour or less) bearer tokens, particularly when issuing 576 tokens to clients that run within a web browser or other 577 environments where information leakage may occur. Using short- 578 lived bearer tokens can reduce the impact of them being leaked. 580 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 581 that contain an audience restriction, scoping their use to the 582 intended relying party or set of relying parties. 584 Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be 585 passed in page URLs (for example as query string parameters). 586 Instead, bearer tokens SHOULD be passed in HTTP message headers or 587 message bodies for which confidentiality measures are taken. 588 Browsers, web servers, and other software may not adequately 589 secure URLs in the browser history, web server logs, and other 590 data structures. If bearer tokens are passed in page URLs, 591 attackers might be able to steal them from the history data, logs, 592 or other unsecured locations. 594 6. IANA Considerations 596 6.1. OAuth Access Token Type Registration 598 This specification registers the following access token type in the 599 OAuth Access Token Type Registry defined in OAuth 2.0 Authorization 600 [I-D.ietf-oauth-v2]. 602 6.1.1. The "Bearer" OAuth Access Token Type 604 Type name: 605 Bearer 607 Additional Token Endpoint Response Parameters: 608 (none) 610 HTTP Authentication Scheme(s): 611 Bearer 613 Change controller: 614 IETF 616 Specification document(s): 617 [[ this document ]] 619 6.2. OAuth Extensions Error Registration 621 This specification registers the following error values in the OAuth 622 Extensions Error Registry defined in OAuth 2.0 Authorization 623 [I-D.ietf-oauth-v2]. 625 6.2.1. The "invalid_request" Error Value 627 Error name: 628 invalid_request 630 Error usage location: 631 Resource access error response 633 Related protocol extension: 634 Bearer access token type 636 Change controller: 637 IETF 639 Specification document(s): 640 [[ this document ]] 642 6.2.2. The "invalid_token" Error Value 644 Error name: 645 invalid_token 647 Error usage location: 648 Resource access error response 650 Related protocol extension: 651 Bearer access token type 653 Change controller: 654 IETF 656 Specification document(s): 657 [[ this document ]] 659 6.2.3. The "insufficient_scope" Error Value 661 Error name: 662 insufficient_scope 664 Error usage location: 665 Resource access error response 667 Related protocol extension: 668 Bearer access token type 670 Change controller: 671 IETF 673 Specification document(s): 674 [[ this document ]] 676 7. References 678 7.1. Normative References 680 [I-D.ietf-oauth-v2] 681 Hardt, D. and D. Recordon, "The OAuth 2.0 Authorization 682 Framework", draft-ietf-oauth-v2-29 (work in progress), 683 July 2012. 685 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 686 Requirement Levels", BCP 14, RFC 2119, March 1997. 688 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 689 RFC 2246, January 1999. 691 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 692 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 693 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 695 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 696 Leach, P., Luotonen, A., and L. Stewart, "HTTP 697 Authentication: Basic and Digest Access Authentication", 698 RFC 2617, June 1999. 700 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 702 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 703 Resource Identifier (URI): Generic Syntax", STD 66, 704 RFC 3986, January 2005. 706 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 707 Specifications: ABNF", STD 68, RFC 5234, January 2008. 709 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 710 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 712 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 713 Housley, R., and W. Polk, "Internet X.509 Public Key 714 Infrastructure Certificate and Certificate Revocation List 715 (CRL) Profile", RFC 5280, May 2008. 717 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 718 April 2011. 720 [USASCII] American National Standards Institute, "Coded Character 721 Set -- 7-bit American Standard Code for Information 722 Interchange", ANSI X3.4, 1986. 724 [W3C.REC-html401-19991224] 725 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 726 Specification", World Wide Web Consortium 727 Recommendation REC-html401-19991224, December 1999, 728 . 730 [W3C.REC-webarch-20041215] 731 Jacobs, I. and N. Walsh, "Architecture of the World Wide 732 Web, Volume One", World Wide Web Consortium 733 Recommendation REC-webarch-20041215, December 2004, 734 . 736 7.2. Informative References 738 [NIST800-63] 739 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 740 and E. Nabbus, "NIST Special Publication 800-63-1, 741 INFORMATION SECURITY", December 2008. 743 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 744 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 745 and B. Boyer, "Online Multimedia Authorization Protocol: 746 An Industry Standard for Authorized Access to Internet 747 Multimedia Resources", April 2012. 749 [OpenID.Messages] 750 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 751 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 752 June 2012. 754 Appendix A. Acknowledgements 756 The following people contributed to preliminary versions of this 757 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland 758 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 759 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 760 concepts within are a product of the OAuth community, the WRAP 761 community, and the OAuth Working Group. 763 The OAuth Working Group has dozens of very active contributors who 764 proposed ideas and wording for this document, including: Michael 765 Adams, Amanda Anganes, Andrew Arnott, Derek Atkins, Dirk Balfanz, 766 John Bradley, Brian Campbell, Francisco Corella, Leah Culver, Bill de 767 hOra, Breno de Medeiros, Brian Ellin, Stephen Farrell, Igor Faynberg, 768 George Fletcher, Tim Freeman, Evan Gilbert, Yaron Y. Goland, Thomas 769 Hardjono, Justin Hart, Phil Hunt, John Kemp, Eran Hammer, Chasen Le 770 Hara, Dick Hardt, Barry Leiba, Amos Jeffries, Michael B. Jones, 771 Torsten Lodderstedt, Paul Madsen, Eve Maler, James Manger, Laurence 772 Miao, William J. Mills, Chuck Mortimore, Anthony Nadalin, Axel 773 Nennker, Mark Nottingham, David Recordon, Julian Reschke, Rob 774 Richards, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, 775 Marius Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian 776 Stuebner, Doug Tangren, Paul Tarjan, Hannes Tschofenig, Franklin Tse, 777 Sean Turner, Paul Walker, Shane Weeden, Skylar Woodward, and Zachary 778 Zeltsan. 780 Appendix B. Document History 782 [[ to be removed by the RFC editor before publication as an RFC ]] 784 -22 786 o Removed uses of HTTPbis in favor of RFC 2616 and RFC 2617, since 787 HTTPbis is not an approved standard. 789 o Match formatting of artwork elements with OAuth core 790 specification. 792 -21 794 o Changed "NOT RECOMMENDED" to "not recommended" in caveat about the 795 URI Query Parameter method. 797 o Changed "other specifications may extend this specification for 798 use with other transport protocols" to "other specifications may 799 extend this specification for use with other protocols". 801 o Changed Acknowledgements to use only ASCII characters, per the RFC 802 style guide. 804 -20 806 o Added caveat about using a reserved query parameter name being 807 counter to URI namespace best practices. 809 o Specified use of Cache-Control options when using the URI Query 810 Parameter method. 812 o Changed title to "The OAuth 2.0 Authorization Framework: Bearer 813 Token Usage". 815 o Referenced syntax definitions for the "scope", "error", 816 "error_description", and "error_uri" parameters in the OAuth 2.0 817 core spec. 819 o Registered the "invalid_request", "invalid_token", and 820 "insufficient_scope" error values in the OAuth Extensions Error 821 Registry. 823 o Acknowledged additional individuals. 825 -19 827 o Addressed DISCUSS issues and comments raised for which resolutions 828 have been agreed to. No normative changes were made. Changes 829 made were: 831 o Use ABNF from RFC 5234. 833 o Added sentence "The Bearer authentication scheme is intended 834 primarily for server authentication using the WWW-Authenticate and 835 Authorization HTTP headers, but does not preclude its use for 836 proxy authentication" to the introduction. 838 o In the introduction, state that this document also imposes 839 semantic requirements upon the access token. 841 o Reference the "scope" definition in the OAuth core spec. 843 o Added "scope" examples. 845 o Reference RFC 6265 for security considerations about cookies. 847 -18 849 o Changed example bearer token value from vF9dft4qmT to mF_9.B5f- 850 4.1JqM. 852 o Added example access token response returning a Bearer token. 854 -17 856 o Restore RFC 2818 reference for server identity verification and 857 add RFC 5280 reference for certificate revocation lists, per Gen- 858 ART review comments. 860 -16 862 o Use the HTTPbis auth-param syntax for Bearer challenge attributes. 864 o Dropped the sentence "The "realm" value is intended for 865 programmatic use and is not meant to be displayed to end users". 867 o Reordered form-encoded body parameter description bullets for 868 better readability. 870 o Added [USASCII] reference. 872 -15 874 o Clarified that form-encoded content must consist entirely of ASCII 875 characters. 877 o Added TLS version requirements. 879 o Applied editorial improvements suggested by Mark Nottingham during 880 the APPS area review. 882 -14 884 o Changes made in response to review comments by Security Area 885 Director Stephen Farrell. Specifically: 887 o Strengthened warnings about passing an access token as a query 888 parameter and more precisely described the limitations placed upon 889 the use of this method. 891 o Clarified that the "realm" attribute MAY included to indicate the 892 scope of protection in the manner described in HTTP/1.1, Part 7 893 [I-D.ietf-httpbis-p7-auth]. 895 o Normatively stated that "the token integrity protection MUST be 896 sufficient to prevent the token from being modified". 898 o Added statement that "TLS is mandatory to implement and use with 899 this specification" to the introduction. 901 o Stated that TLS MUST be used with "a ciphersuite that provides 902 confidentiality and integrity protection". 904 o Added "As a further defense against token disclosure, the client 905 MUST validate the TLS certificate chain when making requests to 906 protected resources" to the Threat Mitigation section. 908 o Clarified that putting a validity time field inside the protected 909 part of the token is one means, but not the only means, of 910 limiting the lifetime of the token. 912 o Dropped the confusing phrase "for instance, through the use of 913 TLS" from the sentence about confidentiality protection of the 914 exchanges. 916 o Reference RFC 6125 for identity verification, rather than RFC 917 2818. 919 o Stated that the token MUST be protected between front end and back 920 end servers when the TLS connection terminates at a front end 921 server that is distinct from the actual server that provides the 922 resource. 924 o Stated that bearer tokens MUST NOT be stored in cookies that can 925 be sent in the clear in the Threat Mitigation section. 927 o Replaced sole remaining reference to [RFC2616] with HTTPbis 928 [I-D.ietf-httpbis-p1-messaging] reference. 930 o Replaced all references where the reference is used as if it were 931 part of the sentence (such as "defined by [I-D.whatever]") with 932 ones where the specification name is used, followed by the 933 reference (such as "defined by Whatever [I-D.whatever]"). 935 o Other on-normative editorial improvements. 937 -13 939 o At the request of Hannes Tschofenig, made ABNF changes to make it 940 clear that no special WWW-Authenticate response header field 941 parsers are needed. The "scope", "error-description", and 942 "error-uri" parameters are all now defined as quoted-string in the 943 ABNF (as "error" already was). Restrictions on these values that 944 were formerly described in the ABNFs are now described in 945 normative text instead. 947 -12 949 o Made non-normative editorial changes that Hannes Tschofenig 950 requested be applied prior to forwarding the specification to the 951 IESG. 953 o Added rationale for the choice of the b64token syntax. 955 o Added rationale stating that receivers are free to parse the 956 "scope" attribute using a standard quoted-string parser, since it 957 will correctly process all legal "scope" values. 959 o Added additional active working group contributors to the 960 Acknowledgements section. 962 -11 964 o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. 966 -10 968 o Removed the #auth-param option from Authorization header syntax 969 (leaving only the b64token syntax). 971 o Restricted the "scope" value character set to %x21 / %x23-5B / 972 %x5D-7E (printable ASCII characters excluding double-quote and 973 backslash). Indicated that scope is intended for programmatic use 974 and is not meant to be displayed to end users. 976 o Restricted the character set for "error_description" strings to SP 977 / VCHAR and indicated that they are not meant to be displayed to 978 end users. 980 o Included more description in the Abstract, since Hannes Tschofenig 981 indicated that the RFC editor would require this. 983 o Changed "Access Grant" to "Authorization Grant", as was done in 984 the core spec. 986 o Simplified the introduction to the Authenticated Requests section. 988 -09 990 o Incorporated working group last call comments. Specific changes 991 were: 993 o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than 994 [RFC2617]. 996 o Update credentials definition to conform to [I-D.ietf-httpbis-p7- 997 auth]. 999 o Further clarified that query parameters may occur in any order. 1001 o Specify that error_description is UTF-8 encoded (matching the core 1002 specification). 1004 o Registered "Bearer" Authentication Scheme in Authentication Scheme 1005 Registry defined by [I-D.ietf-httpbis-p7-auth]. 1007 o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- 1008 p7-auth drafts. 1010 o Other wording improvements not introducing normative changes. 1012 -08 1014 o Updated references to oauth-v2 and HTTPbis drafts. 1016 -07 1018 o Added missing comma in error response example. 1020 -06 1022 o Changed parameter name "bearer_token" to "access_token", per 1023 working group consensus. 1025 o Changed HTTP status code for "invalid_request" error code from 1026 HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input 1027 from HTTP working group experts. 1029 -05 1031 o Removed OAuth Errors Registry, per design team input. 1033 o Changed HTTP status code for "invalid_request" error code from 1034 HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP 1035 usage [[ change pending working group consensus ]]. 1037 o Added missing quotation marks in error-uri definition. 1039 o Added note to add language and encoding information to 1040 error_description if the core specification does. 1042 o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined 1043 in [RFC5234]. 1045 o Use auth-param instead of repeating its definition, which is ( 1046 token "=" ( token / quoted-string ) ). 1048 o Clarify security considerations about including an audience 1049 restriction in the token and include a recommendation to issue 1050 scoped bearer tokens in the summary of recommendations. 1052 -04 1054 o Edits responding to working group last call feedback on -03. 1055 Specific edits enumerated below. 1057 o Added Bearer Token definition in Terminology section. 1059 o Changed parameter name "oauth_token" to "bearer_token". 1061 o Added realm parameter to "WWW-Authenticate" response to comply 1062 with [RFC2617]. 1064 o Removed "[ RWS 1#auth-param ]" from "credentials" definition since 1065 it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. 1067 o Removed restriction that the "bearer_token" (formerly 1068 "oauth_token") parameter be the last parameter in the entity-body 1069 and the HTTP request URI query. 1071 o Do not require WWW-Authenticate Response in a reply to a malformed 1072 request, as an HTTP 400 Bad Request response without a WWW- 1073 Authenticate header is likely the right response in some cases of 1074 malformed requests. 1076 o Removed OAuth Parameters registry extension. 1078 o Numerous editorial improvements suggested by working group 1079 members. 1081 -03 1083 o Restored the WWW-Authenticate response header functionality 1084 deleted from the framework specification in draft 12 based upon 1085 the specification text from draft 11. 1087 o Augmented the OAuth Parameters registry by adding two additional 1088 parameter usage locations: "resource request" and "resource 1089 response". 1091 o Registered the "oauth_token" OAuth parameter with usage location 1092 "resource request". 1094 o Registered the "error" OAuth parameter. 1096 o Created the OAuth Error registry and registered errors. 1098 o Changed the "OAuth2" OAuth access token type name to "Bearer". 1100 -02 1102 o Incorporated feedback received on draft 01. Most changes were to 1103 the security considerations section. No normative changes were 1104 made. Specific changes included: 1106 o Changed terminology from "token reuse" to "token capture and 1107 replay". 1109 o Removed sentence "Encrypting the token contents is another 1110 alternative" from the security considerations since it was 1111 redundant and potentially confusing. 1113 o Corrected some references to "resource server" to be 1114 "authorization server" in the security considerations. 1116 o Generalized security considerations language about obtaining 1117 consent of the resource owner. 1119 o Broadened scope of security considerations description for 1120 recommendation "Don't pass bearer tokens in page URLs". 1122 o Removed unused reference to OAuth 1.0. 1124 o Updated reference to framework specification and updated David 1125 Recordon's e-mail address. 1127 o Removed security considerations text on authenticating clients. 1129 o Registered the "OAuth2" OAuth access token type and "oauth_token" 1130 parameter. 1132 -01 1134 o First public draft, which incorporates feedback received on -00 1135 including enhanced Security Considerations content. This version 1136 is intended to accompany OAuth 2.0 draft 11. 1138 -00 1140 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 1142 Authors' Addresses 1144 Michael B. Jones 1145 Microsoft 1147 Email: mbj@microsoft.com 1148 URI: http://self-issued.info/ 1150 Dick Hardt 1151 independent 1153 Email: dick.hardt@gmail.com 1154 URI: http://dickhardt.org/ 1156 David Recordon 1157 Facebook 1159 Email: dr@fb.com 1160 URI: http://www.davidrecordon.com/