idnits 2.17.1 draft-ietf-httpauth-extension-02.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 (August 19, 2014) is 3530 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 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-03 Summary: 3 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: February 20, 2015 RISEC, AIST 6 T. Hayashi 7 Lepidum 8 Y. Ioku 9 Individual 10 August 19, 2014 12 HTTP Authentication Extensions for Interactive Clients 13 draft-ietf-httpauth-extension-02 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 February 20, 2015. 46 Copyright Notice 48 Copyright (c) 2014 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. Auth-style parameter . . . . . . . . . . . . . . . . . . . 11 71 4.2. Location-when-unauthenticated parameter . . . . . . . . . 12 72 4.3. No-auth parameter . . . . . . . . . . . . . . . . . . . . 13 73 4.4. Location-when-logout parameter . . . . . . . . . . . . . . 13 74 4.5. Logout-timeout parameter . . . . . . . . . . . . . . . . . 14 75 4.6. Username parameter . . . . . . . . . . . . . . . . . . . . 15 76 5. Usage examples (informative) . . . . . . . . . . . . . . . . . 15 77 5.1. Example 1: a portal site . . . . . . . . . . . . . . . . . 16 78 5.1.1. Case 1: a simple application . . . . . . . . . . . . . 16 79 5.1.2. Case 2: specific action required on log-out . . . . . 16 80 5.1.3. Case 3: specific page displayed before log-in . . . . 17 81 5.2. Example 2: authenticated user-only sites . . . . . . . . . 17 82 5.3. When to use Cookies . . . . . . . . . . . . . . . . . . . 18 83 5.4. Parallel deployment with Form/Cookie authentications . . . 18 84 6. Methods to extend this protocol . . . . . . . . . . . . . . . 19 85 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 86 8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 87 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 88 9.1. Normative References . . . . . . . . . . . . . . . . . . . 21 89 9.2. Informative References . . . . . . . . . . . . . . . . . . 21 90 Appendix A. (Informative) Applicability of features for each 91 messages . . . . . . . . . . . . . . . . . . . . . . 21 92 Appendix B. (Informative) Draft Notes . . . . . . . . . . . . . . 22 93 Appendix C. (Informative) Draft Change Log . . . . . . . . . . . 22 94 C.1. Changes in Httpauth WG revision 02 . . . . . . . . . . . . 22 95 C.2. Changes in Httpauth WG revision 01 . . . . . . . . . . . . 23 96 C.3. Changes in Httpauth revision 00 and HttpBis revision 00 . 23 97 C.4. Changes in revision 02 . . . . . . . . . . . . . . . . . . 23 98 C.5. Changes in revision 01 . . . . . . . . . . . . . . . . . . 23 99 C.6. Changes in revision 00 . . . . . . . . . . . . . . . . . . 23 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 102 1. Introduction 104 The document proposes several extensions to the current HTTP 105 authentication framework, to provide enough functionality comparable 106 with current widely-used form-based Web authentication. A majority 107 of the recent Web-sites on the Internet use custom application-layer 108 authentication implementations using Web forms. The reasons for 109 these may vary, but many people believe that the current HTTP Basic 110 (and Digest, too) authentication method does not have enough 111 functionality (including a good-feeling user interfaces) to support 112 most of realistic Web-based applications. However, the method is 113 very weak against phishing and other attacks, because the whole 114 behavior of the authentication is controlled from the server-side 115 applications. This makes it really hard to implement any 116 cryptographically strong authentication mechanisms into Web systems. 117 To overcome this problem, we need to "modernize" the HTTP 118 authentication framework so that better client-controlled secure 119 methods can be used with Web applications. The extensions proposed 120 in this document include: 122 o non-mandatory, optional authentication on HTTP (Section 3), 124 o log out from both server and client side (Section 4), and 126 o finer control for redirection depending on authentication status 127 (Section 4). 129 [I-D note: These extensions are initially proposed as a part of 130 [I-D.ietf-httpauth-mutual]. However, since these functionalities 131 might possibly be useful in combination even with other 132 authentication schemes, the extensions were separated from the 133 original document as this independent draft.] 135 1.1. Terminology 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 139 "OPTIONAL" in this document are to be interpreted as described in 140 [RFC2119]. 142 The terms "encouraged" and "advised" are used for suggestions that do 143 not constitute "SHOULD"-level requirements. People MAY freely choose 144 not to include the suggested items regarding [RFC2119], but complying 145 with those suggestions would be a best practice; it will improve the 146 security, interoperability, and/or operational performance. 148 This document distinguishes the terms "client" and "user" in the 149 following way: A "client" is an entity understanding and talking HTTP 150 and the specified authentication protocol, usually computer software; 151 a "user" is a (usually natural) person who wants to access data 152 resources using "a client". 154 2. Definitions 156 2.1. Terms for describing authentication protocol flow 158 HTTP Authentication defined in [RFC7235] may involve with several 159 pairs of HTTP requests/responses. Throughout this document, the 160 following terms are used to categorize those messages: for requests, 162 o A non-authenticating request is a request not attempting any 163 authentication: a request without any Authorization header. 165 o An authenticating request is the opposite: a request with an 166 Authorization header. 168 For responses, 170 1) A non-authenticated response: is a response which does not 171 involve with any HTTP authentication. It may not contain any 172 WWW-Authenticate or Authentication-Info header. 174 Servers send this response when the requested resource is not 175 protected by HTTP authentication mechanisms. In context of this 176 specification, not-authentication-related negative responses (e.g. 177 403 and 404) are also considered as non-authenticated responses. 179 (See note on successfully-authenticated responses below for some 180 ambiguous cases.) 182 2) An authentication-initializing response: is a response which 183 requires or allows clients to start authentication attempts. 184 Servers send this response when the requested resource is 185 protected by HTTP authentication mechanism, and the request meets 186 one of the following cases: 188 * The request is non-authenticating request, or 190 * The request contained an authentication trial directed to the 191 protection space (realm) other than the server's expected one. 193 The server will specify the protection space for authentication in 194 this response. 196 Upon reception, the client's behavior is further divided to two 197 possible cases. 199 * If the client may have no prior knowledge on authentication 200 credentials (e.g. a user-name and a password) related to the 201 requested protection space, the protocol flow terminates and 202 the client will ask the user to provide authentication 203 credentials, 205 * On the other hand, if client already have an enough credentials 206 for authentication to the requested protection space, the 207 client will automatically send an authenticating request. Such 208 cases often occur when the client did not know beforehand that 209 the current request-URL requires an authentication. 211 3) A successfully-authenticated response: is a response for an 212 authenticating request meaning that the authentication attempt was 213 granted. (Note: if the authentication scheme used does not use an 214 Authentication-Info header, it may be indistinguishable from a 215 non-authenticated response.) 217 4) An intermediate authenticating response: is a response for an 218 authenticating request which requires some more reaction by the 219 client software without involving users. Such a response is 220 required when an authentication scheme requires two or more round- 221 trip messages to perform authentication, or when an authentication 222 scheme uses some speculative short-cut method (such as uses of 223 cached shared secrets) and it failed. 225 5) A negatively-authenticated response: is a response for an 226 authenticating request which means that the authentication attempt 227 was declined and can not continue without another authentication 228 credential. Clients typically erase memory of the currently-using 229 credentials and ask the user for other ones. 231 Usually the format of these responses are as same as the one for 232 authentication-initializing responses. Client can distinguish it 233 by comparing the protection spaces contained in the request and in 234 the response. 236 Figure 1 shows a state diagram of generic HTTP authentication with 237 the above message categorization. Note that many authentication 238 schemes use only a subset of the transitions described on the 239 diagram. Labels in the figure show the abbreviated names of response 240 types. 242 =========== ----------------- 243 NEW REQUEST ( UNAUTHENTICATED ) 244 =========== ----------------- 245 | ^ non-auth. 246 v | response 247 +----------------------+ NO +-------------+ 248 | The requested URI |--------------------------->| send normal | 249 | known to be auth'ed? | ---------------->| request | 250 +----------------------+ / +-------------+ 251 YES | / initializing| 252 v / | 253 +------------------+ NO / | 254 | Can auth-req.(*1)|--------- | 255 | be constructed? | | 256 +------------------+ | 257 YES | initializing | 258 | ---------------------------------------. | 259 | / v v 260 | | ---------------- NO +-----------+ 261 | | ( AUTH-REQUESTED )<------|credentials| 262 | | ---------------- | known? | 263 v | +-----------+ 264 +-----------+ negative ------------- negative |YES 265 | send |---------->( AUTH-FAILED )<---------, | 266 /| auth-req | ------------- | | 267 / +-----------+\ | v 268 | \ \ intermediate +-----------+ 269 | \ -------------------------------->| send | 270 | \ | auth-req | 271 | non-auth. \successful successful +-----------+ 272 | response (*2) \ / | ^ 273 v \ / | | 274 ----------------- \ -------------- / `----' 275 ( UNAUTHENTICATED ) ----->( AUTH-SUCCEED )<---- intermediate 276 ----------------- -------------- 278 Figure 1: Generic state diagram for HTTP authentication 280 Note: (*1) For example, "Digest" scheme requires server-provided 281 nonces to construct client-side challenges. 282 (*2) In "Basic" and some others, this cannot be distinguished from a 283 successfully-authenticated response. 285 2.2. Syntax Notation 287 This specification uses an extended BNF syntax defined in [RFC7230]. 288 The following syntax definitions are quoted from [RFC7230] and 290 [RFC7235]: auth-scheme, quoted-string, auth-param, SP, header-field, 291 and challenge. It also uses the convention of using header names for 292 specifying syntax of header values. 294 Additionally, this specification uses the following syntax elements 295 following syntax definitions as a refinement for token and the 296 righthand-side of auth-param in [RFC7235]. (Note: these definitions 297 are consistent with those in [I-D.ietf-httpauth-mutual].) 299 bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 300 extension-token = "-" bare-token 1*("." bare-token) 301 extensive-token = bare-token / extension-token 302 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 304 Figure 2: the BNF syntax for common notations 306 Extensive-tokens are used in this protocol where the set of 307 acceptable tokens may include private extensions. Any private 308 extensions of this protocol MUST use the extension-tokens with format 309 "-.", where is a validly registered 310 (sub-)domain name on the Internet owned by the party who defines the 311 extensions. 313 3. Optional Authentication 315 The Optional-WWW-Authenticate header enables a non-mandatory 316 authentication, which is not possible under the current HTTP 317 authentication mechanism. In several Web applications, users can 318 access the same contents as both a guest user and an authenticated 319 user. In most Web applications, it is implemented using HTTP cookies 320 [RFC6265] and custom form-based authentications. The new 321 authentication method using this message will provide a replacement 322 for these authentication systems. 324 Servers MAY send HTTP successful responses (response code 200, 206 325 and others) containing the Optional-WWW-Authenticate header as a 326 replacement of a 401 response when it is an authentication- 327 initializing response. The Optional-WWW-Authenticate header MUST NOT 328 be contained in 401 responses. 330 HTTP/1.1 200 OK 331 Optional-WWW-Authenticate: Basic realm="xxxx" 333 Optional-WWW-Authenticate = 1#challenge 335 Figure 3: BNF syntax for Optional-WWW-Authenticate header 337 The challenges contained in the Optional-WWW-Authenticate header are 338 the same as those for a 401 responses corresponding for a same 339 request. For authentication-related matters, an optional 340 authentication request will have the same meaning as a 401 message 341 with a corresponding WWW-Authenticate header (as an authentication- 342 initializing response). (The behavior for other matters, such as 343 caching, MAY be different between the optional authentication and 401 344 messages.) 346 A response with an Optional-WWW-Authenticate header SHOULD be 347 returned from the server only when the request is either non- 348 authenticated or authenticating to a wrong (not the server's 349 expected) protection space. If a response is either an intermediate 350 or a negative response to a client's authentication attempt, the 351 server MUST respond with a 401 status response with a 352 WWW-Authenticate header instead. Failure to comply this rule will 353 make client not able to distinguish authentication successes and 354 failures. 356 The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate 357 header in a positive response when a client's authentication attempt 358 succeeds. 360 Whenever an authentication scheme support for servers to send some 361 parameter which gives a hint of URL space for the corresponding 362 protection space for the same realm (e.g. "path" or "domain"), 363 servers requesting non-mandatory authentication SHOULD send such 364 parameter with the response. Clients supporting non-mandatory 365 authentication MUST recognize the parameter, and MUST send a request 366 with an appropriate authentication credential in an Authorization 367 header for any URI inside the specified paths. 369 Support of this header is OPTIONAL; Clients MAY also choose any set 370 of authentication schemes for which optional authentication is 371 supported (in other words, its support MAY be scheme-dependent). 372 However, some authentication schemes MAY require mandatory/ 373 recommended support for this header, so that server-side applications 374 MAY assume that clients supporting such schemes are likely to support 375 the extension as well. 377 4. Authentication-Control header 379 Authentication-Control = 1#Auth-Control-Entry 380 Auth-Control-Entry = auth-scheme 1*SP 1#auth-param 382 Figure 4: the BNF syntax for the Authentication-Control header 384 The Authentication-Control header provides a more precise control of 385 the client behavior for Web applications using an HTTP authentication 386 protocol. This header is supposed to be generated in the application 387 layer, as opposed to WWW-Authenticate headers which will be generated 388 usually by the Web servers. 390 Support of this header is OPTIONAL, and clients MAY choose any subset 391 of these parameters to be supported. The set of supported parameters 392 MAY also be authentication scheme-dependent. However, some 393 authentication schemes MAY require mandatory/recommended support for 394 some or all of the features provided in this header. 396 The Authentication-Control header contains one or more 397 "authentication control entries" each of which corresponds to a 398 single realm for a specific authentication scheme. If the 399 auth-scheme specified for an entry supports the HTTP "realm" feature, 400 that entry MUST contain the "realm" parameter. If not, the entry 401 MUST NOT contain the "realm" parameter. 403 Among the multiple entries in the header, the meaningful entries in 404 the header are those corresponding to an auth-scheme and a realm (if 405 any), for which "the authentication process is being performed, or 406 going to be performed". In more detail, 408 (1) If the response is either an authentication-initializing 409 response or a negatively-authenticated response, there may be 410 multiple challenges in the WWW-Authenticate (or Optional-WWW- 411 Authenticate defined in this extension) header, each of which 412 corresponds to a different scheme and realm. The client will 413 determine the scheme and realm to perform an authentication, and 414 the entries corresponding to the chosen scheme and realm will be 415 meaningful. 417 (2) If the response is either an intermediate authenticating 418 response or a successfully-authenticated response, the scheme 419 and a realm given in the Authorization header of the HTTP 420 request will determine the currently-ongoing authentication 421 process. Only the entries correspond to that scheme and realm 422 are meaningful. 424 The server MAY send an Authentication-Control header containing non- 425 meaningful entries. The client MUST ignore all non-meaningful 426 entries it received. 428 Each entry contains one or more parameters, each of which is a name- 429 value pair. The name of each parameter MUST be an extensive-token. 430 Clients MUST ignore any unknown parameters contained in this header. 431 The entries for the same auth-scheme and the realm MUST NOT contain 432 the duplicated parameters for the same name. 434 The type of parameter value depends on the parameter name as defined 435 in the following subsections. Regardless of the type, however, the 436 recipients SHOULD accept both quoted and unquoted representations of 437 values as defined in HTTP. If it is defined as a string, it is 438 encouraged to be sent in a quoted-string form. If it defined as a 439 token (or similar) or an integer, the value SHOULD follow the 440 corresponding ABNF syntax after possible unquoting of the quoted- 441 string value (as defined in HTTP), and is encouraged to be sent in a 442 unquoted form. 444 Server-side application SHOULD always be reminded that any parameters 445 contained in this header MAY be ignored by clients. Also, even when 446 a client accepts this header, users may always be able to circumvent 447 semantics of this header. Therefore, if this header is used for 448 security purposes, its use MUST be limited for providing some non- 449 fundamental additional security measures valuable for end-users (such 450 as client-side log-out for protecting against console takeover). 451 Server-side application MUST NOT rely on the use of this header for 452 protecting server-side resources. 454 Note: The header syntax allows servers to specify Authentication- 455 Control for multiple authentication schemes, either as multiple 456 occurances of this header or as a combined single header (see Section 457 3.2.2 of [RFC7230] for rationale). The same care as for parsing 458 multiple authnetication challenges SHALL be taken. 460 4.1. Auth-style parameter 462 Authentication-Control: Digest realm="protected space", 463 auth-style=modal 465 The parameter "auth-style" specifies the server's preferences over 466 user interface behavior for user authentication. This parameter can 467 be included in any kind of responses, however, it is only meaningful 468 for either authentication-initializing or negatively-authenticated 469 responses. The value of this parameter MUST be one of the bare- 470 tokens "modal" or "non-modal". When the Optional-WWW-Authenticate 471 header is used, the value of this parameter MUST be disregarded and 472 the value "non-modal" is implied. 474 The value "modal" means that the server thinks the content of the 475 response (body and other content-related headers) is valuable only 476 for users refusing authentication request. The clients are expected 477 to ask the user a password before processing the content. This 478 behavior is common for most of the current implementations of Basic 479 and Digest authentication schemes. 481 The value "non-modal" means that the server thinks the content of the 482 response (body and other content-related headers) is valuable for 483 users before processing an authentication request. The clients are 484 expected to first process the content and then provide users 485 opportunities to perform authentication. 487 The default behavior for the clients is implementation-dependent, and 488 clients MAY choose different defaults for different authentication 489 schemes. The proposed default behavior is "modal" for all 490 authentication schemes, but specifications for authentication schemes 491 MAY propose a different default. 493 The above two different methods of authentication may introduce a 494 observable difference of semantics when the response contains state- 495 changing side effects; for example, it may change whether Cookie 496 headers [RFC6265] in 401 responses are processed or not. However, 497 the server applications SHOULD NOT depend on both existence and non- 498 existence of such side effects. 500 4.2. Location-when-unauthenticated parameter 502 Authentication-Control: Mutual realm="auth-space-1", 503 location-when-unauthenticated="http://www.example.com/login.html" 505 The parameter "location-when-unauthenticated" specifies a location 506 where any unauthenticated clients should be redirected to. This 507 header may be used, for example, when there is a central login page 508 for the entire Web application. The value of this parameter is a 509 string that contains an absolute URL location. Senders MUST always 510 send an absolute URL location. If a received URL is not absolute, 511 the clients SHOULD either ignore it or consider it a relative URL 512 from the current location. 514 This parameter MAY be used with a 401 response for authentication- 515 initializing response. It can also be contained, although 516 NOT RECOMMENDED, in a positive response with an 517 Optional-WWW-Authenticate header. The clients MUST ignore this 518 parameter, when a response is either successfully-authenticated or 519 intermediately-authenticated. The clients SHOULD ignore this 520 parameter when a response is a negatively-authenticated one (the case 521 is unlikely to happen, though). 523 When a client receives an authentication-initiating response with 524 this parameter, if the client has to ask users for authentication 525 credentials, the client will treat the entire response as if it were 526 a 303 "See Other" response with a Location header that contains the 527 value of this parameter (i.e., client will be redirected to the 528 specified location with a GET request). Unlike a normal 303 529 response, if the client can process authentication without the user's 530 interaction, this parameter MUST be ignored. 532 4.3. No-auth parameter 534 Authentication-Control: Basic realm="entrance", no-auth=true 536 The parameter "no-auth" is a variant of the 537 location-when-unauthenticated parameter; it specifies that new 538 authentication attempt is not to be performed on this location for 539 better user experience, without specifying the redirection on the 540 HTTP level. This header may be used, for example, when there is a 541 central login page for the entire Web application, and when a (Web 542 content's level) explicit interaction of users is desired before 543 authentications. The value of this parameter MUST be a token "true". 544 If the value is incorrect, client MAY ignore this parameter. 546 This parameter MAY be used with authentication-initiating responses. 547 It can also be contained, although NOT RECOMMENDED, in a positive 548 response with an Optional-WWW-Authenticate header. The clients MUST 549 ignore this parameter, when a response is either successfully- 550 authenticated or intermediately-authenticated. The clients SHOULD 551 ignore this parameter when a response is a negatively-authenticated 552 one (the case is unlikely to happen, though). 554 When a client receives an authentication-initiating response with 555 this parameter, if the client has to ask users for authentication 556 credentials, the client will ignore the WWW-Authenticate header 557 contained in the response and treat the whole response as a normal 558 negative 4xx-class response instead of giving user an opportunity to 559 start authentication. If the client can process authentication 560 without the user's interaction, this parameter MUST ignored. 562 This parameter SHOULD NOT be used along with the 563 location-when-unauthenticated parameter. If both were supplied, 564 clients MAY choose which one is to be honored. 566 This parameter SHOULD NOT be used as any security measures to prevent 567 authentication attempts, as it is easily circumvented by users. This 568 parameter SHOULD be used solely for improving user experience of web 569 applications. 571 4.4. Location-when-logout parameter 573 Authentication-Control: Digest realm="protected space", 574 location-when-logout="http://www.example.com/byebye.html" 576 The parameter "location-when-logout" specifies a location where the 577 client is to be redirected when the user explicitly request a logout. 578 The value of this parameter MUST be a string that contains an 579 absolute URL location. If a given URL is not absolute, the clients 580 MAY consider it a relative URL from the current location. 582 This parameter MAY be used with successfully-authenticated responses. 583 If this parameter is contained in other kinds of responses, the 584 clients MUST ignore this parameter. 586 When the user requests to terminate an authentication period, and if 587 the client currently displays a page supplied by a response with this 588 parameter, the client will be redirected to the specified location by 589 a new GET request (as if it received a 303 response). The log-out 590 operation (e.g. erasing memories of user name, authentication 591 credential and all related one-time credentials such as nonce or 592 keys) SHOULD occur before processing a redirection. 594 When the user requests to terminate an authentication period, if the 595 client supports this parameter but the server response does not 596 contain this parameter, the client's RECOMMENDED behavior is as 597 follows: if the request corresponding to the current content was safe 598 (e.g. GET), reload the page without the authentication credential. 599 If the request was non-idempotent (e.g. POST), keep the current 600 content as-is and simply forget the authentication status. The 601 client SHOULD NOT replay a non-idempotent request without the user's 602 explicit approval. 604 Web applications are encouraged to send this parameter with an 605 appropriate value for any responses (except those with redirection 606 (3XX) statuses) for non-GET requests. 608 4.5. Logout-timeout parameter 610 Authentication-Control: Basic realm="entrance", logout-timeout=300 612 The parameter "logout-timeout", when contained in a successfully- 613 authenticated response, means that any authentication credentials and 614 states related to the current protection space are to be discarded if 615 a time specified in this header (in seconds) has been passed from the 616 time received. The value MUST be an integer. As a special case, the 617 value 0 means that the client is requested to immediately log-out 618 from the current authentication space and revert to an 619 unauthenticated status. This does not, however, mean that the long- 620 term memories for the passwords (such as the password reminders and 621 auto fill-ins) should be removed. If a new timeout value is received 622 for the same authentication space, it cancels the previous timeout 623 and sets a new timeout. 625 4.6. Username parameter 627 Authentication-Control: Basic realm="configuration", username="admin" 629 The parameter "username" tells that the only "user name" to be 630 accepted by the server is the value given in this parameter. This 631 parameter is particularly useful, for example, for routers and other 632 appliances with a Web configuration interface. 634 This parameter MAY be used with authentication-initiating responses 635 or negatively-authenticated responses requiring another attempt of 636 authentication. The clients MUST ignore this parameter, when a 637 response is either successfully-authenticated or intermediately- 638 authenticated. 640 If the authentication scheme to be used has syntax limitation on the 641 allowed user names (e.g. Basic and Digest do not allow colons in 642 user names), the specified value MUST follow that limitation. Client 643 SHOULD ignore any values which do not conform to such limitations. 645 Clients MAY still send any authentication requests with other user 646 names, possibly in vain. Servers are not strictly required to reject 647 user names other than specified, but doing it will give bad user 648 experiences and may confuse users and clients. 650 5. Usage examples (informative) 652 This section shows some examples for applying this extension to 653 typical Web-sites which are using Forms and cookies for managing 654 authentication and authorization. The content of this section is not 655 normative and for illustrative purposes only. 657 We assume that all features described in the previous sections are 658 implemented in clients (Web browsers). We also assume that browsers 659 will have a user interface which allows users to deactivate (log-out 660 from) current authentication sessions. If this assumption is not 661 hold, texts below provides another approach with de-authentication 662 pages used instead of such a UI. 664 Without explicit notices, all settings described below are to be 665 applied with Authentication-Control headers, and these can be sent to 666 clients regardless of authentication statuses (these will be silently 667 ignored whenever not effective). 669 5.1. Example 1: a portal site 671 This subsection provides an example application for a site whose 672 structure is somewhat similar to conventional portal sites. In 673 particular, most of web pages are available for guest 674 (unauthenticated) users, and if authentication is performed, contents 675 of these pages are customized for each user. We assume the site has 676 the following kinds of pages currently: 678 o Content pages. 680 o Pages/mechanism for performing authentication: 682 * There is one page which asks a user name and a password using a 683 HTML POST form. 685 * After the authentication attempt, the user will be redirected 686 to either the page which is previously displayed before the 687 authentication, or some specific page. 689 o A de-authentication (log-out) page. 691 5.1.1. Case 1: a simple application 693 When such a site does not need a specific actions upon log-in and 694 log-out, the following simple settings can be used. 696 o Set up an optional authentication to all pages available to 697 guests. Set up an Authentication-Control header with "auth- 698 style=non-modal" setting. 700 o If there are pages only available to authenticated users, Set up a 701 mandatory authentication with "auth-style=non-modal" setting. 703 o No specific pages for authentication is needed. It will be 704 performed automatically, directed by the above setting. 706 o A de-authentication page is also not needed. If the site will 707 have one, put "logout-timeout=0" there. 709 o For all pages for POST requests, it is advisable to have 710 "location-when-logout=". 712 5.1.2. Case 2: specific action required on log-out 714 If the site needs a specific actions upon log-out, the following 715 settings can be used. 717 o All shown in the Case 1 are to be applied. 719 o For all pages, set up the Authentication-Control header "location- 720 when-logout=". 722 o In de-authentication pages, no specific set-up is needed. If 723 there is any direct links to it, put "logout-timeout=0". 725 5.1.3. Case 3: specific page displayed before log-in 727 If the site needs to display a specific page before log-in actions 728 (some announces, user notices, or even advertisements), the following 729 settings can be applied. 731 o Set up an optional authentication to all pages available to guest. 732 Set up an Authentication-Control header with "no-auth=true". Put 733 a link to a specific log-in page in contents. 735 o If there are pages only available to authenticated users, Set up a 736 mandatory authentication with "location-when-unauthenticated=". 739 o For the specific log-in page, Set up a mandatory authentication. 741 o For all pages for POST requests, it is advisable to have 742 "location-when-logout=", too. 744 o De-authentication pages are not needed. If the site will have 745 one, put "logout-timeout=0". 747 5.2. Example 2: authenticated user-only sites 749 If almost all pages in the target site requires authentication (e.g., 750 an Internet banking site), or there are no needs to support both 751 unauthenticated and authenticated users on the same resource, the 752 setting will become somewhat simple. The following are an example to 753 realize such a site: 755 o Set up a mandatory authentication to all pages available to 756 authenticated. Set up an Authentication-Control header with 757 "auth-style=non-modal" setting. 759 o Set up a handler for the 401-status which requests users to 760 authenticate. 762 o For all pages for POST requests, it is advisable to have 763 "location-when-logout=", too. 765 o De-authentication pages are not needed. If the site will have 766 one, put "logout-timeout=0" there. 768 5.3. When to use Cookies 770 In the current Web sites using Form-based authentications, Cookies 771 [RFC6265] are used for managing both authorization and application 772 sessions. Using the extensions in this document, the former features 773 will be provided by using (extended) HTTP authentication/ 774 authorization mechanisms. In some cases, there will be some 775 ambiguous situations whether some functions are authorization 776 management or session management. The following hints will be 777 helpful for deciding which features to be used. 779 o If there is a need to serve multiple sessions for a single user 780 using multiple browsers concurrently, use a Cookie for 781 distinguishing between sessions for the same user. (C.f. if there 782 is a need to distinguish sessions in the same browser, HTML5 Web 783 Storage [W3C.REC-webstorage-20130730] features may be used instead 784 of Cookies.) 786 o If a web site is currently deploying a session time-out feature, 787 consider who benefits from the feature. In most cases, the main 788 requirement for such feature is to protect users from their 789 consoles and browsers hijacked (i.e. benefits are on the users' 790 side). In such cases, the time-out features provided in this 791 extension may be used. On the other hand, the requirements is to 792 protect server's privilege (e.g. when some regulations require to 793 limit the time difference between user's two-factor authentication 794 and financial transaction commitment; the requirement is strictly 795 on the servers' side), that should be managed on the server side 796 using Cookies or other session management mechanisms. 798 5.4. Parallel deployment with Form/Cookie authentications 800 In some transition periods, sites may need to support both HTTP-layer 801 and Form-based authentications. The following example shows one way 802 to achieve that. 804 o If Cookies are used even for HTTP-authenticated users, each 805 session determined by Cookies should identify which authentication 806 are used for the session. 808 o First, set up any of the above settings for enabling HTTP-layer 809 authentication. 811 o For unauthenticated users, put the following things to the Web 812 pages, unless the client supports this extension and HTTP-level 813 authentication. 815 * For non-mandatory authenticated pages, put a link to Form-based 816 authenticated pages. 818 * For mandatory authenticated pages, either put a link to Form- 819 based authenticated pages, or put a HTML-level redirection 820 (using META element) to such pages. 822 o In Form-based authenticated pages, if users are not authenticated, 823 it may have a diversion for HTTP-level authentication by 824 "location-when-unauthenticated" setting. 826 o Users are identified for authorizations and content customizations 827 by the following logic. 829 * First, check the result of the HTTP-level authentication. If 830 there is a Cookie session tied to a specific user, both ones 831 should match. 833 * If the user is not authenticated on the HTTP-level, use the 834 conventional Form-based method to determine the user. 836 * If there is a Cookie tied to an HTTP authentication, but there 837 is no corresponding HTTP authentication result, that session 838 will be discarded (because it means that authentication is 839 deactivated by the corresponding user). 841 6. Methods to extend this protocol 843 If a private extension to this protocol is implemented, it MUST use 844 the extension-param to avoid conflicts with this protocol and other 845 future official extensions. 847 Extension-tokens MAY be freely used for any non-standard, private, 848 and/or experimental uses. The extension-tokens MUST be with format 849 "-.", where is a validly 850 registered (sub-)domain name on the Internet owned by the party who 851 defines the extensions. Unknown parameter names are to be ignored 852 regardless of whether it is extension-tokens or bare-tokens. 854 7. IANA Considerations 856 The header "Optional-WWW-Authenticate" and "Authentication-Control" 857 should be registered to IANA registry appropriately (TO-DO). 859 Tokens used for the authentication control parameters may be either 860 extension-tokens or bare-tokens as outlined in Section 2.2. When 861 bare-tokens are used in this protocol, these MUST be allocated by 862 IANA. Any tokens used for non-private, non-experimental parameters 863 are RECOMMENDED to be registered to IANA, regardless of the kind of 864 tokens used. 866 To acquire registered tokens, a specification for the use of such 867 tokens MUST be available as a publicly-accessible documents, as 868 outlined as "Specification Required" level in [RFC5226]. 870 Note: More formal declarations will be added in the future drafts to 871 meet the RFC 5226 requirements. 873 8. Security Considerations 875 The purpose of the log-out timeout feature in the Authentication- 876 control header is to protect users of clients from impersonation 877 caused by an attacker having access to the same console. Server 878 application implementors SHOULD be aware that the directive may 879 always be ignored by either malicious clients or clients not 880 supporting this extension. If the purpose of introducing a timeout 881 for an authentication period is to protect server-side resources, 882 such features MUST be implemented by other means such as HTTP Cookies 883 [RFC6265]. 885 All parameters in Authentication-Control header SHOULD NOT be used 886 for any security-enforcement purposes. Server-side applications MUST 887 be implemented always considering that the header may be either 888 ignored by clients or even bypassed by users. 890 The "username" parameter may reveal sensitive information about the 891 HTTP server and its configurations, useful for security attacks. The 892 use of the "username" parameter SHOULD be limited to cases where the 893 all of the following conditions are met: 895 (1) the valid user name is pre-configured and not modifiable (such 896 as root, admin or similar ones); 898 (2) the valid user name for such an appliance is publicly known (for 899 example, written in a manual); and 901 (3) either the valid user name for the server is easily guessable by 902 other means (for example, from the model number shown in an 903 unauthenticated page), or the server is only accesible from 904 limited networks. 906 Especially, it SHOULD NOT be used in any case when the valid user 907 names are configured by its users or administrators. 909 9. References 911 9.1. Normative References 913 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 914 Requirement Levels", BCP 14, RFC 2119, March 1997. 916 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 917 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 918 May 2008. 920 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 921 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 922 June 2014. 924 [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 925 (HTTP/1.1): Authentication", RFC 7235, June 2014. 927 9.2. Informative References 929 [I-D.ietf-httpauth-mutual] 930 Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, 931 T., and Y. Ioku, "Mutual Authentication Protocol for 932 HTTP", draft-ietf-httpauth-mutual-03 (work in progress), 933 August 2014. 935 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 936 April 2011. 938 [W3C.REC-webstorage-20130730] 939 Hickson, I., "Web Storage", World Wide Web Consortium 940 Recommendation REC-webstorage-20130730, July 2013, 941 . 943 Appendix A. (Informative) Applicability of features for each messages 945 This section provides cross-reference table about applicability of 946 each features provided in this specification for each kinds of 947 responses described in Section 2.1. The table provided in this 948 section is for informative purposes only. 950 +-------------------+-------+----------+-----------+------+ 951 | | init. | success. | intermed. | neg. | 952 +-------------------+-------+----------+-----------+------+ 953 | Optional auth. | O | n | N | N | 954 | auth-style | O | - | - | O | 955 | loc.-when-unauth. | O | I | I | i | 956 | no-auth | O | I | I | i | 957 | loc.-when-logout | - | O | - | - | 958 | logout-timeout | - | O | - | - | 959 | username | O | - | - | O | 960 +-------------------+-------+----------+-----------+------+ 962 Legends: 963 O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain 964 i = SHOULD be ignored; I = MUST be ignored; 965 - = meaningless (to be ignored) 967 Appendix B. (Informative) Draft Notes 969 Things which might be considered for future revisions: 971 o In [RFC7235], meaning of WWW-Authenticate headers in non-401 972 responses are defined as "supplying credentials (or different 973 credentials) might affect the response". This clarification 974 change leaves a way for using 200-status responses along with a 975 WWW-Authenticate header for providing optional authentication. 976 Incorporating this possibility, however, needs more detailed 977 analysis on the behavior of existing clients and intermediate 978 proxies for such possibly-confusing responses. Optional-WWW- 979 Authenticate is safer, at least for minimum backward 980 compatibility, because clients not supporting this extension will 981 consider this header as an unrecognized entity-header, possibly 982 providing opportunity for silently falling-back to application- 983 level authentications. 985 Appendix C. (Informative) Draft Change Log 987 C.1. Changes in Httpauth WG revision 02 989 o Added realm parameter. 991 o Added username parameter. We acknowledge Michael Sweet's proposal 992 for including this to the Basic authentication. 994 C.2. Changes in Httpauth WG revision 01 996 o Clarification on peers' responsibility about handling of relative 997 URLs. 999 o Automatic reloading should be allowed only on safe methods, not 1000 always on idempotent methods. 1002 C.3. Changes in Httpauth revision 00 and HttpBis revision 00 1004 None. 1006 C.4. Changes in revision 02 1008 o Added usage examples. 1010 C.5. Changes in revision 01 1012 o Syntax notations and parsing semantics changed to match httpbis 1013 style. 1015 C.6. Changes in revision 00 1017 o Separated from HTTP Mutual authentication proposal (-09). 1019 o Adopting httpbis works as a referencing point to HTTP. 1021 o Generalized, now applicable for all HTTP authentication schemes. 1023 o Added "no-auth" and "auth-style" parameters. 1025 o Loosened standardization requirements for parameter-name tokens 1026 registration. 1028 Authors' Addresses 1030 Yutaka Oiwa 1031 National Institute of Advanced Industrial Science and Technology 1032 Research Institute for Secure Systems 1033 3-11-46 Nakouji 1034 Amagasaki, Hyogo 1035 JP 1037 Email: mutual-auth-contact-ml@aist.go.jp 1038 Hajime Watanabe 1039 National Institute of Advanced Industrial Science and Technology 1040 Research Institute for Secure Systems 1041 Tsukuba Central 2 1042 1-1-1 Umezono 1043 Tsukuba-shi, Ibaraki 1044 JP 1046 Hiromitsu Takagi 1047 National Institute of Advanced Industrial Science and Technology 1048 Research Institute for Secure Systems 1049 Tsukuba Central 2 1050 1-1-1 Umezono 1051 Tsukuba-shi, Ibaraki 1052 JP 1054 Tatsuya Hayashi 1055 Lepidum Co. Ltd. 1056 #602, Village Sasazuka 3 1057 1-30-3 Sasazuka 1058 Shibuya-ku, Tokyo 1059 JP 1061 Yuichi Ioku 1062 Individual