idnits 2.17.1 draft-ietf-oauth-v2-bearer-23.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 (August 1, 2012) is 4284 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 1070, but not defined == Missing Reference: 'I-D.ietf-httpbis-p1-messaging' is mentioned on line 934, but not defined ** 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 (~~), 4 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: February 2, 2013 independent 6 August 1, 2012 8 The OAuth 2.0 Authorization Framework: Bearer Token Usage 9 draft-ietf-oauth-v2-bearer-23 11 Abstract 13 This specification describes how to use bearer tokens in HTTP 14 requests to access OAuth 2.0 protected resources. Any party in 15 possession of a bearer token (a "bearer") can use it to get access to 16 the associated resources (without demonstrating possession of a 17 cryptographic key). To prevent misuse, bearer tokens need to be 18 protected from disclosure in storage and in transport. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on February 2, 2013. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 5 59 2.1. Authorization Request Header Field . . . . . . . . . . . . 5 60 2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 6 61 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 7 62 3. The WWW-Authenticate Response Header Field . . . . . . . . . . 8 63 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 9 64 4. Example Access Token Response . . . . . . . . . . . . . . . . 10 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 66 5.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 11 67 5.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 11 68 5.3. Summary of Recommendations . . . . . . . . . . . . . . . . 13 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 70 6.1. OAuth Access Token Type Registration . . . . . . . . . . . 14 71 6.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 14 72 6.2. OAuth Extensions Error Registration . . . . . . . . . . . 14 73 6.2.1. The "invalid_request" Error Value . . . . . . . . . . 15 74 6.2.2. The "invalid_token" Error Value . . . . . . . . . . . 15 75 6.2.3. The "insufficient_scope" Error Value . . . . . . . . . 15 76 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 77 7.1. Normative References . . . . . . . . . . . . . . . . . . . 16 78 7.2. Informative References . . . . . . . . . . . . . . . . . . 17 79 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 17 80 Appendix B. Document History . . . . . . . . . . . . . . . . . . 18 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 26 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 [RFC2616] using TLS [RFC5246] to access protected resources. TLS is 99 mandatory to implement and use with this specification; other 100 specifications may extend this specification for use with other 101 protocols. While designed for use with access tokens resulting from 102 OAuth 2.0 Authorization [I-D.ietf-oauth-v2] flows to access OAuth 103 protected resources, this specification actually defines a general 104 HTTP authorization method that can be used with bearer tokens from 105 any source to access any resources protected by those bearer tokens. 106 The Bearer authentication scheme is intended primarily for server 107 authentication using the WWW-Authenticate and Authorization HTTP 108 headers, but does not preclude its use for proxy authentication. 110 1.1. Notational Conventions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in Key words for use in 115 RFCs to Indicate Requirement Levels [RFC2119]. 117 This document uses the Augmented Backus-Naur Form (ABNF) notation of 118 [RFC5234]. Additionally, the following rules are included from 119 HTTP/1.1 [RFC2617]: auth-param and auth-scheme; and from Uniform 120 Resource Identifier (URI) [RFC3986]: URI-Reference. 122 Unless otherwise noted, all the protocol parameter names and values 123 are case sensitive. 125 1.2. Terminology 126 Bearer Token 127 A security token with the property that any party in possession of 128 the token (a "bearer") can use the token in any way that any other 129 party in possession of it can. Using a bearer token does not 130 require a bearer to prove possession of cryptographic key material 131 (proof-of-possession). 133 All other terms are as defined in OAuth 2.0 Authorization 134 [I-D.ietf-oauth-v2]. 136 1.3. Overview 138 OAuth provides a method for clients to access a protected resource on 139 behalf of a resource owner. In the general case, before a client can 140 access a protected resource, it must first obtain an authorization 141 grant from the resource owner and then exchange the authorization 142 grant for an access token. The access token represents the grant's 143 scope, duration, and other attributes granted by the authorization 144 grant. The client accesses the protected resource by presenting the 145 access token to the resource server. In some cases, a client can 146 directly present its own credentials to an authorization server to 147 obtain an access token without having to first obtain an 148 authorization grant from a resource owner. 150 The access token provides an abstraction, replacing different 151 authorization constructs (e.g., username and password, assertion) for 152 a single token understood by the resource server. This abstraction 153 enables issuing access tokens valid for a short time period, as well 154 as removing the resource server's need to understand a wide range of 155 authentication schemes. 157 +--------+ +---------------+ 158 | |--(A)- Authorization Request ->| Resource | 159 | | | Owner | 160 | |<-(B)-- Authorization Grant ---| | 161 | | +---------------+ 162 | | 163 | | +---------------+ 164 | |--(C)-- Authorization Grant -->| Authorization | 165 | Client | | Server | 166 | |<-(D)----- Access Token -------| | 167 | | +---------------+ 168 | | 169 | | +---------------+ 170 | |--(E)----- Access Token ------>| Resource | 171 | | | Server | 172 | |<-(F)--- Protected Resource ---| | 173 +--------+ +---------------+ 175 Figure 1: Abstract Protocol Flow 177 The abstract OAuth 2.0 flow illustrated in Figure 1 describes the 178 interaction between the four roles. The following steps are 179 specified within this document: 181 E) The client requests the protected resource from the resource 182 server and authenticates by presenting the access token. 184 F) The resource server validates the access token, and if valid, 185 serves the request. 187 This document also imposes semantic requirements upon the access 188 token returned in Step D. 190 2. Authenticated Requests 192 This section defines three methods of sending bearer access tokens in 193 resource requests to resource servers. Clients MUST NOT use more 194 than one method to transmit the token in each request. 196 2.1. Authorization Request Header Field 198 When sending the access token in the "Authorization" request header 199 field defined by HTTP/1.1 [RFC2617], the client uses the "Bearer" 200 authentication scheme to transmit the access token. 202 For example: 204 GET /resource HTTP/1.1 205 Host: server.example.com 206 Authorization: Bearer mF_9.B5f-4.1JqM 208 The "Authorization" header field uses the framework defined by 209 HTTP/1.1 [RFC2617] as follows: 211 b64token = 1*( ALPHA / DIGIT / 212 "-" / "." / "_" / "~" / "+" / "/" ) *"=" 213 credentials = "Bearer" 1*SP b64token 215 Clients SHOULD make authenticated requests with a bearer token using 216 the "Authorization" request header field with the "Bearer" HTTP 217 authorization scheme. Resource servers MUST support this method. 219 2.2. Form-Encoded Body Parameter 221 When sending the access token in the HTTP request entity-body, the 222 client adds the access token to the request body using the 223 "access_token" parameter. The client MUST NOT use this method unless 224 all of the following conditions are met: 226 o The HTTP request entity-header includes the "Content-Type" header 227 field set to "application/x-www-form-urlencoded". 229 o The entity-body follows the encoding requirements of the 230 "application/x-www-form-urlencoded" content-type as defined by 231 HTML 4.01 [W3C.REC-html401-19991224]. 233 o The HTTP request entity-body is single-part. 235 o The content to be encoded in the entity-body MUST consist entirely 236 of ASCII [USASCII] characters. 238 o The HTTP request method is one for which the request body has 239 defined semantics. In particular, this means that the "GET" 240 method MUST NOT be used. 242 The entity-body MAY include other request-specific parameters, in 243 which case, the "access_token" parameter MUST be properly separated 244 from the request-specific parameters using "&" character(s) (ASCII 245 code 38). 247 For example, the client makes the following HTTP request using 248 transport-layer security: 250 POST /resource HTTP/1.1 251 Host: server.example.com 252 Content-Type: application/x-www-form-urlencoded 254 access_token=mF_9.B5f-4.1JqM 256 The "application/x-www-form-urlencoded" method SHOULD NOT be used 257 except in application contexts where participating browsers do not 258 have access to the "Authorization" request header field. Resource 259 servers MAY support this method. 261 2.3. URI Query Parameter 263 When sending the access token in the HTTP request URI, the client 264 adds the access token to the request URI query component as defined 265 by Uniform Resource Identifier (URI) [RFC3986] using the 266 "access_token" parameter. 268 For example, the client makes the following HTTP request using 269 transport-layer security: 271 GET /resource?access_token=mF_9.B5f-4.1JqM HTTP/1.1 272 Host: server.example.com 274 The HTTP request URI query can include other request-specific 275 parameters, in which case, the "access_token" parameter MUST be 276 properly separated from the request-specific parameters using "&" 277 character(s) (ASCII code 38). 279 For example: 281 https://server.example.com/resource?access_token=mF_9.B5f-4.1JqM&p=q 283 Clients using the URI Query Parameter method SHOULD also send a 284 Cache-Control header containing the "no-store" option. Server 285 success (2XX status) responses to these requests SHOULD contain a 286 Cache-Control header with the "private" option. 288 Because of the security weaknesses associated with the URI method 289 (see Section 5), including the high likelihood that the URL 290 containing the access token will be logged, it SHOULD NOT be used 291 unless it is impossible to transport the access token in the 292 "Authorization" request header field or the HTTP request entity-body. 293 Resource servers MAY support this method. 295 This method is included to document current use; its use is not 296 recommended, both due to its security deficiencies (see Section 5) 297 and because it uses a reserved query parameter name, which is counter 298 to URI namespace best practices, per the Architecture of the World 299 Wide Web [W3C.REC-webarch-20041215]. 301 3. The WWW-Authenticate Response Header Field 303 If the protected resource request does not include authentication 304 credentials or does not contain an access token that enables access 305 to the protected resource, the resource server MUST include the HTTP 306 "WWW-Authenticate" response header field; it MAY include it in 307 response to other conditions as well. The "WWW-Authenticate" header 308 field uses the framework defined by HTTP/1.1 [RFC2617]. 310 All challenges defined by this specification MUST use the auth-scheme 311 value "Bearer". This scheme MUST be followed by one or more auth- 312 param values. The auth-param attributes used or defined by this 313 specification are as follows. Other auth-param attributes MAY be 314 used as well. 316 A "realm" attribute MAY be included to indicate the scope of 317 protection in the manner described in HTTP/1.1 [RFC2617]. The 318 "realm" attribute MUST NOT appear more than once. 320 The "scope" attribute is defined in Section 3.3 of OAuth 2.0 321 Authorization [I-D.ietf-oauth-v2]. The "scope" attribute is a space- 322 delimited list of case sensitive scope values indicating the required 323 scope of the access token for accessing the requested resource. 324 "scope" values are implementation defined; there is no centralized 325 registry for them; allowed values are defined by the authorization 326 server. The order of "scope" values is not significant. In some 327 cases, the "scope" value will be used when requesting a new access 328 token with sufficient scope of access to utilize the protected 329 resource. Use of the "scope" attribute is OPTIONAL. The "scope" 330 attribute MUST NOT appear more than once. The "scope" value is 331 intended for programmatic use and is not meant to be displayed to end 332 users. 334 Two example scope values follow; these are taken from the OpenID 335 Connect [OpenID.Messages] and OATC Online Multimedia Authorization 336 Protocol [OMAP] OAuth 2.0 use cases, respectively: 338 scope="openid profile email" 339 scope="urn:example:channel=HBO&urn:example:rating=G,PG-13" 341 If the protected resource request included an access token and failed 342 authentication, the resource server SHOULD include the "error" 343 attribute to provide the client with the reason why the access 344 request was declined. The parameter value is described in 345 Section 3.1. In addition, the resource server MAY include the 346 "error_description" attribute to provide developers a human-readable 347 explanation that is not meant to be displayed to end users. It also 348 MAY include the "error_uri" attribute with an absolute URI 349 identifying a human-readable web page explaining the error. The 350 "error", "error_description", and "error_uri" attributes MUST NOT 351 appear more than once. 353 Values for the "scope" attribute MUST NOT include characters outside 354 the set %x21 / %x23-5B / %x5D-7E specified in Section A.4 of OAuth 355 2.0 Authorization [I-D.ietf-oauth-v2] for representing scope values 356 and %x20 for delimiters between scope values. Values for the "error" 357 and "error_description" attributes MUST NOT include characters 358 outside the set %x20-21 / %x23-5B / %x5D-7E specified in Sections A.7 359 and A.8 of OAuth 2.0 Authorization. Values for the "error_uri" 360 attribute MUST conform to the URI-Reference syntax, and thus MUST NOT 361 include characters outside the set %x21 / %x23-5B / %x5D-7E specified 362 in Section A.9 of OAuth 2.0 Authorization. 364 For example, in response to a protected resource request without 365 authentication: 367 HTTP/1.1 401 Unauthorized 368 WWW-Authenticate: Bearer realm="example" 370 And in response to a protected resource request with an 371 authentication attempt using an expired access token: 373 HTTP/1.1 401 Unauthorized 374 WWW-Authenticate: Bearer realm="example", 375 error="invalid_token", 376 error_description="The access token expired" 378 3.1. Error Codes 380 When a request fails, the resource server responds using the 381 appropriate HTTP status code (typically, 400, 401, 403, or 405), and 382 includes one of the following error codes in the response: 384 invalid_request 385 The request is missing a required parameter, includes an 386 unsupported parameter or parameter value, repeats the same 387 parameter, uses more than one method for including an access 388 token, or is otherwise malformed. The resource server SHOULD 389 respond with the HTTP 400 (Bad Request) status code. 391 invalid_token 392 The access token provided is expired, revoked, malformed, or 393 invalid for other reasons. The resource SHOULD respond with 394 the HTTP 401 (Unauthorized) status code. The client MAY 395 request a new access token and retry the protected resource 396 request. 398 insufficient_scope 399 The request requires higher privileges than provided by the 400 access token. The resource server SHOULD respond with the HTTP 401 403 (Forbidden) status code and MAY include the "scope" 402 attribute with the scope necessary to access the protected 403 resource. 405 If the request lacks any authentication information (e.g., the client 406 was unaware authentication is necessary or attempted using an 407 unsupported authentication method), the resource server SHOULD NOT 408 include an error code or other error information. 410 For example: 412 HTTP/1.1 401 Unauthorized 413 WWW-Authenticate: Bearer realm="example" 415 4. Example Access Token Response 417 Typically a bearer token is returned to the client as part of an 418 OAuth 2.0 [I-D.ietf-oauth-v2] access token response. An example of 419 such a response is: 421 HTTP/1.1 200 OK 422 Content-Type: application/json;charset=UTF-8 423 Cache-Control: no-store 424 Pragma: no-cache 426 { 427 "access_token":"mF_9.B5f-4.1JqM", 428 "token_type":"Bearer", 429 "expires_in":3600, 430 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" 431 } 433 5. Security Considerations 435 This section describes the relevant security threats regarding token 436 handling when using bearer tokens and describes how to mitigate these 437 threats. 439 5.1. Security Threats 441 The following list presents several common threats against protocols 442 utilizing some form of tokens. This list of threats is based on NIST 443 Special Publication 800-63 [NIST800-63]. Since this document builds 444 on the OAuth 2.0 Authorization specification, we exclude a discussion 445 of threats that are described there or in related documents. 447 Token manufacture/modification: An attacker may generate a bogus 448 token or modify the token contents (such as the authentication or 449 attribute statements) of an existing token, causing the resource 450 server to grant inappropriate access to the client. For example, 451 an attacker may modify the token to extend the validity period; a 452 malicious client may modify the assertion to gain access to 453 information that they should not be able to view. 455 Token disclosure: Tokens may contain authentication and attribute 456 statements that include sensitive information. 458 Token redirect: An attacker uses a token generated for consumption 459 by one resource server to gain access to a different resource 460 server that mistakenly believes the token to be for it. 462 Token replay: An attacker attempts to use a token that has already 463 been used with that resource server in the past. 465 5.2. Threat Mitigation 467 A large range of threats can be mitigated by protecting the contents 468 of the token by using a digital signature or a Message Authentication 469 Code (MAC). Alternatively, a bearer token can contain a reference to 470 authorization information, rather than encoding the information 471 directly. Such references MUST be infeasible for an attacker to 472 guess; using a reference may require an extra interaction between a 473 server and the token issuer to resolve the reference to the 474 authorization information. The mechanics of such an interaction are 475 not defined by this specification. 477 This document does not specify the encoding or the contents of the 478 token; hence detailed recommendations about the means of guaranteeing 479 token integrity protection are outside the scope of this document. 480 The token integrity protection MUST be sufficient to prevent the 481 token from being modified. 483 To deal with token redirect, it is important for the authorization 484 server to include the identity of the intended recipients (the 485 audience), typically a single resource server (or a list of resource 486 servers), in the token. Restricting the use of the token to a 487 specific scope is also RECOMMENDED. 489 The authorization server MUST implement TLS. Which version(s) ought 490 to be implemented will vary over time, and depend on the widespread 491 deployment and known security vulnerabilities at the time of 492 implementation. At the time of this writing, TLS version 1.2 493 [RFC5246] is the most recent version, but has very limited actual 494 deployment, and might not be readily available in implementation 495 toolkits. TLS version 1.0 [RFC2246] is the most widely deployed 496 version, and will give the broadest interoperability. 498 To protect against token disclosure, confidentiality protection MUST 499 be applied using TLS [RFC5246] with a ciphersuite that provides 500 confidentiality and integrity protection. This requires that the 501 communication interaction between the client and the authorization 502 server, as well as the interaction between the client and the 503 resource server, utilize confidentiality and integrity protection. 504 Since TLS is mandatory to implement and to use with this 505 specification, it is the preferred approach for preventing token 506 disclosure via the communication channel. For those cases where the 507 client is prevented from observing the contents of the token, token 508 encryption MUST be applied in addition to the usage of TLS 509 protection. As a further defense against token disclosure, the 510 client MUST validate the TLS certificate chain when making requests 511 to protected resources, including checking the Certificate Revocation 512 List (CRL) [RFC5280]. 514 Cookies are typically transmitted in the clear. Thus, any 515 information contained in them is at risk of disclosure. Therefore, 516 bearer tokens MUST NOT be stored in cookies that can be sent in the 517 clear. See HTTP State Management Mechanism [RFC6265] for security 518 considerations about cookies. 520 In some deployments, including those utilizing load balancers, the 521 TLS connection to the resource server terminates prior to the actual 522 server that provides the resource. This could leave the token 523 unprotected between the front end server where the TLS connection 524 terminates and the back end server that provides the resource. In 525 such deployments, sufficient measures MUST be employed to ensure 526 confidentiality of the token between the front end and back end 527 servers; encryption of the token is one possible such measure. 529 To deal with token capture and replay, the following recommendations 530 are made: First, the lifetime of the token MUST be limited; one means 531 of achieving this is by putting a validity time field inside the 532 protected part of the token. Note that using short-lived (one hour 533 or less) tokens reduces the impact of them being leaked. Second, 534 confidentiality protection of the exchanges between the client and 535 the authorization server and between the client and the resource 536 server MUST be applied. As a consequence, no eavesdropper along the 537 communication path is able to observe the token exchange. 538 Consequently, such an on-path adversary cannot replay the token. 539 Furthermore, when presenting the token to a resource server, the 540 client MUST verify the identity of that resource server, as per 541 Section 3.1 of HTTP Over TLS [RFC2818]. Note that the client MUST 542 validate the TLS certificate chain when making these requests to 543 protected resources. Presenting the token to an unauthenticated and 544 unauthorized resource server or failing to validate the certificate 545 chain will allow adversaries to steal the token and gain unauthorized 546 access to protected resources. 548 5.3. Summary of Recommendations 550 Safeguard bearer tokens: Client implementations MUST ensure that 551 bearer tokens are not leaked to unintended parties, as they will 552 be able to use them to gain access to protected resources. This 553 is the primary security consideration when using bearer tokens and 554 underlies all the more specific recommendations that follow. 556 Validate TLS certificate chains: The client MUST validate the TLS 557 certificate chain when making requests to protected resources. 558 Failing to do so may enable DNS hijacking attacks to steal the 559 token and gain unintended access. 561 Always use TLS (https): Clients MUST always use TLS [RFC5246] 562 (https) or equivalent transport security when making requests with 563 bearer tokens. Failing to do so exposes the token to numerous 564 attacks that could give attackers unintended access. 566 Don't store bearer tokens in cookies: Implementations MUST NOT store 567 bearer tokens within cookies that can be sent in the clear (which 568 is the default transmission mode for cookies). Implementations 569 that do store bearer tokens in cookies MUST take precautions 570 against cross site request forgery. 572 Issue short-lived bearer tokens: Token servers SHOULD issue short- 573 lived (one hour or less) bearer tokens, particularly when issuing 574 tokens to clients that run within a web browser or other 575 environments where information leakage may occur. Using short- 576 lived bearer tokens can reduce the impact of them being leaked. 578 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 579 that contain an audience restriction, scoping their use to the 580 intended relying party or set of relying parties. 582 Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be 583 passed in page URLs (for example as query string parameters). 584 Instead, bearer tokens SHOULD be passed in HTTP message headers or 585 message bodies for which confidentiality measures are taken. 586 Browsers, web servers, and other software may not adequately 587 secure URLs in the browser history, web server logs, and other 588 data structures. If bearer tokens are passed in page URLs, 589 attackers might be able to steal them from the history data, logs, 590 or other unsecured locations. 592 6. IANA Considerations 594 6.1. OAuth Access Token Type Registration 596 This specification registers the following access token type in the 597 OAuth Access Token Type Registry defined in OAuth 2.0 Authorization 598 [I-D.ietf-oauth-v2]. 600 6.1.1. The "Bearer" OAuth Access Token Type 602 Type name: 603 Bearer 605 Additional Token Endpoint Response Parameters: 606 (none) 608 HTTP Authentication Scheme(s): 609 Bearer 611 Change controller: 612 IETF 614 Specification document(s): 615 [[ this document ]] 617 6.2. OAuth Extensions Error Registration 619 This specification registers the following error values in the OAuth 620 Extensions Error Registry defined in OAuth 2.0 Authorization 621 [I-D.ietf-oauth-v2]. 623 6.2.1. The "invalid_request" Error Value 625 Error name: 626 invalid_request 628 Error usage location: 629 Resource access error response 631 Related protocol extension: 632 Bearer access token type 634 Change controller: 635 IETF 637 Specification document(s): 638 [[ this document ]] 640 6.2.2. The "invalid_token" Error Value 642 Error name: 643 invalid_token 645 Error usage location: 646 Resource access error response 648 Related protocol extension: 649 Bearer access token type 651 Change controller: 652 IETF 654 Specification document(s): 655 [[ this document ]] 657 6.2.3. The "insufficient_scope" Error Value 659 Error name: 660 insufficient_scope 662 Error usage location: 663 Resource access error response 665 Related protocol extension: 666 Bearer access token type 668 Change controller: 669 IETF 671 Specification document(s): 672 [[ this document ]] 674 7. References 676 7.1. Normative References 678 [I-D.ietf-oauth-v2] 679 Hardt, D., "The OAuth 2.0 Authorization Framework", 680 draft-ietf-oauth-v2-31 (work in progress), July 2012. 682 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 683 Requirement Levels", BCP 14, RFC 2119, March 1997. 685 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 686 RFC 2246, January 1999. 688 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 689 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 690 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 692 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 693 Leach, P., Luotonen, A., and L. Stewart, "HTTP 694 Authentication: Basic and Digest Access Authentication", 695 RFC 2617, June 1999. 697 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 699 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 700 Resource Identifier (URI): Generic Syntax", STD 66, 701 RFC 3986, January 2005. 703 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 704 Specifications: ABNF", STD 68, RFC 5234, January 2008. 706 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 707 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 709 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 710 Housley, R., and W. Polk, "Internet X.509 Public Key 711 Infrastructure Certificate and Certificate Revocation List 712 (CRL) Profile", RFC 5280, May 2008. 714 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 715 April 2011. 717 [USASCII] American National Standards Institute, "Coded Character 718 Set -- 7-bit American Standard Code for Information 719 Interchange", ANSI X3.4, 1986. 721 [W3C.REC-html401-19991224] 722 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 723 Specification", World Wide Web Consortium 724 Recommendation REC-html401-19991224, December 1999, 725 . 727 [W3C.REC-webarch-20041215] 728 Jacobs, I. and N. Walsh, "Architecture of the World Wide 729 Web, Volume One", World Wide Web Consortium 730 Recommendation REC-webarch-20041215, December 2004, 731 . 733 7.2. Informative References 735 [NIST800-63] 736 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 737 and E. Nabbus, "NIST Special Publication 800-63-1, 738 INFORMATION SECURITY", December 2008. 740 [OMAP] Huff, J., Schlacht, D., Nadalin, A., Simmons, J., 741 Rosenberg, P., Madsen, P., Ace, T., Rickelton-Abdi, C., 742 and B. Boyer, "Online Multimedia Authorization Protocol: 743 An Industry Standard for Authorized Access to Internet 744 Multimedia Resources", April 2012. 746 [OpenID.Messages] 747 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., 748 Mortimore, C., and E. Jay, "OpenID Connect Messages 1.0", 749 June 2012. 751 Appendix A. Acknowledgements 753 The following people contributed to preliminary versions of this 754 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland 755 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 756 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 757 concepts within are a product of the OAuth community, the WRAP 758 community, and the OAuth Working Group. David Recordon created a 759 preliminary draft of this specification based upon a preliminary 760 version of OAuth 2.0 draft 11. Michael B. Jones created draft 00 of 761 this specification using portions of David's preliminary draft, and 762 edited all subsequent versions. 764 The OAuth Working Group has dozens of very active contributors who 765 proposed ideas and wording for this document, including: Michael 766 Adams, Amanda Anganes, Andrew Arnott, Derek Atkins, Dirk Balfanz, 767 John Bradley, Brian Campbell, Francisco Corella, Leah Culver, Bill de 768 hOra, Breno de Medeiros, Brian Ellin, Stephen Farrell, Igor Faynberg, 769 George Fletcher, Tim Freeman, Evan Gilbert, Yaron Y. Goland, Thomas 770 Hardjono, Justin Hart, Phil Hunt, John Kemp, Eran Hammer, Chasen Le 771 Hara, Dick Hardt, Barry Leiba, Amos Jeffries, Michael B. Jones, 772 Torsten Lodderstedt, Paul Madsen, Eve Maler, James Manger, Laurence 773 Miao, William J. Mills, Chuck Mortimore, Anthony Nadalin, Axel 774 Nennker, Mark Nottingham, David Recordon, Julian Reschke, Rob 775 Richards, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, 776 Marius Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian 777 Stuebner, Doug Tangren, Paul Tarjan, Hannes Tschofenig, Franklin Tse, 778 Sean Turner, Paul Walker, Shane Weeden, Skylar Woodward, and Zachary 779 Zeltsan. 781 Appendix B. Document History 783 [[ to be removed by the RFC editor before publication as an RFC ]] 785 -23 787 o Removed David Recordon's name from the author list, at his 788 request. 790 -22 792 o Removed uses of HTTPbis in favor of RFC 2616 and RFC 2617, since 793 HTTPbis is not an approved standard. 795 o Match formatting of artwork elements with OAuth core 796 specification. 798 -21 800 o Changed "NOT RECOMMENDED" to "not recommended" in caveat about the 801 URI Query Parameter method. 803 o Changed "other specifications may extend this specification for 804 use with other transport protocols" to "other specifications may 805 extend this specification for use with other protocols". 807 o Changed Acknowledgements to use only ASCII characters, per the RFC 808 style guide. 810 -20 812 o Added caveat about using a reserved query parameter name being 813 counter to URI namespace best practices. 815 o Specified use of Cache-Control options when using the URI Query 816 Parameter method. 818 o Changed title to "The OAuth 2.0 Authorization Framework: Bearer 819 Token Usage". 821 o Referenced syntax definitions for the "scope", "error", 822 "error_description", and "error_uri" parameters in the OAuth 2.0 823 core spec. 825 o Registered the "invalid_request", "invalid_token", and 826 "insufficient_scope" error values in the OAuth Extensions Error 827 Registry. 829 o Acknowledged additional individuals. 831 -19 833 o Addressed DISCUSS issues and comments raised for which resolutions 834 have been agreed to. No normative changes were made. Changes 835 made were: 837 o Use ABNF from RFC 5234. 839 o Added sentence "The Bearer authentication scheme is intended 840 primarily for server authentication using the WWW-Authenticate and 841 Authorization HTTP headers, but does not preclude its use for 842 proxy authentication" to the introduction. 844 o In the introduction, state that this document also imposes 845 semantic requirements upon the access token. 847 o Reference the "scope" definition in the OAuth core spec. 849 o Added "scope" examples. 851 o Reference RFC 6265 for security considerations about cookies. 853 -18 855 o Changed example bearer token value from vF9dft4qmT to mF_9.B5f- 856 4.1JqM. 858 o Added example access token response returning a Bearer token. 860 -17 862 o Restore RFC 2818 reference for server identity verification and 863 add RFC 5280 reference for certificate revocation lists, per Gen- 864 ART review comments. 866 -16 868 o Use the HTTPbis auth-param syntax for Bearer challenge attributes. 870 o Dropped the sentence "The "realm" value is intended for 871 programmatic use and is not meant to be displayed to end users". 873 o Reordered form-encoded body parameter description bullets for 874 better readability. 876 o Added [USASCII] reference. 878 -15 880 o Clarified that form-encoded content must consist entirely of ASCII 881 characters. 883 o Added TLS version requirements. 885 o Applied editorial improvements suggested by Mark Nottingham during 886 the APPS area review. 888 -14 890 o Changes made in response to review comments by Security Area 891 Director Stephen Farrell. Specifically: 893 o Strengthened warnings about passing an access token as a query 894 parameter and more precisely described the limitations placed upon 895 the use of this method. 897 o Clarified that the "realm" attribute MAY included to indicate the 898 scope of protection in the manner described in HTTP/1.1, Part 7 899 [I-D.ietf-httpbis-p7-auth]. 901 o Normatively stated that "the token integrity protection MUST be 902 sufficient to prevent the token from being modified". 904 o Added statement that "TLS is mandatory to implement and use with 905 this specification" to the introduction. 907 o Stated that TLS MUST be used with "a ciphersuite that provides 908 confidentiality and integrity protection". 910 o Added "As a further defense against token disclosure, the client 911 MUST validate the TLS certificate chain when making requests to 912 protected resources" to the Threat Mitigation section. 914 o Clarified that putting a validity time field inside the protected 915 part of the token is one means, but not the only means, of 916 limiting the lifetime of the token. 918 o Dropped the confusing phrase "for instance, through the use of 919 TLS" from the sentence about confidentiality protection of the 920 exchanges. 922 o Reference RFC 6125 for identity verification, rather than RFC 923 2818. 925 o Stated that the token MUST be protected between front end and back 926 end servers when the TLS connection terminates at a front end 927 server that is distinct from the actual server that provides the 928 resource. 930 o Stated that bearer tokens MUST NOT be stored in cookies that can 931 be sent in the clear in the Threat Mitigation section. 933 o Replaced sole remaining reference to [RFC2616] with HTTPbis 934 [I-D.ietf-httpbis-p1-messaging] reference. 936 o Replaced all references where the reference is used as if it were 937 part of the sentence (such as "defined by [I-D.whatever]") with 938 ones where the specification name is used, followed by the 939 reference (such as "defined by Whatever [I-D.whatever]"). 941 o Other on-normative editorial improvements. 943 -13 945 o At the request of Hannes Tschofenig, made ABNF changes to make it 946 clear that no special WWW-Authenticate response header field 947 parsers are needed. The "scope", "error-description", and 948 "error-uri" parameters are all now defined as quoted-string in the 949 ABNF (as "error" already was). Restrictions on these values that 950 were formerly described in the ABNFs are now described in 951 normative text instead. 953 -12 954 o Made non-normative editorial changes that Hannes Tschofenig 955 requested be applied prior to forwarding the specification to the 956 IESG. 958 o Added rationale for the choice of the b64token syntax. 960 o Added rationale stating that receivers are free to parse the 961 "scope" attribute using a standard quoted-string parser, since it 962 will correctly process all legal "scope" values. 964 o Added additional active working group contributors to the 965 Acknowledgements section. 967 -11 969 o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. 971 -10 973 o Removed the #auth-param option from Authorization header syntax 974 (leaving only the b64token syntax). 976 o Restricted the "scope" value character set to %x21 / %x23-5B / 977 %x5D-7E (printable ASCII characters excluding double-quote and 978 backslash). Indicated that scope is intended for programmatic use 979 and is not meant to be displayed to end users. 981 o Restricted the character set for "error_description" strings to SP 982 / VCHAR and indicated that they are not meant to be displayed to 983 end users. 985 o Included more description in the Abstract, since Hannes Tschofenig 986 indicated that the RFC editor would require this. 988 o Changed "Access Grant" to "Authorization Grant", as was done in 989 the core spec. 991 o Simplified the introduction to the Authenticated Requests section. 993 -09 995 o Incorporated working group last call comments. Specific changes 996 were: 998 o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than 999 [RFC2617]. 1001 o Update credentials definition to conform to [I-D.ietf-httpbis-p7- 1002 auth]. 1004 o Further clarified that query parameters may occur in any order. 1006 o Specify that error_description is UTF-8 encoded (matching the core 1007 specification). 1009 o Registered "Bearer" Authentication Scheme in Authentication Scheme 1010 Registry defined by [I-D.ietf-httpbis-p7-auth]. 1012 o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- 1013 p7-auth drafts. 1015 o Other wording improvements not introducing normative changes. 1017 -08 1019 o Updated references to oauth-v2 and HTTPbis drafts. 1021 -07 1023 o Added missing comma in error response example. 1025 -06 1027 o Changed parameter name "bearer_token" to "access_token", per 1028 working group consensus. 1030 o Changed HTTP status code for "invalid_request" error code from 1031 HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input 1032 from HTTP working group experts. 1034 -05 1036 o Removed OAuth Errors Registry, per design team input. 1038 o Changed HTTP status code for "invalid_request" error code from 1039 HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP 1040 usage [[ change pending working group consensus ]]. 1042 o Added missing quotation marks in error-uri definition. 1044 o Added note to add language and encoding information to 1045 error_description if the core specification does. 1047 o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined 1048 in [RFC5234]. 1050 o Use auth-param instead of repeating its definition, which is ( 1051 token "=" ( token / quoted-string ) ). 1053 o Clarify security considerations about including an audience 1054 restriction in the token and include a recommendation to issue 1055 scoped bearer tokens in the summary of recommendations. 1057 -04 1059 o Edits responding to working group last call feedback on -03. 1060 Specific edits enumerated below. 1062 o Added Bearer Token definition in Terminology section. 1064 o Changed parameter name "oauth_token" to "bearer_token". 1066 o Added realm parameter to "WWW-Authenticate" response to comply 1067 with [RFC2617]. 1069 o Removed "[ RWS 1#auth-param ]" from "credentials" definition since 1070 it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. 1072 o Removed restriction that the "bearer_token" (formerly 1073 "oauth_token") parameter be the last parameter in the entity-body 1074 and the HTTP request URI query. 1076 o Do not require WWW-Authenticate Response in a reply to a malformed 1077 request, as an HTTP 400 Bad Request response without a WWW- 1078 Authenticate header is likely the right response in some cases of 1079 malformed requests. 1081 o Removed OAuth Parameters registry extension. 1083 o Numerous editorial improvements suggested by working group 1084 members. 1086 -03 1088 o Restored the WWW-Authenticate response header functionality 1089 deleted from the framework specification in draft 12 based upon 1090 the specification text from draft 11. 1092 o Augmented the OAuth Parameters registry by adding two additional 1093 parameter usage locations: "resource request" and "resource 1094 response". 1096 o Registered the "oauth_token" OAuth parameter with usage location 1097 "resource request". 1099 o Registered the "error" OAuth parameter. 1101 o Created the OAuth Error registry and registered errors. 1103 o Changed the "OAuth2" OAuth access token type name to "Bearer". 1105 -02 1107 o Incorporated feedback received on draft 01. Most changes were to 1108 the security considerations section. No normative changes were 1109 made. Specific changes included: 1111 o Changed terminology from "token reuse" to "token capture and 1112 replay". 1114 o Removed sentence "Encrypting the token contents is another 1115 alternative" from the security considerations since it was 1116 redundant and potentially confusing. 1118 o Corrected some references to "resource server" to be 1119 "authorization server" in the security considerations. 1121 o Generalized security considerations language about obtaining 1122 consent of the resource owner. 1124 o Broadened scope of security considerations description for 1125 recommendation "Don't pass bearer tokens in page URLs". 1127 o Removed unused reference to OAuth 1.0. 1129 o Updated reference to framework specification and updated David 1130 Recordon's e-mail address. 1132 o Removed security considerations text on authenticating clients. 1134 o Registered the "OAuth2" OAuth access token type and "oauth_token" 1135 parameter. 1137 -01 1139 o First public draft, which incorporates feedback received on -00 1140 including enhanced Security Considerations content. This version 1141 is intended to accompany OAuth 2.0 draft 11. 1143 -00 1145 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 1147 Authors' Addresses 1149 Michael B. Jones 1150 Microsoft 1152 Email: mbj@microsoft.com 1153 URI: http://self-issued.info/ 1155 Dick Hardt 1156 independent 1158 Email: dick.hardt@gmail.com 1159 URI: http://dickhardt.org/