idnits 2.17.1 draft-ietf-httpauth-extension-04.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 date (July 6, 2015) is 3217 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-11) exists of draft-ietf-httpauth-mutual-05 Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPAUTH Working Group Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Experimental H. Takagi 5 Expires: January 7, 2016 ITRI, AIST 6 T. Hayashi 7 Lepidum 8 Y. Ioku 9 Individual 10 July 6, 2015 12 HTTP Authentication Extensions for Interactive Clients 13 draft-ietf-httpauth-extension-04 15 Abstract 17 This document specifies a few extensions of HTTP authentication 18 framework for interactive clients. Recently, fundamental features of 19 HTTP-level authentication is not enough for complex requirements of 20 various Web-based applications. This makes these applications to 21 implement their own authentication frameworks using HTML Forms and 22 other means, which becomes one of the hurdles against introducing 23 secure authentication mechanisms handled jointly by servers and user- 24 agent clients. The extended framework fills gaps between Web 25 application requirements and HTTP authentication provisions to solve 26 the above problems, while maintaining compatibility against existing 27 Web and non-Web uses of HTTP authentications. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 7, 2016. 46 Copyright Notice 48 Copyright (c) 2015 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 65 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 2.1. Terms for describing authentication protocol flow . . . . 5 67 2.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 68 3. Optional Authentication . . . . . . . . . . . . . . . . . . . 8 69 4. Authentication-Control header . . . . . . . . . . . . . . . . 9 70 4.1. Non-ASCII extended header parameters . . . . . . . . . . . 11 71 4.2. Auth-style parameter . . . . . . . . . . . . . . . . . . . 12 72 4.3. Location-when-unauthenticated parameter . . . . . . . . . 13 73 4.4. No-auth parameter . . . . . . . . . . . . . . . . . . . . 13 74 4.5. Location-when-logout parameter . . . . . . . . . . . . . . 14 75 4.6. Logout-timeout parameter . . . . . . . . . . . . . . . . . 15 76 4.7. Username parameter . . . . . . . . . . . . . . . . . . . . 15 77 5. Usage examples (informative) . . . . . . . . . . . . . . . . . 16 78 5.1. Example 1: a portal site . . . . . . . . . . . . . . . . . 16 79 5.1.1. Case 1: a simple application . . . . . . . . . . . . . 17 80 5.1.2. Case 2: specific action required on log-out . . . . . 17 81 5.1.3. Case 3: specific page displayed before log-in . . . . 17 82 5.2. Example 2: authenticated user-only sites . . . . . . . . . 18 83 5.3. When to use Cookies . . . . . . . . . . . . . . . . . . . 18 84 5.4. Parallel deployment with Form/Cookie authentications . . . 19 85 6. Methods to extend this protocol . . . . . . . . . . . . . . . 20 86 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 87 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 88 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 89 9.1. Normative References . . . . . . . . . . . . . . . . . . . 22 90 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 91 Appendix A. (Informative) Applicability of features for each 92 messages . . . . . . . . . . . . . . . . . . . . . . 23 93 Appendix B. (Informative) Draft Notes . . . . . . . . . . . . . . 23 94 Appendix C. (Informative) Draft Change Log . . . . . . . . . . . 24 95 C.1. Changes in Httpauth WG revision 04 . . . . . . . . . . . . 24 96 C.2. Changes in Httpauth WG revision 03 . . . . . . . . . . . . 24 97 C.3. Changes in Httpauth WG revision 02 . . . . . . . . . . . . 24 98 C.4. Changes in Httpauth WG revision 01 . . . . . . . . . . . . 24 99 C.5. Changes in Httpauth revision 00 and HttpBis revision 00 . 24 100 C.6. Changes in revision 02 . . . . . . . . . . . . . . . . . . 24 101 C.7. Changes in revision 01 . . . . . . . . . . . . . . . . . . 24 102 C.8. Changes in revision 00 . . . . . . . . . . . . . . . . . . 25 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 105 1. Introduction 107 The document proposes several extensions to the current HTTP 108 authentication framework, to provide enough functionality comparable 109 with current widely-used form-based Web authentication. A majority 110 of the recent Web-sites on the Internet use custom application-layer 111 authentication implementations using Web forms. The reasons for 112 these may vary, but many people believe that the current HTTP Basic 113 (and Digest, too) authentication method does not have enough 114 functionality (including a good-feeling user interfaces) to support 115 most of realistic Web-based applications. However, the method is 116 very weak against phishing and other attacks, because the whole 117 behavior of the authentication is controlled from the server-side 118 applications. This makes it really hard to implement any 119 cryptographically strong authentication mechanisms into Web systems. 120 To overcome this problem, we need to "modernize" the HTTP 121 authentication framework so that better client-controlled secure 122 methods can be used with Web applications. The extensions proposed 123 in this document include: 125 o non-mandatory, optional authentication on HTTP (Section 3), 127 o log out from both server and client side (Section 4), and 129 o finer control for redirection depending on authentication status 130 (Section 4). 132 1.1. Terminology 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 136 "OPTIONAL" in this document are to be interpreted as described in 137 [RFC2119]. 139 The terms "encouraged" and "advised" are used for suggestions that do 140 not constitute "SHOULD"-level requirements. People MAY freely choose 141 not to include the suggested items regarding [RFC2119], but complying 142 with those suggestions would be a best practice; it will improve the 143 security, interoperability, and/or operational performance. 145 This document distinguishes the terms "client" and "user" in the 146 following way: A "client" is an entity understanding and talking HTTP 147 and the specified authentication protocol, usually computer software; 148 a "user" is a (usually natural) person who wants to access data 149 resources using "a client". 151 2. Definitions 153 2.1. Terms for describing authentication protocol flow 155 HTTP Authentication defined in [RFC7235] may involve with several 156 pairs of HTTP requests/responses. Throughout this document, the 157 following terms are used to categorize those messages: for requests, 159 o A non-authenticating request is a request not attempting any 160 authentication: a request without any Authorization header. 162 o An authenticating request is the opposite: a request with an 163 Authorization header. 165 For responses, 167 1) A non-authenticated response: is a response which does not 168 involve with any HTTP authentication. It may not contain any 169 WWW-Authenticate or Authentication-Info header. 171 Servers send this response when the requested resource is not 172 protected by HTTP authentication mechanisms. In context of this 173 specification, not-authentication-related negative responses (e.g. 174 403 and 404) are also considered as non-authenticated responses. 176 (See note on successfully-authenticated responses below for some 177 ambiguous cases.) 179 2) An authentication-initializing response: is a response which 180 requires or allows clients to start authentication attempts. 181 Servers send this response when the requested resource is 182 protected by HTTP authentication mechanism, and the request meets 183 one of the following cases: 185 * The request is non-authenticating request, or 187 * The request contained an authentication trial directed to the 188 protection space (realm) other than the server's expected one. 190 The server will specify the protection space for authentication in 191 this response. 193 Upon reception, the client's behavior is further divided to two 194 possible cases. 196 * If the client may have no prior knowledge on authentication 197 credentials (e.g. a user-name and a password) related to the 198 requested protection space, the protocol flow terminates and 199 the client will ask the user to provide authentication 200 credentials, 202 * On the other hand, if client already have an enough credentials 203 for authentication to the requested protection space, the 204 client will automatically send an authenticating request. Such 205 cases often occur when the client did not know beforehand that 206 the current request-URL requires an authentication. 208 3) A successfully-authenticated response: is a response for an 209 authenticating request meaning that the authentication attempt was 210 granted. (Note: if the authentication scheme used does not use an 211 Authentication-Info header, it may be indistinguishable from a 212 non-authenticated response.) 214 4) An intermediate authenticating response: is a response for an 215 authenticating request which requires some more reaction by the 216 client software without involving users. Such a response is 217 required when an authentication scheme requires two or more round- 218 trip messages to perform authentication, or when an authentication 219 scheme uses some speculative short-cut method (such as uses of 220 cached shared secrets) and it failed. 222 5) A negatively-authenticated response: is a response for an 223 authenticating request which means that the authentication attempt 224 was declined and can not continue without another authentication 225 credential. Clients typically erase memory of the currently-using 226 credentials and ask the user for other ones. 228 Usually the format of these responses are as same as the one for 229 authentication-initializing responses. Client can distinguish it 230 by comparing the protection spaces contained in the request and in 231 the response. 233 Figure 1 shows a state diagram of generic HTTP authentication with 234 the above message categorization. Note that many authentication 235 schemes use only a subset of the transitions described on the 236 diagram. Labels in the figure show the abbreviated names of response 237 types. 239 =========== ----------------- 240 NEW REQUEST ( UNAUTHENTICATED ) 241 =========== ----------------- 242 | ^ non-auth. 243 v | response 244 +----------------------+ NO +-------------+ 245 | The requested URI |--------------------------->| send normal | 246 | known to be auth'ed? | ---------------->| request | 247 +----------------------+ / +-------------+ 248 YES | / initializing| 249 v / | 250 +------------------+ NO / | 251 | Can auth-req.(*1)|--------- | 252 | be constructed? | | 253 +------------------+ | 254 YES | initializing | 255 | ---------------------------------------. | 256 | / v v 257 | | ---------------- NO +-----------+ 258 | | ( AUTH-REQUESTED )<------|credentials| 259 | | ---------------- | known? | 260 v | +-----------+ 261 +-----------+ negative ------------- negative |YES 262 | send |---------->( AUTH-FAILED )<---------, | 263 /| auth-req | ------------- | | 264 / +-----------+\ | v 265 | \ \ intermediate +-----------+ 266 | \ -------------------------------->| send | 267 | \ | auth-req | 268 | non-auth. \successful successful +-----------+ 269 | response (*2) \ / | ^ 270 v \ / | | 271 ----------------- \ -------------- / `----' 272 ( UNAUTHENTICATED ) ----->( AUTH-SUCCEED )<---- intermediate 273 ----------------- -------------- 275 Figure 1: Generic state diagram for HTTP authentication 277 Note: (*1) For example, "Digest" scheme requires server-provided 278 nonce to construct client-side challenges. 279 (*2) In "Basic" and some others, this cannot be distinguished from a 280 successfully-authenticated response. 282 2.2. Syntax Notation 284 This specification uses an extended BNF syntax defined in [RFC7230]. 285 The following syntax definitions are quoted from [RFC7230] and 287 [RFC7235]: auth-scheme, quoted-string, auth-param, SP, BWS, header- 288 field, and challenge. It also uses the convention of using header 289 names for specifying syntax of header values. 291 Additionally, this specification uses the following syntax elements 292 following syntax definitions as a refinement for token and the right- 293 hand-side of auth-param in [RFC7235]. (Note: these definitions are 294 consistent with those in [I-D.ietf-httpauth-mutual].) 296 bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 297 extension-token = "-" bare-token 1*("." bare-token) 298 extensive-token = bare-token / extension-token 299 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 301 Figure 2: the BNF syntax for common notations 303 Extensive-tokens are used in this protocol where the set of 304 acceptable tokens may include private extensions. Any private 305 extensions of this protocol MUST use the extension-tokens with format 306 "-.", where is a validly registered 307 (sub-)domain name on the Internet owned by the party who defines the 308 extensions. 310 3. Optional Authentication 312 The Optional-WWW-Authenticate header enables a non-mandatory 313 authentication, which is not possible under the current HTTP 314 authentication mechanism. In several Web applications, users can 315 access the same contents as both a guest user and an authenticated 316 user. In most Web applications, it is implemented using HTTP cookies 317 [RFC6265] and custom form-based authentications. The new 318 authentication method using this message will provide a replacement 319 for these authentication systems. 321 Servers MAY send HTTP successful responses (response code 200, 206 322 and others) containing the Optional-WWW-Authenticate header as a 323 replacement of a 401 response when it is an authentication- 324 initializing response. The Optional-WWW-Authenticate header MUST NOT 325 be contained in 401 responses. 327 HTTP/1.1 200 OK 328 Optional-WWW-Authenticate: Basic realm="xxxx" 330 Optional-WWW-Authenticate = 1#challenge 332 Figure 3: BNF syntax for Optional-WWW-Authenticate header 334 The challenges contained in the Optional-WWW-Authenticate header are 335 the same as those for a 401 responses corresponding for a same 336 request. For authentication-related matters, an optional 337 authentication request will have the same meaning as a 401 message 338 with a corresponding WWW-Authenticate header (as an authentication- 339 initializing response). (The behavior for other matters, such as 340 caching, MAY be different between the optional authentication and 401 341 messages.) 343 A response with an Optional-WWW-Authenticate header SHOULD be 344 returned from the server only when the request is either non- 345 authenticated or authenticating to a wrong (not the server's 346 expected) protection space. If a response is either an intermediate 347 or a negative response to a client's authentication attempt, the 348 server MUST respond with a 401 status response with a 349 WWW-Authenticate header instead. Failure to comply this rule will 350 make client not able to distinguish authentication successes and 351 failures. 353 The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate 354 header in a positive response when a client's authentication attempt 355 succeeds. 357 Whenever an authentication scheme support for servers to send some 358 parameter which gives a hint of URL space for the corresponding 359 protection space for the same realm (e.g. "path" or "domain"), 360 servers requesting non-mandatory authentication SHOULD send such 361 parameter with the response. Clients supporting non-mandatory 362 authentication MUST recognize the parameter, and MUST send a request 363 with an appropriate authentication credential in an Authorization 364 header for any URI inside the specified paths. 366 Support of this header is OPTIONAL; Clients MAY also choose any set 367 of authentication schemes for which optional authentication is 368 supported (in other words, its support MAY be scheme-dependent). 369 However, some authentication schemes MAY require mandatory/ 370 recommended support for this header, so that server-side applications 371 MAY assume that clients supporting such schemes are likely to support 372 the extension as well. 374 4. Authentication-Control header 375 Authentication-Control = 1#Auth-Control-Entry 376 Auth-Control-Entry = auth-scheme 1*SP 1#auth-control-param 377 auth-control-param = extensive-token BWS "=" BWS token 378 / extensive-token "*" BWS "=" BWS ext-value 379 ext-value = 381 Figure 4: the BNF syntax for the Authentication-Control header 383 The Authentication-Control header provides a more precise control of 384 the client behavior for Web applications using an HTTP authentication 385 protocol. This header is supposed to be generated in the application 386 layer, as opposed to WWW-Authenticate headers which will be generated 387 usually by the Web servers. 389 Support of this header is OPTIONAL, and clients MAY choose any subset 390 of these parameters to be supported. The set of supported parameters 391 MAY also be authentication scheme-dependent. However, some 392 authentication schemes MAY require mandatory/recommended support for 393 some or all of the features provided in this header. 395 The Authentication-Control header contains one or more 396 "authentication control entries" each of which corresponds to a 397 single realm for a specific authentication scheme. If the 398 auth-scheme specified for an entry supports the HTTP "realm" feature, 399 that entry MUST contain the "realm" parameter. If not, the entry 400 MUST NOT contain the "realm" parameter. 402 Among the multiple entries in the header, the meaningful entries in 403 the header are those corresponding to an auth-scheme and a realm (if 404 any), for which "the authentication process is being performed, or 405 going to be performed". In more detail, 407 (1) If the response is either an authentication-initializing 408 response or a negatively-authenticated response, there may be 409 multiple challenges in the WWW-Authenticate (or Optional-WWW- 410 Authenticate defined in this extension) header, each of which 411 corresponds to a different scheme and realm. The client will 412 determine the scheme and realm to perform an authentication, and 413 the entries corresponding to the chosen scheme and realm will be 414 meaningful. 416 (2) If the response is either an intermediate authenticating 417 response or a successfully-authenticated response, the scheme 418 and a realm given in the Authorization header of the HTTP 419 request will determine the currently-ongoing authentication 420 process. Only the entries correspond to that scheme and realm 421 are meaningful. 423 The server MAY send an Authentication-Control header containing non- 424 meaningful entries. The client MUST ignore all non-meaningful 425 entries it received. 427 Each entry contains one or more parameters, each of which is a name- 428 value pair. The name of each parameter MUST be an extensive-token. 429 Clients MUST ignore any unknown parameters contained in this header. 430 The entries for the same auth-scheme and the realm MUST NOT contain 431 the duplicated parameters for the same name. 433 The type of parameter value depends on the parameter name as defined 434 in the following subsections. Regardless of the type, however, the 435 recipients SHOULD accept both quoted and unquoted representations of 436 values as defined in HTTP. If the parameter is defined to have a 437 string value, is is encouraged t be sent either in a quoted form or 438 an ext-value form (see Section 4.1). If it is defined as a token (or 439 similar) or an integer, the value SHOULD follow the corresponding 440 ABNF syntax after possible unquoting of the quoted-string value (as 441 defined in HTTP), and is encouraged to be sent in a unquoted form. 443 Server-side application SHOULD always be reminded that any parameters 444 contained in this header MAY be ignored by clients. Also, even when 445 a client accepts this header, users may always be able to circumvent 446 semantics of this header. Therefore, if this header is used for 447 security purposes, its use MUST be limited for providing some non- 448 fundamental additional security measures valuable for end-users (such 449 as client-side log-out for protecting against console takeover). 450 Server-side application MUST NOT rely on the use of this header for 451 protecting server-side resources. 453 Note: The header syntax allows servers to specify Authentication- 454 Control for multiple authentication schemes, either as multiple 455 occurrences of this header or as a combined single header (see 456 Section 3.2.2 of [RFC7230] for rationale). The same care as for 457 parsing multiple authentication challenges SHALL be taken. 459 4.1. Non-ASCII extended header parameters 461 Parameters contained in the Authentication-Control header MAY be 462 extended to ISO 10646-1 values using the framework described in 463 [RFC5987]. All servers and clients MUST be capable of receiving and 464 sending values encoded in [RFC5987] syntax. 466 If a value to be sent contains only ASCII characters, the field MUST 467 be sent in clear using plain RFC 7235 syntax. The syntax extended by 468 RFC 5987 MUST NOT be used in this case. 470 If a value (except the "realm" header) contains one or more non-ASCII 471 characters, the parameter SHOULD be sent using the ext-value syntax 472 defined in Section 3.2 of [RFC5987]. Such parameter MUST have 473 charset value of "UTF-8", and the language value MUST always be 474 omitted (have an empty value). The same parameter MUST NOT be sent 475 twice or more, those in both plain- and extended-syntax. 477 For example, a parameter "username" with value "Renee or France" 478 SHOULD be sent as < username="Renee of France" >. If the value is 479 "Rene of France", it SHOULD be sent as < username*=UTF- 480 8''Ren%C3%89e%20of%20France > instead. 482 4.2. Auth-style parameter 484 Authentication-Control: Digest realm="protected space", 485 auth-style=modal 487 The parameter "auth-style" specifies the server's preferences over 488 user interface behavior for user authentication. This parameter can 489 be included in any kind of responses, however, it is only meaningful 490 for either authentication-initializing or negatively-authenticated 491 responses. The value of this parameter MUST be one of the bare- 492 tokens "modal" or "non-modal". When the Optional-WWW-Authenticate 493 header is used, the value of this parameter MUST be disregarded and 494 the value "non-modal" is implied. 496 The value "modal" means that the server thinks the content of the 497 response (body and other content-related headers) is valuable only 498 for users refusing authentication request. The clients are expected 499 to ask the user a password before processing the content. This 500 behavior is common for most of the current implementations of Basic 501 and Digest authentication schemes. 503 The value "non-modal" means that the server thinks the content of the 504 response (body and other content-related headers) is valuable for 505 users before processing an authentication request. The clients are 506 expected to first process the content and then provide users 507 opportunities to perform authentication. 509 The default behavior for the clients is implementation-dependent, and 510 clients MAY choose different defaults for different authentication 511 schemes. The proposed default behavior is "modal" for all 512 authentication schemes, but specifications for authentication schemes 513 MAY propose a different default. 515 The above two different methods of authentication may introduce a 516 observable difference of semantics when the response contains state- 517 changing side effects; for example, it may change whether Cookie 518 headers [RFC6265] in 401 responses are processed or not. However, 519 the server applications SHOULD NOT depend on both existence and non- 520 existence of such side effects. 522 4.3. Location-when-unauthenticated parameter 524 Authentication-Control: Mutual realm="auth-space-1", 525 location-when-unauthenticated="http://www.example.com/login.html" 527 The parameter "location-when-unauthenticated" specifies a location 528 where any unauthenticated clients should be redirected to. This 529 header may be used, for example, when there is a central login page 530 for the entire Web application. The value of this parameter is a 531 string that contains an absolute URL location. Senders MUST always 532 send an absolute URL location. If a received URL is not absolute, 533 the clients SHOULD either ignore it or consider it a relative URL 534 from the current location. 536 This parameter MAY be used with a 401 response for authentication- 537 initializing response. It can also be contained, although 538 NOT RECOMMENDED, in a positive response with an 539 Optional-WWW-Authenticate header. The clients MUST ignore this 540 parameter, when a response is either successfully-authenticated or 541 intermediately-authenticated. The clients SHOULD ignore this 542 parameter when a response is a negatively-authenticated one (the case 543 is unlikely to happen, though). 545 When a client receives an authentication-initiating response with 546 this parameter, if the client has to ask users for authentication 547 credentials, the client will treat the entire response as if it were 548 a 303 "See Other" response with a Location header that contains the 549 value of this parameter (i.e., client will be redirected to the 550 specified location with a GET request). Unlike a normal 303 551 response, if the client can process authentication without the user's 552 interaction, this parameter MUST be ignored. 554 4.4. No-auth parameter 556 Authentication-Control: Basic realm="entrance", no-auth=true 558 The parameter "no-auth" is a variant of the 559 location-when-unauthenticated parameter; it specifies that new 560 authentication attempt is not to be performed on this location for 561 better user experience, without specifying the redirection on the 562 HTTP level. This header may be used, for example, when there is a 563 central login page for the entire Web application, and when a (Web 564 content's level) explicit interaction of users is desired before 565 authentications. The value of this parameter MUST be a token "true". 566 If the value is incorrect, client MAY ignore this parameter. 568 This parameter MAY be used with authentication-initiating responses. 569 It can also be contained, although NOT RECOMMENDED, in a positive 570 response with an Optional-WWW-Authenticate header. The clients MUST 571 ignore this parameter, when a response is either successfully- 572 authenticated or intermediately-authenticated. The clients SHOULD 573 ignore this parameter when a response is a negatively-authenticated 574 one (the case is unlikely to happen, though). 576 When a client receives an authentication-initiating response with 577 this parameter, if the client has to ask users for authentication 578 credentials, the client will ignore the WWW-Authenticate header 579 contained in the response and treat the whole response as a normal 580 negative 4xx-class response instead of giving user an opportunity to 581 start authentication. If the client can process authentication 582 without the user's interaction, this parameter MUST ignored. 584 This parameter SHOULD NOT be used along with the 585 location-when-unauthenticated parameter. If both were supplied, 586 clients MAY choose which one is to be honored. 588 This parameter SHOULD NOT be used as any security measures to prevent 589 authentication attempts, as it is easily circumvented by users. This 590 parameter SHOULD be used solely for improving user experience of web 591 applications. 593 4.5. Location-when-logout parameter 595 Authentication-Control: Digest realm="protected space", 596 location-when-logout="http://www.example.com/byebye.html" 598 The parameter "location-when-logout" specifies a location where the 599 client is to be redirected when the user explicitly request a logout. 600 The value of this parameter MUST be a string that contains an 601 absolute URL location. If a given URL is not absolute, the clients 602 MAY consider it a relative URL from the current location. 604 This parameter MAY be used with successfully-authenticated responses. 605 If this parameter is contained in other kinds of responses, the 606 clients MUST ignore this parameter. 608 When the user requests to terminate an authentication period, and if 609 the client currently displays a page supplied by a response with this 610 parameter, the client will be redirected to the specified location by 611 a new GET request (as if it received a 303 response). The log-out 612 operation (e.g. erasing memories of user name, authentication 613 credential and all related one-time credentials such as nonce or 614 keys) SHOULD occur before processing a redirection. 616 When the user requests to terminate an authentication period, if the 617 client supports this parameter but the server response does not 618 contain this parameter, the client's RECOMMENDED behavior is as 619 follows: if the request corresponding to the current content was safe 620 (e.g. GET), reload the page without the authentication credential. 621 If the request was non-idempotent (e.g. POST), keep the current 622 content as-is and simply forget the authentication status. The 623 client SHOULD NOT replay a non-idempotent request without the user's 624 explicit approval. 626 Web applications are encouraged to send this parameter with an 627 appropriate value for any responses (except those with redirection 628 (3XX) statuses) for non-GET requests. 630 4.6. Logout-timeout parameter 632 Authentication-Control: Basic realm="entrance", logout-timeout=300 634 The parameter "logout-timeout", when contained in a successfully- 635 authenticated response, means that any authentication credentials and 636 states related to the current protection space are to be discarded if 637 a time specified in this header (in seconds) has been passed from the 638 time received. The value MUST be an integer. As a special case, the 639 value 0 means that the client is requested to immediately log-out 640 from the current authentication space and revert to an 641 unauthenticated status. This does not, however, mean that the long- 642 term memories for the passwords (such as the password reminders and 643 auto fill-ins) should be removed. If a new timeout value is received 644 for the same authentication space, it cancels the previous timeout 645 and sets a new timeout. 647 4.7. Username parameter 649 Authentication-Control: Basic realm="configuration", username="admin" 651 The parameter "username" tells that the only "user name" to be 652 accepted by the server is the value given in this parameter. This 653 parameter is particularly useful, for example, for routers and other 654 appliances with a Web configuration interface. 656 This parameter MAY be used with authentication-initiating responses 657 or negatively-authenticated responses requiring another attempt of 658 authentication. The clients MUST ignore this parameter, when a 659 response is either successfully-authenticated or intermediately- 660 authenticated. 662 If the authentication scheme to be used has syntax limitation on the 663 allowed user names (e.g. Basic and Digest do not allow colons in 664 user names), the specified value MUST follow that limitation. Client 665 SHOULD ignore any values which do not conform to such limitations. 667 Clients MAY still send any authentication requests with other user 668 names, possibly in vain. Servers are not strictly required to reject 669 user names other than specified, but doing it will give bad user 670 experiences and may confuse users and clients. 672 If the used authentication scheme requires specific style of text 673 preparation for the user name (e.g., PRECIS string preparation or 674 Unicode normalization), the specified user name SHOULD follow such 675 requirements. 677 5. Usage examples (informative) 679 This section shows some examples for applying this extension to 680 typical Web-sites which are using Forms and cookies for managing 681 authentication and authorization. The content of this section is not 682 normative and for illustrative purposes only. 684 We assume that all features described in the previous sections are 685 implemented in clients (Web browsers). We also assume that browsers 686 will have a user interface which allows users to deactivate (log-out 687 from) current authentication sessions. If this assumption is not 688 hold, texts below provides another approach with de-authentication 689 pages used instead of such a UI. 691 Without explicit notices, all settings described below are to be 692 applied with Authentication-Control headers, and these can be sent to 693 clients regardless of authentication statuses (these will be silently 694 ignored whenever not effective). 696 5.1. Example 1: a portal site 698 This subsection provides an example application for a site whose 699 structure is somewhat similar to conventional portal sites. In 700 particular, most of web pages are available for guest 701 (unauthenticated) users, and if authentication is performed, contents 702 of these pages are customized for each user. We assume the site has 703 the following kinds of pages currently: 705 o Content pages. 707 o Pages/mechanism for performing authentication: 709 * There is one page which asks a user name and a password using a 710 HTML POST form. 712 * After the authentication attempt, the user will be redirected 713 to either the page which is previously displayed before the 714 authentication, or some specific page. 716 o A de-authentication (log-out) page. 718 5.1.1. Case 1: a simple application 720 When such a site does not need a specific actions upon log-in and 721 log-out, the following simple settings can be used. 723 o Set up an optional authentication to all pages available to 724 guests. Set up an Authentication-Control header with "auth- 725 style=non-modal" setting. 727 o If there are pages only available to authenticated users, Set up a 728 mandatory authentication with "auth-style=non-modal" setting. 730 o No specific pages for authentication is needed. It will be 731 performed automatically, directed by the above setting. 733 o A de-authentication page is also not needed. If the site will 734 have one, put "logout-timeout=0" there. 736 o For all pages for POST requests, it is advisable to have 737 "location-when-logout=". 739 5.1.2. Case 2: specific action required on log-out 741 If the site needs a specific actions upon log-out, the following 742 settings can be used. 744 o All shown in the Case 1 are to be applied. 746 o For all pages, set up the Authentication-Control header "location- 747 when-logout=". 749 o In de-authentication pages, no specific set-up is needed. If 750 there is any direct links to it, put "logout-timeout=0". 752 5.1.3. Case 3: specific page displayed before log-in 754 If the site needs to display a specific page before log-in actions 755 (some announces, user notices, or even advertisements), the following 756 settings can be applied. 758 o Set up an optional authentication to all pages available to guest. 759 Set up an Authentication-Control header with "no-auth=true". Put 760 a link to a specific log-in page in contents. 762 o If there are pages only available to authenticated users, Set up a 763 mandatory authentication with "location-when-unauthenticated=". 766 o For the specific log-in page, Set up a mandatory authentication. 768 o For all pages for POST requests, it is advisable to have 769 "location-when-logout=", too. 771 o De-authentication pages are not needed. If the site will have 772 one, put "logout-timeout=0". 774 5.2. Example 2: authenticated user-only sites 776 If almost all pages in the target site requires authentication (e.g., 777 an Internet banking site), or there are no needs to support both 778 unauthenticated and authenticated users on the same resource, the 779 setting will become somewhat simple. The following are an example to 780 realize such a site: 782 o Set up a mandatory authentication to all pages available to 783 authenticated. Set up an Authentication-Control header with 784 "auth-style=non-modal" setting. 786 o Set up a handler for the 401-status which requests users to 787 authenticate. 789 o For all pages for POST requests, it is advisable to have 790 "location-when-logout=", too. 792 o De-authentication pages are not needed. If the site will have 793 one, put "logout-timeout=0" there. 795 5.3. When to use Cookies 797 In the current Web sites using Form-based authentications, Cookies 798 [RFC6265] are used for managing both authorization and application 799 sessions. Using the extensions in this document, the former features 800 will be provided by using (extended) HTTP authentication/ 801 authorization mechanisms. In some cases, there will be some 802 ambiguous situations whether some functions are authorization 803 management or session management. The following hints will be 804 helpful for deciding which features to be used. 806 o If there is a need to serve multiple sessions for a single user 807 using multiple browsers concurrently, use a Cookie for 808 distinguishing between sessions for the same user. (C.f. if there 809 is a need to distinguish sessions in the same browser, HTML5 Web 810 Storage [W3C.REC-webstorage-20130730] features may be used instead 811 of Cookies.) 813 o If a web site is currently deploying a session time-out feature, 814 consider who benefits from the feature. In most cases, the main 815 requirement for such feature is to protect users from their 816 consoles and browsers hijacked (i.e. benefits are on the users' 817 side). In such cases, the time-out features provided in this 818 extension may be used. On the other hand, the requirements is to 819 protect server's privilege (e.g. when some regulations require to 820 limit the time difference between user's two-factor authentication 821 and financial transaction commitment; the requirement is strictly 822 on the servers' side), that should be managed on the server side 823 using Cookies or other session management mechanisms. 825 5.4. Parallel deployment with Form/Cookie authentications 827 In some transition periods, sites may need to support both HTTP-layer 828 and Form-based authentications. The following example shows one way 829 to achieve that. 831 o If Cookies are used even for HTTP-authenticated users, each 832 session determined by Cookies should identify which authentication 833 are used for the session. 835 o First, set up any of the above settings for enabling HTTP-layer 836 authentication. 838 o For unauthenticated users, put the following things to the Web 839 pages, unless the client supports this extension and HTTP-level 840 authentication. 842 * For non-mandatory authenticated pages, put a link to Form-based 843 authenticated pages. 845 * For mandatory authenticated pages, either put a link to Form- 846 based authenticated pages, or put a HTML-level redirection 847 (using META element) to such pages. 849 o In Form-based authenticated pages, if users are not authenticated, 850 it may have a diversion for HTTP-level authentication by 851 "location-when-unauthenticated" setting. 853 o Users are identified for authorizations and content customization 854 by the following logic. 856 * First, check the result of the HTTP-level authentication. If 857 there is a Cookie session tied to a specific user, both ones 858 should match. 860 * If the user is not authenticated on the HTTP-level, use the 861 conventional Form-based method to determine the user. 863 * If there is a Cookie tied to an HTTP authentication, but there 864 is no corresponding HTTP authentication result, that session 865 will be discarded (because it means that authentication is 866 deactivated by the corresponding user). 868 6. Methods to extend this protocol 870 If a private extension to this protocol is implemented, it MUST use 871 the extension-param to avoid conflicts with this protocol and other 872 future official extensions. 874 When bare-tokens are used in this protocol, these MUST be allocated 875 by IANA. Any tokens used for non-private, non-experimental 876 parameters are RECOMMENDED to be registered to IANA, regardless of 877 the kind of tokens used. 879 Extension-tokens MAY be freely used for any non-standard, private, 880 and/or experimental uses. The extension-tokens MUST be with format 881 "-.", where is a validly 882 registered (sub-)domain name on the Internet owned by the party who 883 defines the extensions. Unknown parameter names are to be ignored 884 regardless of whether it is extension-tokens or bare-tokens. 886 7. IANA Considerations 888 This document defines two new entries for the "Permanent Message 889 Header Field Names" registry. 891 +---------------------------+----------+----------------------------+ 892 | Header Field Name | Protocol | Specification | 893 +---------------------------+----------+----------------------------+ 894 | Optional-WWW-Authenticate | http | Section 3 of this document | 895 | Authentication-Control | http | Section 4 of this document | 896 +---------------------------+----------+----------------------------+ 898 This document also establishes a registry for HTTP authentication 899 control parameters. The registry manages a case-insensitive ASCII 900 strings. The string MUST follow the extensive-token syntax defined 901 in Section 2.2. 903 To acquire registered tokens, a specification for the use of such 904 tokens MUST be available as a publicly-accessible documents, as 905 outlined as "Specification Required" level in [RFC5226]. 907 Registrations for authentication algorithms are required to include a 908 description of the control extension. New registrations are advised 909 to provide the following information: 911 o Token: a token used in HTTP headers for identifying the algorithm. 913 o Specification: A reference for a specification defining the 914 algorithm. 916 The initial content of this registry is as follows: 918 +-------------------------------+------------------------------+ 919 | Token | Specification | 920 +-------------------------------+------------------------------+ 921 | auth-style | Section 4.2 of this document | 922 | location-when-unauthenticated | Section 4.3 of this document | 923 | no-auth | Section 4.4 of this document | 924 | location-when-logout | Section 4.5 of this document | 925 | logout-timeout | Section 4.6 of this document | 926 | username | Section 4.7 of this document | 927 +-------------------------------+------------------------------+ 929 8. Security Considerations 931 The purpose of the log-out timeout feature in the Authentication- 932 control header is to protect users of clients from impersonation 933 caused by an attacker having access to the same console. Server 934 application implementer SHOULD be aware that the directive may always 935 be ignored by either malicious clients or clients not supporting this 936 extension. If the purpose of introducing a timeout for an 937 authentication period is to protect server-side resources, such 938 features MUST be implemented by other means such as HTTP Cookies 939 [RFC6265]. 941 All parameters in Authentication-Control header SHOULD NOT be used 942 for any security-enforcement purposes. Server-side applications MUST 943 be implemented always considering that the header may be either 944 ignored by clients or even bypassed by users. 946 The "username" parameter may reveal sensitive information about the 947 HTTP server and its configurations, useful for security attacks. The 948 use of the "username" parameter SHOULD be limited to cases where the 949 all of the following conditions are met: 951 (1) the valid user name is pre-configured and not modifiable (such 952 as root, admin or similar ones); 954 (2) the valid user name for such an appliance is publicly known (for 955 example, written in a manual); and 957 (3) either the valid user name for the server is easily guessable by 958 other means (for example, from the model number shown in an 959 unauthenticated page), or the server is only accessible from 960 limited networks. 962 Especially, it SHOULD NOT be used in any case when the valid user 963 names are configured by its users or administrators. 965 9. References 967 9.1. Normative References 969 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 970 Requirement Levels", BCP 14, RFC 2119, March 1997. 972 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 973 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 974 May 2008. 976 [RFC5987] Reschke, J., "Character Set and Language Encoding for 977 Hypertext Transfer Protocol (HTTP) Header Field 978 Parameters", RFC 5987, August 2010. 980 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 981 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 982 June 2014. 984 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 985 (HTTP/1.1): Authentication", RFC 7235, June 2014. 987 9.2. Informative References 989 [I-D.ietf-httpauth-mutual] 990 Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, 991 T., and Y. Ioku, "Mutual Authentication Protocol for 992 HTTP", draft-ietf-httpauth-mutual-05 (work in progress), 993 July 2015. 995 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 996 April 2011. 998 [W3C.REC-webstorage-20130730] 999 Hickson, I., "Web Storage", World Wide Web Consortium 1000 Recommendation REC-webstorage-20130730, July 2013, 1001 . 1003 Appendix A. (Informative) Applicability of features for each messages 1005 This section provides cross-reference table about applicability of 1006 each features provided in this specification for each kinds of 1007 responses described in Section 2.1. The table provided in this 1008 section is for informative purposes only. 1010 +-------------------+-------+----------+-----------+------+ 1011 | | init. | success. | intermed. | neg. | 1012 +-------------------+-------+----------+-----------+------+ 1013 | Optional auth. | O | n | N | N | 1014 | auth-style | O | - | - | O | 1015 | loc.-when-unauth. | O | I | I | i | 1016 | no-auth | O | I | I | i | 1017 | loc.-when-logout | - | O | - | - | 1018 | logout-timeout | - | O | - | - | 1019 | username | O | - | - | O | 1020 +-------------------+-------+----------+-----------+------+ 1022 Legends: 1023 O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain 1024 i = SHOULD be ignored; I = MUST be ignored; 1025 - = meaningless (to be ignored) 1027 Appendix B. (Informative) Draft Notes 1029 Things which might be considered for future revisions: 1031 o In [RFC7235], meaning of WWW-Authenticate headers in non-401 1032 responses are defined as "supplying credentials (or different 1033 credentials) might affect the response". This clarification 1034 change leaves a way for using 200-status responses along with a 1035 WWW-Authenticate header for providing optional authentication. 1036 Incorporating this possibility, however, needs more detailed 1037 analysis on the behavior of existing clients and intermediate 1038 proxies for such possibly-confusing responses. Optional-WWW- 1039 Authenticate is safer, at least for minimum backward 1040 compatibility, because clients not supporting this extension will 1041 consider this header as an unrecognized entity-header, possibly 1042 providing opportunity for silently falling-back to application- 1043 level authentications. 1045 Appendix C. (Informative) Draft Change Log 1047 C.1. Changes in Httpauth WG revision 04 1049 o IANA consideration section added. 1051 C.2. Changes in Httpauth WG revision 03 1053 o Adopting RFC 5987 extended syntax for non-ASCII parameter values. 1055 C.3. Changes in Httpauth WG revision 02 1057 o Added realm parameter. 1059 o Added username parameter. We acknowledge Michael Sweet's proposal 1060 for including this to the Basic authentication. 1062 C.4. Changes in Httpauth WG revision 01 1064 o Clarification on peers' responsibility about handling of relative 1065 URLs. 1067 o Automatic reloading should be allowed only on safe methods, not 1068 always on idempotent methods. 1070 C.5. Changes in Httpauth revision 00 and HttpBis revision 00 1072 None. 1074 C.6. Changes in revision 02 1076 o Added usage examples. 1078 C.7. Changes in revision 01 1080 o Syntax notations and parsing semantics changed to match httpbis 1081 style. 1083 C.8. Changes in revision 00 1085 o Separated from HTTP Mutual authentication proposal (-09). 1087 o Adopting httpbis works as a referencing point to HTTP. 1089 o Generalized, now applicable for all HTTP authentication schemes. 1091 o Added "no-auth" and "auth-style" parameters. 1093 o Loosened standardization requirements for parameter-name tokens 1094 registration. 1096 Authors' Addresses 1098 Yutaka Oiwa 1099 National Institute of Advanced Industrial Science and Technology 1100 Information Technology Research Institute 1101 Tsukuba Central 2 1102 1-1-1 Umezono 1103 Tsukuba-shi, Ibaraki 1104 JP 1106 Email: mutual-auth-contact-ml@aist.go.jp 1108 Hajime Watanabe 1109 National Institute of Advanced Industrial Science and Technology 1110 Information Technology Research Institute 1111 Tsukuba Central 2 1112 1-1-1 Umezono 1113 Tsukuba-shi, Ibaraki 1114 JP 1116 Hiromitsu Takagi 1117 National Institute of Advanced Industrial Science and Technology 1118 Information Technology Research Institute 1119 Tsukuba Central 2 1120 1-1-1 Umezono 1121 Tsukuba-shi, Ibaraki 1122 JP 1123 Tatsuya Hayashi 1124 Lepidum Co. Ltd. 1125 #602, Village Sasazuka 3 1126 1-30-3 Sasazuka 1127 Shibuya-ku, Tokyo 1128 JP 1130 Yuichi Ioku 1131 Individual