idnits 2.17.1 draft-ietf-oauth-v2-bearer-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o Stated that bearer tokens MUST not be stored in cookies that can be sent in the clear in the Threat Mitigation section. -- The document date (November 3, 2011) is 4556 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-17 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-17 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-22 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) -- Obsolete informational reference (is this intentional?): RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track D. Hardt 5 Expires: May 6, 2012 independent 6 D. Recordon 7 Facebook 8 November 3, 2011 10 The OAuth 2.0 Authorization Protocol: Bearer Tokens 11 draft-ietf-oauth-v2-bearer-14 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 May 6, 2012. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. Authenticated Requests . . . . . . . . . . . . . . . . . . . . 5 61 2.1. Authorization Request Header Field . . . . . . . . . . . . 5 62 2.2. Form-Encoded Body Parameter . . . . . . . . . . . . . . . 5 63 2.3. URI Query Parameter . . . . . . . . . . . . . . . . . . . 6 64 3. The WWW-Authenticate Response Header Field . . . . . . . . . . 7 65 3.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 8 66 4. Security Considerations . . . . . . . . . . . . . . . . . . . 9 67 4.1. Security Threats . . . . . . . . . . . . . . . . . . . . . 9 68 4.2. Threat Mitigation . . . . . . . . . . . . . . . . . . . . 10 69 4.3. Summary of Recommendations . . . . . . . . . . . . . . . . 11 70 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 71 5.1. OAuth Access Token Type Registration . . . . . . . . . . . 12 72 5.1.1. The "Bearer" OAuth Access Token Type . . . . . . . . . 12 73 5.2. Authentication Scheme Registration . . . . . . . . . . . . 13 74 5.2.1. The "Bearer" Authentication Scheme . . . . . . . . . . 13 75 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 76 6.1. Normative References . . . . . . . . . . . . . . . . . . . 13 77 6.2. Informative References . . . . . . . . . . . . . . . . . . 14 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 79 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 82 1. Introduction 84 OAuth enables clients to access protected resources by obtaining an 85 access token, which is defined in OAuth 2.0 Authorization 86 [I-D.ietf-oauth-v2] as "a string representing an access authorization 87 issued to the client", rather than using the resource owner's 88 credentials directly. 90 Tokens are issued to clients by an authorization server with the 91 approval of the resource owner. The client uses the access token to 92 access the protected resources hosted by the resource server. This 93 specification describes how to make protected resource requests when 94 the OAuth access token is a bearer token. 96 This specification defines the use of bearer tokens with OAuth over 97 HTTP/1.1 [I-D.ietf-httpbis-p1-messaging] using TLS [RFC5246]. TLS is 98 mandatory to implement and use with this specification; other 99 specifications may extend this specification for use with other 100 transport protocols. 102 1.1. Notational Conventions 104 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 105 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 106 document are to be interpreted as described in Key words for use in 107 RFCs to Indicate Requirement Levels [RFC2119]. 109 This document uses the Augmented Backus-Naur Form (ABNF) notation of 110 HTTP/1.1, Part 1 [I-D.ietf-httpbis-p1-messaging], which is based upon 111 the Augmented Backus-Naur Form (ABNF) [RFC5234] notation. 112 Additionally, the following rules are included from HTTP/1.1, Part 7 113 [I-D.ietf-httpbis-p7-auth]: b64token, auth-param, and realm; from 114 HTTP/1.1, Part 1 [I-D.ietf-httpbis-p1-messaging]: quoted-string; and 115 from Uniform Resource Identifier (URI) [RFC3986]: URI-Reference. 117 Unless otherwise noted, all the protocol parameter names and values 118 are case sensitive. 120 1.2. Terminology 122 Bearer Token 123 A security token with the property that any party in possession of 124 the token (a "bearer") can use the token in any way that any other 125 party in possession of it can. Using a bearer token does not 126 require a bearer to prove possession of cryptographic key material 127 (proof-of-possession). 129 All other terms are as defined in OAuth 2.0 Authorization 131 [I-D.ietf-oauth-v2]. 133 1.3. Overview 135 OAuth provides a method for clients to access a protected resource on 136 behalf of a resource owner. In the general case, before a client can 137 access a protected resource, it must first obtain an authorization 138 grant from the resource owner and then exchange the authorization 139 grant for an access token. The access token represents the grant's 140 scope, duration, and other attributes granted by the authorization 141 grant. The client accesses the protected resource by presenting the 142 access token to the resource server. In some cases, a client can 143 directly present its own credentials to an authorization server to 144 obtain an access token without having to first obtain an 145 authorization grant from a resource owner. 147 The access token provides an abstraction, replacing different 148 authorization constructs (e.g. username and password, assertion) for 149 a single token understood by the resource server. This abstraction 150 enables issuing access tokens valid for a short time period, as well 151 as removing the resource server's need to understand a wide range of 152 authentication schemes. 154 +--------+ +---------------+ 155 | |--(A)- Authorization Request ->| Resource | 156 | | | Owner | 157 | |<-(B)-- Authorization Grant ---| | 158 | | +---------------+ 159 | | 160 | | Authorization Grant & +---------------+ 161 | |--(C)--- Client Credentials -->| Authorization | 162 | Client | | Server | 163 | |<-(D)----- Access Token -------| | 164 | | +---------------+ 165 | | 166 | | +---------------+ 167 | |--(E)----- Access Token ------>| Resource | 168 | | | Server | 169 | |<-(F)--- Protected Resource ---| | 170 +--------+ +---------------+ 172 Figure 1: Abstract Protocol Flow 174 The abstract flow illustrated in Figure 1 describes the overall OAuth 175 2.0 protocol architecture. The following steps are specified within 176 this document: 178 E) The client makes a protected resource request to the resource 179 server by presenting the access token. 181 F) The resource server validates the access token, and if valid, 182 serves the request. 184 2. Authenticated Requests 186 This section defines three methods of sending bearer access tokens in 187 resource requests to resource servers. Clients MUST NOT use more 188 than one method to transmit the token in each request. 190 2.1. Authorization Request Header Field 192 When sending the access token in the "Authorization" request header 193 field defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth], the 194 client uses the "Bearer" authentication scheme to transmit the access 195 token. 197 For example: 199 GET /resource HTTP/1.1 200 Host: server.example.com 201 Authorization: Bearer vF9dft4qmT 203 The "Authorization" header field uses the framework defined by 204 HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] as follows: 206 credentials = "Bearer" 1*SP b64token 208 The b64token syntax was chosen over the alternative #auth-param 209 syntax also defined by HTTP/1.1, Part 7 [I-D.ietf-httpbis-p7-auth] 210 both for simplicity reasons and for compatibility with existing 211 implementations. If additional parameters are desired in the future, 212 a different scheme could be defined. 214 Clients SHOULD make authenticated requests with a bearer token using 215 the "Authorization" request header field with the "Bearer" HTTP 216 authorization scheme. Resource servers MUST support this method. 218 2.2. Form-Encoded Body Parameter 220 When sending the access token in the HTTP request entity-body, the 221 client adds the access token to the request body using the 222 "access_token" parameter. The client MUST NOT use this method unless 223 all of the following conditions are met: 225 o The HTTP request entity-body is single-part. 227 o The entity-body follows the encoding requirements of the 228 "application/x-www-form-urlencoded" content-type as defined by 229 HTML 4.01 [W3C.REC-html401-19991224]. 231 o The HTTP request entity-header includes the "Content-Type" header 232 field set to "application/x-www-form-urlencoded". 234 o The HTTP request method is one for which the request body has 235 defined semantics. In particular, this means that the "GET" 236 method MUST NOT be used. 238 The entity-body MAY include other request-specific parameters, in 239 which case, the "access_token" parameter MUST be properly separated 240 from the request-specific parameters using "&" character(s) (ASCII 241 code 38). 243 For example, the client makes the following HTTP request using 244 transport-layer security: 246 POST /resource HTTP/1.1 247 Host: server.example.com 248 Content-Type: application/x-www-form-urlencoded 250 access_token=vF9dft4qmT 252 The "application/x-www-form-urlencoded" method SHOULD NOT be used 253 except in application contexts where participating browsers do not 254 have access to the "Authorization" request header field. Resource 255 servers MAY support this method. 257 2.3. URI Query Parameter 259 When sending the access token in the HTTP request URI, the client 260 adds the access token to the request URI query component as defined 261 by Uniform Resource Identifier (URI) [RFC3986] using the 262 "access_token" parameter. 264 For example, the client makes the following HTTP request using 265 transport-layer security: 267 GET /resource?access_token=vF9dft4qmT HTTP/1.1 268 Host: server.example.com 270 The HTTP request URI query can include other request-specific 271 parameters, in which case, the "access_token" parameter MUST be 272 properly separated from the request-specific parameters using "&" 273 character(s) (ASCII code 38). 275 For example: 277 https://server.example.com/resource?x=y&access_token=vF9dft4qmT&p=q 279 Because of the security weaknesses associated with the URI method 280 (see Section 4), including the high likelihood that the URL 281 containing the access token will be logged, it SHOULD NOT be used 282 unless it is impossible to transport the access token in the 283 "Authorization" request header field or the HTTP request entity-body. 284 Resource servers MAY support this method. 286 3. The WWW-Authenticate Response Header Field 288 If the protected resource request does not include authentication 289 credentials or does not contain an access token that enables access 290 to the protected resource, the resource server MUST include the HTTP 291 "WWW-Authenticate" response header field; it MAY include it in 292 response to other conditions as well. The "WWW-Authenticate" header 293 field uses the framework defined by HTTP/1.1, Part 7 294 [I-D.ietf-httpbis-p7-auth] as follows: 296 challenge = "Bearer" [ 1*SP 1#param ] 298 param = realm / scope / 299 error / error-desc / error-uri / 300 auth-param 302 scope = "scope" "=" quoted-string 303 error = "error" "=" quoted-string 304 error-desc = "error_description" "=" quoted-string 305 error-uri = "error_uri" "=" quoted-string 307 A "realm" attribute MAY be included to indicate the scope of 308 protection in the manner described in HTTP/1.1, Part 7 309 [I-D.ietf-httpbis-p7-auth]. The "realm" attribute MUST NOT appear 310 more than once. The "realm" value is intended for programmatic use 311 and is not meant to be displayed to end users. 313 The "scope" attribute is a space-delimited list of scope values 314 indicating the required scope of the access token for accessing the 315 requested resource. In some cases, the "scope" value will be used 316 when requesting a new access token with sufficient scope of access to 317 utilize the protected resource. The "scope" attribute MUST NOT 318 appear more than once. The "scope" value is intended for 319 programmatic use and is not meant to be displayed to end users. 321 If the protected resource request included an access token and failed 322 authentication, the resource server SHOULD include the "error" 323 attribute to provide the client with the reason why the access 324 request was declined. The parameter value is described in 325 Section 3.1. In addition, the resource server MAY include the 326 "error_description" attribute to provide developers a human-readable 327 explanation that is not meant to be displayed to end users. It also 328 MAY include the "error_uri" attribute with an absolute URI 329 identifying a human-readable web page explaining the error. The 330 "error", "error_description", and "error_uri" attributes MUST NOT 331 appear more than once. 333 Producers of "scope" strings MUST NOT use characters outside the set 334 %x21 / %x23-5B / %x5D-7E for representing the scope values and %x20 335 for the delimiter. Producers of "error" and "error_description" 336 strings MUST NOT use characters outside the set %x20-21 / %x23-5B / 337 %x5D-7E for representing these values. Producers of "error-uri" 338 strings MUST NOT use characters outside the set %x21 / %x23-5B / 339 %x5D-7E for representing these values. Furthermore, "error-uri" 340 strings MUST conform to the URI-reference syntax. In all these 341 cases, no character quoting will occur, as senders are prohibited 342 from using the %5C ('\') character. 344 For example, in response to a protected resource request without 345 authentication: 347 HTTP/1.1 401 Unauthorized 348 WWW-Authenticate: Bearer realm="example" 350 And in response to a protected resource request with an 351 authentication attempt using an expired access token: 353 HTTP/1.1 401 Unauthorized 354 WWW-Authenticate: Bearer realm="example", 355 error="invalid_token", 356 error_description="The access token expired" 358 3.1. Error Codes 360 When a request fails, the resource server responds using the 361 appropriate HTTP status code (typically, 400, 401, or 403), and 362 includes one of the following error codes in the response: 364 invalid_request 365 The request is missing a required parameter, includes an 366 unsupported parameter or parameter value, repeats the same 367 parameter, uses more than one method for including an access 368 token, or is otherwise malformed. The resource server SHOULD 369 respond with the HTTP 400 (Bad Request) status code. 371 invalid_token 372 The access token provided is expired, revoked, malformed, or 373 invalid for other reasons. The resource SHOULD respond with 374 the HTTP 401 (Unauthorized) status code. The client MAY 375 request a new access token and retry the protected resource 376 request. 378 insufficient_scope 379 The request requires higher privileges than provided by the 380 access token. The resource server SHOULD respond with the HTTP 381 403 (Forbidden) status code and MAY include the "scope" 382 attribute with the scope necessary to access the protected 383 resource. 385 If the request lacks any authentication information (i.e. the client 386 was unaware authentication is necessary or attempted using an 387 unsupported authentication method), the resource server SHOULD NOT 388 include an error code or other error information. 390 For example: 392 HTTP/1.1 401 Unauthorized 393 WWW-Authenticate: Bearer realm="example" 395 4. Security Considerations 397 This section describes the relevant security threats regarding token 398 handling when using bearer tokens and describes how to mitigate these 399 threats. 401 4.1. Security Threats 403 The following list presents several common threats against protocols 404 utilizing some form of tokens. This list of threats is based on NIST 405 Special Publication 800-63 [NIST800-63]. Since this document builds 406 on the OAuth 2.0 specification, we exclude a discussion of threats 407 that are described there or in related documents. 409 Token manufacture/modification: An attacker may generate a bogus 410 token or modify the token contents (such as the authentication or 411 attribute statements) of an existing token, causing the resource 412 server to grant inappropriate access to the client. For example, 413 an attacker may modify the token to extend the validity period; a 414 malicious client may modify the assertion to gain access to 415 information that they should not be able to view. 417 Token disclosure: Tokens may contain authentication and attribute 418 statements that include sensitive information. 420 Token redirect: An attacker uses a token generated for consumption 421 by one resource server to gain access to a different resource 422 server that mistakenly believes the token to be for it. 424 Token replay: An attacker attempts to use a token that has already 425 been used with that resource server in the past. 427 4.2. Threat Mitigation 429 A large range of threats can be mitigated by protecting the contents 430 of the token by using a digital signature or a Message Authentication 431 Code (MAC). Alternatively, a bearer token can contain a reference to 432 authorization information, rather than encoding the information 433 directly. Such references MUST be infeasible for an attacker to 434 guess; using a reference may require an extra interaction between a 435 server and the token issuer to resolve the reference to the 436 authorization information. The mechanics of such an interaction are 437 not defined by this specification. 439 This document does not specify the encoding or the contents of the 440 token; hence detailed recommendations about the means of guaranteeing 441 token integrity protection are outside the scope of this document. 442 The token integrity protection MUST be sufficient to prevent the 443 token from being modified. 445 To deal with token redirect, it is important for the authorization 446 server to include the identity of the intended recipients (the 447 audience), typically a single resource server (or a list of resource 448 servers), in the token. Restricting the use of the token to a 449 specific scope is also RECOMMENDED. 451 To protect against token disclosure, confidentiality protection MUST 452 be applied using TLS [RFC5246] with a ciphersuite that provides 453 confidentiality and integrity protection. This requires that the 454 communication interaction between the client and the authorization 455 server, as well as the interaction between the client and the 456 resource server, utilize confidentiality and integrity protection. 457 Since TLS is mandatory to implement and to use with this 458 specification, it is the preferred approach for preventing token 459 disclosure via the communication channel. For those cases where the 460 client is prevented from observing the contents of the token, token 461 encryption MUST be applied in addition to the usage of TLS 462 protection. As a further defense against token disclosure, the 463 client MUST validate the TLS certificate chain when making requests 464 to protected resources. 466 Cookies are typically transmitted in the clear. Thus, any 467 information contained in them is at risk of disclosure. Therefore, 468 bearer tokens MUST NOT be stored in cookies that can be sent in the 469 clear. 471 In some deployments, including those utilizing load balancers, the 472 TLS connection to the resource server terminates prior to the actual 473 server that provides the resource. This could leave the token 474 unprotected between the front end server where the TLS connection 475 terminates and the back end server that provides the resource. In 476 such deployments, sufficient measures MUST be employed to ensure 477 confidentiality of the token between the front end and back end 478 servers; encryption of the token is one possible such measure. 480 To deal with token capture and replay, the following recommendations 481 are made: First, the lifetime of the token MUST be limited; one means 482 of achieving this is by putting a validity time field inside the 483 protected part of the token. Note that using short-lived (one hour 484 or less) tokens reduces the impact of them being leaked. Second, 485 confidentiality protection of the exchanges between the client and 486 the authorization server and between the client and the resource 487 server MUST be applied. As a consequence, no eavesdropper along the 488 communication path is able to observe the token exchange. 489 Consequently, such an on-path adversary cannot replay the token. 490 Furthermore, when presenting the token to a resource server, the 491 client MUST verify the identity of that resource server, as per 492 Representation and Verification of Domain-Based Application Service 493 Identity within Internet Public Key Infrastructure Using X.509 (PKIX) 494 Certificates in the Context of Transport Layer Security (TLS) 495 [RFC6125]. Note that the client MUST validate the TLS certificate 496 chain when making these requests to protected resources. Presenting 497 the token to an unauthenticated and unauthorized resource server or 498 failing to validate the certificate chain will allow adversaries to 499 steal the token and gain unauthorized access to protected resources. 501 4.3. Summary of Recommendations 503 Safeguard bearer tokens: Client implementations MUST ensure that 504 bearer tokens are not leaked to unintended parties, as they will 505 be able to use them to gain access to protected resources. This 506 is the primary security consideration when using bearer tokens and 507 underlies all the more specific recommendations that follow. 509 Validate SSL certificate chains: The client MUST validate the TLS 510 certificate chain when making requests to protected resources. 511 Failing to do so may enable DNS hijacking attacks to steal the 512 token and gain unintended access. 514 Always use TLS (https): Clients MUST always use TLS [RFC5246] 515 (https) or equivalent transport security when making requests with 516 bearer tokens. Failing to do so exposes the token to numerous 517 attacks that could give attackers unintended access. 519 Don't store bearer tokens in cookies: Implementations MUST NOT store 520 bearer tokens within cookies that can be sent in the clear (which 521 is the default transmission mode for cookies). Implementations 522 that do store bearer tokens in cookies MUST take precautions 523 against cross site request forgery. 525 Issue short-lived bearer tokens: Token servers SHOULD issue short- 526 lived (one hour or less) bearer tokens, particularly when issuing 527 tokens to clients that run within a web browser or other 528 environments where information leakage may occur. Using short- 529 lived bearer tokens can reduce the impact of them being leaked. 531 Issue scoped bearer tokens: Token servers SHOULD issue bearer tokens 532 that contain an audience restriction, scoping their use to the 533 intended relying party or set of relying parties. 535 Don't pass bearer tokens in page URLs: Bearer tokens SHOULD NOT be 536 passed in page URLs (for example as query string parameters). 537 Instead, bearer tokens SHOULD be passed in HTTP message headers or 538 message bodies for which confidentiality measures are taken. 539 Browsers, web servers, and other software may not adequately 540 secure URLs in the browser history, web server logs, and other 541 data structures. If bearer tokens are passed in page URLs, 542 attackers might be able to steal them from the history data, logs, 543 or other unsecured locations. 545 5. IANA Considerations 547 5.1. OAuth Access Token Type Registration 549 This specification registers the following access token type in the 550 OAuth Access Token Type Registry. 552 5.1.1. The "Bearer" OAuth Access Token Type 554 Type name: 555 Bearer 557 Additional Token Endpoint Response Parameters: 558 (none) 560 HTTP Authentication Scheme(s): 561 Bearer 563 Change controller: 564 IETF 566 Specification document(s): 567 [[ this document ]] 569 5.2. Authentication Scheme Registration 571 This specification registers the following authentication scheme in 572 the Authentication Scheme Registry defined in HTTP/1.1, Part 7 573 [I-D.ietf-httpbis-p7-auth]. 575 5.2.1. The "Bearer" Authentication Scheme 577 Authentication Scheme Name: 578 Bearer 580 Pointer to specification text: 581 [[ this document ]] 583 Notes (optional): 584 (none) 586 6. References 588 6.1. Normative References 590 [I-D.ietf-httpbis-p1-messaging] 591 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 592 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 593 J. Reschke, "HTTP/1.1, part 1: URIs, Connections, and 594 Message Parsing", draft-ietf-httpbis-p1-messaging-17 (work 595 in progress), October 2011. 597 [I-D.ietf-httpbis-p7-auth] 598 Fielding, R., Gettys, J., Mogul, J., Nielsen, H., 599 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., and 600 J. Reschke, "HTTP/1.1, part 7: Authentication", 601 draft-ietf-httpbis-p7-auth-17 (work in progress), 602 October 2011. 604 [I-D.ietf-oauth-v2] 605 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 606 2.0 Authorization Protocol", draft-ietf-oauth-v2-22 (work 607 in progress), September 2011. 609 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 610 Requirement Levels", BCP 14, RFC 2119, March 1997. 612 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 613 Resource Identifier (URI): Generic Syntax", STD 66, 614 RFC 3986, January 2005. 616 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 617 Specifications: ABNF", STD 68, RFC 5234, January 2008. 619 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 620 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 622 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 623 Verification of Domain-Based Application Service Identity 624 within Internet Public Key Infrastructure Using X.509 625 (PKIX) Certificates in the Context of Transport Layer 626 Security (TLS)", RFC 6125, March 2011. 628 [W3C.REC-html401-19991224] 629 Raggett, D., Jacobs, I., and A. Hors, "HTML 4.01 630 Specification", World Wide Web Consortium 631 Recommendation REC-html401-19991224, December 1999, 632 . 634 6.2. Informative References 636 [NIST800-63] 637 Burr, W., Dodson, D., Perlner, R., Polk, T., Gupta, S., 638 and E. Nabbus, "NIST Special Publication 800-63-1, 639 INFORMATION SECURITY", December 2008. 641 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 642 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 643 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 645 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 646 Leach, P., Luotonen, A., and L. Stewart, "HTTP 647 Authentication: Basic and Digest Access Authentication", 648 RFC 2617, June 1999. 650 Appendix A. Acknowledgements 652 The following people contributed to preliminary versions of this 653 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Y. Goland 654 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 655 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 656 concepts within are a product of the OAuth community, the WRAP 657 community, and the OAuth Working Group. 659 The OAuth Working Group has dozens of very active contributors who 660 proposed ideas and wording for this document, including: Michael 661 Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, John Bradley, 662 Brian Campbell, Leah Culver, Bill de hOra, Brian Ellin, Igor 663 Faynberg, Stephen Farrell, George Fletcher, Tim Freeman, Evan 664 Gilbert, Yaron Y. Goland, Thomas Hardjono, Justin Hart, Phil Hunt, 665 John Kemp, Eran Hammer-Lahav, Chasen Le Hara, Barry Leiba, Michael B. 666 Jones, Torsten Lodderstedt, Eve Maler, James Manger, Laurence Miao, 667 William J. Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, 668 Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius 669 Scurtescu, Naitik Shah, Justin Smith, Jeremy Suriel, Christian 670 Stuebner, Paul Tarjan, Hannes Tschofenig, Franklin Tse, and Shane 671 Weeden. 673 Appendix B. Document History 675 [[ to be removed by the RFC editor before publication as an RFC ]] 677 -14 679 o Changes made in response to review comments by Security Area 680 Director Stephen Farrell. Specifically: 682 o Strengthened warnings about passing an access token as a query 683 parameter and more precisely described the limitations placed upon 684 the use of this method. 686 o Clarified that the "realm" attribute MAY included to indicate the 687 scope of protection in the manner described in HTTP/1.1, Part 7 688 [I-D.ietf-httpbis-p7-auth]. 690 o Normatively stated that "the token integrity protection MUST be 691 sufficient to prevent the token from being modified". 693 o Added statement that "TLS is mandatory to implement and use with 694 this specification" to the introduction. 696 o Stated that TLS MUST be used with "a ciphersuite that provides 697 confidentiality and integrity protection". 699 o Added "As a further defense against token disclosure, the client 700 MUST validate the TLS certificate chain when making requests to 701 protected resources" to the Threat Mitigation section. 703 o Clarified that putting a validity time field inside the protected 704 part of the token is one means, but not the only means, of 705 limiting the lifetime of the token. 707 o Dropped the confusing phrase "for instance, through the use of 708 TLS" from the sentence about confidentiality protection of the 709 exchanges. 711 o Reference RFC 6125 for identity verification, rather than RFC 712 2818. 714 o Stated that the token MUST be protected between front end and back 715 end servers when the TLS connection terminates at a front end 716 server that is distinct from the actual server that provides the 717 resource. 719 o Stated that bearer tokens MUST not be stored in cookies that can 720 be sent in the clear in the Threat Mitigation section. 722 o Replaced sole remaining reference to [RFC2616] with HTTPbis 723 [I-D.ietf-httpbis-p1-messaging] reference. 725 o Replaced all references where the reference is used as if it were 726 part of the sentence (such as "defined by [I-D.whatever]") with 727 ones where the specification name is used, followed by the 728 reference (such as "defined by Whatever [I-D.whatever]"). 730 o Other on-normative editorial improvements. 732 -13 734 o At the request of Hannes Tschofenig, made ABNF changes to make it 735 clear that no special WWW-Authenticate response header field 736 parsers are needed. The "scope", "error-description", and 737 "error-uri" parameters are all now defined as quoted-string in the 738 ABNF (as "error" already was). Restrictions on these values that 739 were formerly described in the ABNFs are now described in 740 normative text instead. 742 -12 744 o Made non-normative editorial changes that Hannes Tschofenig 745 requested be applied prior to forwarding the specification to the 746 IESG. 748 o Added rationale for the choice of the b64token syntax. 750 o Added rationale stating that receivers are free to parse the 751 "scope" attribute using a standard quoted-string parser, since it 752 will correctly process all legal "scope" values. 754 o Added additional active working group contributors to the 755 Acknowledgements section. 757 -11 759 o Replaced uses of <"> with DQUOTE to pass ABNF syntax check. 761 -10 763 o Removed the #auth-param option from Authorization header syntax 764 (leaving only the b64token syntax). 766 o Restricted the "scope" value character set to %x21 / %x23-5B / 767 %x5D-7E (printable ASCII characters excluding double-quote and 768 backslash). Indicated that scope is intended for programmatic use 769 and is not meant to be displayed to end users. 771 o Restricted the character set for "error_description" strings to SP 772 / VCHAR and indicated that they are not meant to be displayed to 773 end users. 775 o Included more description in the Abstract, since Hannes Tschofenig 776 indicated that the RFC editor would require this. 778 o Changed "Access Grant" to "Authorization Grant", as was done in 779 the core spec. 781 o Simplified the introduction to the Authenticated Requests section. 783 -09 785 o Incorporated working group last call comments. Specific changes 786 were: 788 o Use definitions from [I-D.ietf-httpbis-p7-auth] rather than 789 [RFC2617]. 791 o Update credentials definition to conform to 792 [I-D.ietf-httpbis-p7-auth]. 794 o Further clarified that query parameters may occur in any order. 796 o Specify that error_description is UTF-8 encoded (matching the core 797 specification). 799 o Registered "Bearer" Authentication Scheme in Authentication Scheme 800 Registry defined by [I-D.ietf-httpbis-p7-auth]. 802 o Updated references to oauth-v2, httpbis-p1-messaging, and httpbis- 803 p7-auth drafts. 805 o Other wording improvements not introducing normative changes. 807 -08 809 o Updated references to oauth-v2 and HTTPbis drafts. 811 -07 813 o Added missing comma in error response example. 815 -06 817 o Changed parameter name "bearer_token" to "access_token", per 818 working group consensus. 820 o Changed HTTP status code for "invalid_request" error code from 821 HTTP 401 (Unauthorized) back to HTTP 400 (Bad Request), per input 822 from HTTP working group experts. 824 -05 826 o Removed OAuth Errors Registry, per design team input. 828 o Changed HTTP status code for "invalid_request" error code from 829 HTTP 400 (Bad Request) to HTTP 401 (Unauthorized) to match HTTP 830 usage [[ change pending working group consensus ]]. 832 o Added missing quotation marks in error-uri definition. 834 o Added note to add language and encoding information to 835 error_description if the core specification does. 837 o Explicitly reference the Augmented Backus-Naur Form (ABNF) defined 838 in [RFC5234]. 840 o Use auth-param instead of repeating its definition, which is ( 841 token "=" ( token / quoted-string ) ). 843 o Clarify security considerations about including an audience 844 restriction in the token and include a recommendation to issue 845 scoped bearer tokens in the summary of recommendations. 847 -04 849 o Edits responding to working group last call feedback on -03. 850 Specific edits enumerated below. 852 o Added Bearer Token definition in Terminology section. 854 o Changed parameter name "oauth_token" to "bearer_token". 856 o Added realm parameter to "WWW-Authenticate" response to comply 857 with [RFC2617]. 859 o Removed "[ RWS 1#auth-param ]" from "credentials" definition since 860 it did not comply with the ABNF in [I-D.ietf-httpbis-p7-auth]. 862 o Removed restriction that the "bearer_token" (formerly 863 "oauth_token") parameter be the last parameter in the entity-body 864 and the HTTP request URI query. 866 o Do not require WWW-Authenticate Response in a reply to a malformed 867 request, as an HTTP 400 Bad Request response without a WWW- 868 Authenticate header is likely the right response in some cases of 869 malformed requests. 871 o Removed OAuth Parameters registry extension. 873 o Numerous editorial improvements suggested by working group 874 members. 876 -03 878 o Restored the WWW-Authenticate response header functionality 879 deleted from the framework specification in draft 12 based upon 880 the specification text from draft 11. 882 o Augmented the OAuth Parameters registry by adding two additional 883 parameter usage locations: "resource request" and "resource 884 response". 886 o Registered the "oauth_token" OAuth parameter with usage location 887 "resource request". 889 o Registered the "error" OAuth parameter. 891 o Created the OAuth Error registry and registered errors. 893 o Changed the "OAuth2" OAuth access token type name to "Bearer". 895 -02 897 o Incorporated feedback received on draft 01. Most changes were to 898 the security considerations section. No normative changes were 899 made. Specific changes included: 901 o Changed terminology from "token reuse" to "token capture and 902 replay". 904 o Removed sentence "Encrypting the token contents is another 905 alternative" from the security considerations since it was 906 redundant and potentially confusing. 908 o Corrected some references to "resource server" to be 909 "authorization server" in the security considerations. 911 o Generalized security considerations language about obtaining 912 consent of the resource owner. 914 o Broadened scope of security considerations description for 915 recommendation "Don't pass bearer tokens in page URLs". 917 o Removed unused reference to OAuth 1.0. 919 o Updated reference to framework specification and updated David 920 Recordon's e-mail address. 922 o Removed security considerations text on authenticating clients. 924 o Registered the "OAuth2" OAuth access token type and "oauth_token" 925 parameter. 927 -01 929 o First public draft, which incorporates feedback received on -00 930 including enhanced Security Considerations content. This version 931 is intended to accompany OAuth 2.0 draft 11. 933 -00 935 o Initial draft based on preliminary version of OAuth 2.0 draft 11. 937 Authors' Addresses 939 Michael B. Jones 940 Microsoft 942 Email: mbj@microsoft.com 943 URI: http://self-issued.info/ 945 Dick Hardt 946 independent 948 Email: dick.hardt@gmail.com 949 URI: http://dickhardt.org/ 951 David Recordon 952 Facebook 954 Email: dr@fb.com 955 URI: http://www.davidrecordon.com/