idnits 2.17.1 draft-ietf-httpauth-extension-01.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 (October 21, 2013) is 3832 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 ---------------------------------------------------------------------------- == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-24 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-24 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-11) exists of draft-ietf-httpauth-mutual-01 Summary: 1 error (**), 0 flaws (~~), 4 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: April 24, 2014 RISEC, AIST 6 T. Hayashi 7 Lepidum 8 Y. Ioku 9 Individual 10 October 21, 2013 12 HTTP Authentication Extensions for Interactive Clients 13 draft-ietf-httpauth-extension-01 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 April 24, 2014. 46 Copyright Notice 48 Copyright (c) 2013 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 . . . . . . . . . 11 72 4.3. No-auth parameter . . . . . . . . . . . . . . . . . . . . 12 73 4.4. Location-when-logout parameter . . . . . . . . . . . . . . 13 74 4.5. Logout-timeout . . . . . . . . . . . . . . . . . . . . . . 14 75 5. Usage examples (informative) . . . . . . . . . . . . . . . . . 14 76 5.1. Example 1: a portal site . . . . . . . . . . . . . . . . . 14 77 5.1.1. Case 1: a simple application . . . . . . . . . . . . . 15 78 5.1.2. Case 2: specific action required on log-out . . . . . 15 79 5.1.3. Case 3: specific page displayed before log-in . . . . 16 80 5.2. Example 2: authenticated user-only sites . . . . . . . . . 16 81 5.3. When to use Cookies . . . . . . . . . . . . . . . . . . . 16 82 5.4. Parallel deployment with Form/Cookie authentications . . . 17 83 6. Methods to extend this protocol . . . . . . . . . . . . . . . 18 84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 85 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 87 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19 88 9.2. Informative References . . . . . . . . . . . . . . . . . . 20 89 Appendix A. (Informative) Applicability of features for each 90 messages . . . . . . . . . . . . . . . . . . . . . . 20 91 Appendix B. (Informative) Draft Notes . . . . . . . . . . . . . . 20 92 Appendix C. (Informative) Draft Change Log . . . . . . . . . . . 21 93 C.1. Changes in Httpauth WG revision 01 . . . . . . . . . . . . 21 94 C.2. Changes in Httpauth revision 00 and HttpBis revision 00 . 21 95 C.3. Changes in revision 02 . . . . . . . . . . . . . . . . . . 21 96 C.4. Changes in revision 01 . . . . . . . . . . . . . . . . . . 21 97 C.5. Changes in revision 00 . . . . . . . . . . . . . . . . . . 21 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22 100 1. Introduction 102 The document proposes several extensions to the current HTTP 103 authentication framework, to provide enough functionality comparable 104 with current widely-used form-based Web authentication. A majority 105 of the recent Web-sites on the Internet use custom application-layer 106 authentication implementations using Web forms. The reasons for 107 these may vary, but many people believe that the current HTTP Basic 108 (and Digest, too) authentication method does not have enough 109 functionality (including a good-feeling user interfaces) to support 110 most of realistic Web-based applications. However, the method is 111 very weak against phishing and other attacks, because the whole 112 behavior of the authentication is controlled from the server-side 113 applications. This makes it really hard to implement any 114 cryptographically strong authentication mechanisms into Web systems. 115 To overcome this problem, we need to "modernize" the HTTP 116 authentication framework so that better client-controlled secure 117 methods can be used with Web applications. The extensions proposed 118 in this document include: 120 o non-mandatory, optional authentication on HTTP (Section 3), 122 o log out from both server and client side (Section 4), and 124 o finer control for redirection depending on authentication status 125 (Section 4). 127 [I-D note: These extensions are initially proposed as a part of 128 [I-D.ietf-httpauth-mutual]. However, since these functionalities 129 might possibly be useful in combination even with other 130 authentication schemes, the extensions were separated from the 131 original document as this independent draft.] 133 1.1. Terminology 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 137 "OPTIONAL" in this document are to be interpreted as described in 138 [RFC2119]. 140 The terms "encouraged" and "advised" are used for suggestions that do 141 not constitute "SHOULD"-level requirements. People MAY freely choose 142 not to include the suggested items regarding [RFC2119], but complying 143 with those suggestions would be a best practice; it will improve the 144 security, interoperability, and/or operational performance. 146 This document distinguishes the terms "client" and "user" in the 147 following way: A "client" is an entity understanding and talking HTTP 148 and the specified authentication protocol, usually computer software; 149 a "user" is a (usually natural) person who wants to access data 150 resources using "a client". 152 2. Definitions 154 2.1. Terms for describing authentication protocol flow 156 HTTP Authentication defined in [I-D.ietf-httpbis-p7-auth] may involve 157 with several pairs of HTTP requests/responses. Throughout this 158 document, the following terms are used to categorize those messages: 159 for requests, 161 o A non-authenticating request is a request not attempting any 162 authentication: a request without any Authorization header. 164 o An authenticating request is the opposite: a request with an 165 Authorization header. 167 For responses, 169 1) A non-authenticated response: is a response which does not 170 involve with any HTTP authentication. It may not contain any 171 WWW-Authenticate or Authentication-Info header. 173 Servers send this response when the requested resource is not 174 protected by HTTP authentication mechanisms. In context of this 175 specification, not-authentication-related negative responses (e.g. 176 403 and 404) are also considered as non-authenticated responses. 178 (See note on successfully-authenticated responses below for some 179 ambiguous cases.) 181 2) An authentication-initializing response: is a response which 182 requires or allows clients to start authentication attempts. 183 Servers send this response when the requested resource is 184 protected by HTTP authentication mechanism, and the request meets 185 one of the following cases: 187 * The request is non-authenticating request, or 189 * The request contained an authentication trial directed to the 190 protection space (realm) other than the server's expected one. 192 The server will specify the protection space for authentication in 193 this response. 195 Upon reception, the client's behavior is further divided to two 196 possible cases. 198 * If the client may have no prior knowledge on authentication 199 credentials (e.g. a user-name and a password) related to the 200 requested protection space, the protocol flow terminates and 201 the client will ask the user to provide authentication 202 credentials, 204 * On the other hand, if client already have an enough credentials 205 for authentication to the requested protection space, the 206 client will automatically send an authenticating request. Such 207 cases often occur when the client did not know beforehand that 208 the current request-URL requires an authentication. 210 3) A successfully-authenticated response: is a response for an 211 authenticating request meaning that the authentication attempt was 212 granted. (Note: if the authentication scheme used does not use an 213 Authentication-Info header, it may be indistinguishable from a 214 non-authenticated response.) 216 4) An intermediate authenticating response: is a response for an 217 authenticating request which requires some more reaction by the 218 client software without involving users. Such a response is 219 required when an authentication scheme requires two or more round- 220 trip messages to perform authentication, or when an authentication 221 scheme uses some speculative short-cut method (such as uses of 222 cached shared secrets) and it failed. 224 5) A negatively-authenticated response: is a response for an 225 authenticating request which means that the authentication attempt 226 was declined and can not continue without another authentication 227 credential. Clients typically erase memory of the currently-using 228 credentials and ask the user for other ones. 230 Usually the format of these responses are as same as the one for 231 authentication-initializing responses. Client can distinguish it 232 by comparing the protection spaces contained in the request and in 233 the response. 235 Figure 1 shows a state diagram of generic HTTP authentication with 236 the above message categorization. Note that many authentication 237 schemes uses only a subset of the transitions described on the 238 diagram. Labels in the figure show the abbreviated names of response 239 types. 241 =========== ----------------- 242 NEW REQUEST ( UNAUTHENTICATED ) 243 =========== ----------------- 244 | ^ non-auth. 245 v | response 246 +----------------------+ NO +-------------+ 247 | The requested URI |--------------------------->| send normal | 248 | known to be auth'ed? | ---------------->| request | 249 +----------------------+ / +-------------+ 250 YES | / initializing| 251 v / | 252 +------------------+ NO / | 253 | Can auth-req (*1)|--------- | 254 | be constructed? | | 255 +------------------+ | 256 YES | initializing | 257 | ---------------------------------------. | 258 | / v v 259 | | ---------------- NO +-----------+ 260 | | ( AUTH-REQUESTED )<------|credentials| 261 | | ---------------- | known? | 262 v | +-----------+ 263 +-----------+ negative ------------- negative |YES 264 | send |---------->( AUTH-FAILED )<---------, | 265 /| auth-req | ------------- | | 266 / +-----------+\ | v 267 | \ \ intermediate +-----------+ 268 | \ -------------------------------->| send | 269 | \ | auth-req | 270 | non-auth. \successful successful +-----------+ 271 | response (*2) \ / | ^ 272 v \ / | | 273 ----------------- \ -------------- / `----' 274 ( UNAUTHENTICATED ) ----->( AUTH-SUCCEED )<---- intermediate 275 ----------------- -------------- 277 Figure 1: Generic state diagram for HTTP authentication 279 Note: (*1) For example, "Digest" scheme requires server-provided 280 nonces to construct client-side challenges. 281 (*2) In "Basic" and some others, this cannot be distinguished from a 282 successfully-authenticated response. 284 2.2. Syntax Notation 286 This specification uses an extended BNF syntax defined in 287 [I-D.ietf-httpbis-p1-messaging]. The following syntax definitions 288 are quoted from [I-D.ietf-httpbis-p1-messaging] and 289 [I-D.ietf-httpbis-p7-auth]: auth-scheme, quoted-string, auth-param, 290 SP, header-field, and challenge. It also uses the convention of 291 using header names for specifying syntax of header values. 293 Additionally, this specification uses the following syntax elements 294 following syntax definitions as a refinement for token and the 295 righthand-side of auth-param in [I-D.ietf-httpbis-p7-auth]. (Note: 296 these definitions are consistent with those in 297 [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 = challenge 335 Figure 3: BNF syntax for Optional-WWW-Authenticate header 337 The challenge 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 378 Authentication-Control = auth-scheme 1*SP 1#auth-param 380 Figure 4: the BNF syntax for the Authentication-Control header 382 The Authentication-Control header provides a more precise control of 383 the client behavior for Web applications using an HTTP authentication 384 protocol. This header is supposed to be generated in the application 385 layer, as opposed to WWW-Authenticate headers which will be generated 386 usually by the Web servers. 388 Support of this header is OPTIONAL, and clients MAY choose any subset 389 of these parameters to be supported. The set of supported parameters 390 MAY also be authentication scheme-dependent. However, some 391 authentication schemes MAY require mandatory/recommended support for 392 some or all of the features provided in this header. 394 The "auth-scheme" specified in this header and other authentication- 395 related headers within the same message MUST be the same. If there 396 are no authentication currently performed, and the auth-scheme 397 contained in this header is not recognizable for the client, the 398 whole header SHOULD be ignored. 400 The header contain one or more parameters, each of which is a name- 401 value pair. The name of each parameter MUST be an extensive-token. 402 Clients MUST ignore any unknown parameters contained in this header. 404 The type of parameter value depends on the parameter name as defined 405 in the following subsections. Regardless of the type, however, the 406 recipients SHOULD accept both quoted and unquoted representations of 407 values as defined in HTTP. If it is defined as a string, it is 408 encouraged to be sent in a quoted-string form. If it defined as a 409 token (or similar) or an integer, the value SHOULD follow the 410 corresponding ABNF syntax after possible unquoting of the quoted- 411 string value (as defined in HTTP), and is encouraged to be sent in a 412 unquoted form. 414 Server-side application SHOULD always be reminded that any parameters 415 contained in this header MAY be ignored by clients. Also, even when 416 a client accepts this header, users may always be able to circumvent 417 semantics of this header. Therefore, if this header is used for 418 security purposes, its use MUST be limited for providing some non- 419 fundamental additional security measures valuable for end-users (such 420 as client-side log-out for protecting against console takeover). 421 Server-side application MUST NOT rely on the use of this header for 422 protecting server-side resources. 424 4.1. Auth-style parameter 426 Authentication-Control: Digest auth-style=modal 428 The parameter "auth-style" specifies the server's preferences over 429 user interface behavior for user authentication. This parameter can 430 be included in any kind of responses, however, it is only meaningful 431 for either authentication-initializing or negatively-authenticated 432 responses. The value of this parameter MUST be one of the bare- 433 tokens "modal" or "non-modal". When the Optional-WWW-Authenticate 434 header is used, the value of this parameter MUST be disregarded and 435 the value "non-modal" is implied. 437 The value "modal" means that the server thinks the content of the 438 response (body and other content-related headers) is valuable only 439 for users refusing authentication request. The clients are expected 440 to ask the user a password before processing the content. This 441 behavior is common for most of the current implementations of Basic 442 and Digest authentication schemes. 444 The value "non-modal" means that the server thinks the content of the 445 response (body and other content-related headers) is valuable for 446 users before processing an authentication request. The clients are 447 expected to first process the content and then provide users 448 opportunities to perform authentication. 450 The default behavior for the clients is implementation-dependent, and 451 clients MAY choose different defaults for different authentication 452 schemes. The proposed default behavior is "modal" for all 453 authentication schemes, but specifications for authentication schemes 454 MAY propose a different default. 456 The above two different methods of authentication may introduce a 457 observable difference of semantics when the response contains state- 458 changing side effects; for example, it may change whether Cookie 459 headers [RFC6265] in 401 responses are processed or not. However, 460 the server applications SHOULD NOT depend on both existence and non- 461 existence of such side effects. 463 4.2. Location-when-unauthenticated parameter 465 Authentication-Control: Mutual 466 location-when-unauthenticated="http://www.example.com/login.html" 468 The parameter "location-when-unauthenticated" specifies a location 469 where any unauthenticated clients should be redirected to. This 470 header may be used, for example, when there is a central login page 471 for the entire Web application. The value of this parameter is a 472 string that contains an absolute URL location. Senders MUST always 473 send an absolute URL location. If a received URL is not absolute, 474 the clients SHOULD either ignore it or consider it a relative URL 475 from the current location. 477 This parameter MAY be used with a 401 response for authentication- 478 initializing response. It can also be contained, although 479 NOT RECOMMENDED, in a positive response with an 480 Optional-WWW-Authenticate header. The clients MUST ignore this 481 parameter, when a response is either successfully-authenticated or 482 intermediately-authenticated. The clients SHOULD ignore this 483 parameter when a response is a negatively-authenticated one (the case 484 is unlikely to happen, though). 486 When a client receives an authentication-initiating response with 487 this parameter, if the client has to ask users for authentication 488 credentials, the client will treat the entire response as if it were 489 a 303 "See Other" response with a Location header that contains the 490 value of this parameter (i.e., client will be redirected to the 491 specified location with a GET request). Unlike a normal 303 492 response, if the client can process authentication without the user's 493 interaction, this parameter MUST be ignored. 495 4.3. No-auth parameter 497 Authentication-Control: Basic no-auth=true 499 The parameter "no-auth" is a variant of the 500 location-when-unauthenticated parameter; it specifies that new 501 authentication attempt is not to be performed on this location for 502 better user experience, without specifying the redirection on the 503 HTTP level. This header may be used, for example, when there is a 504 central login page for the entire Web application, and when a (Web 505 content's level) explicit interaction of users is desired before 506 authentications. The value of this parameter MUST be a token "true". 507 If the value is incorrect, client MAY ignore this parameter. 509 This parameter MAY be used with authentication-initiating responses. 510 It can also be contained, although NOT RECOMMENDED, in a positive 511 response with an Optional-WWW-Authenticate header. The clients MUST 512 ignore this parameter, when a response is either successfully- 513 authenticated or intermediately-authenticated. The clients SHOULD 514 ignore this parameter when a response is a negatively-authenticated 515 one (the case is unlikely to happen, though). 517 When a client receives an authentication-initiating response with 518 this parameter, if the client has to ask users for authentication 519 credentials, the client will ignore the WWW-Authenticate header 520 contained in the response and treat the whole response as a normal 521 negative 4xx-class response instead of giving user an opportunity to 522 start authentication. If the client can process authentication 523 without the user's interaction, this parameter MUST ignored. 525 This parameter SHOULD NOT be used along with the 526 location-when-unauthenticated parameter. If both were supplied, 527 clients MAY choose which one is to be honored. 529 This parameter SHOULD NOT be used as any security measures to prevent 530 authentication attempts, as it is easily circumvented by users. This 531 parameter SHOULD be used solely for improving user experience of web 532 applications. 534 4.4. Location-when-logout parameter 536 Authentication-Control: Digest 537 location-when-logout="http://www.example.com/byebye.html" 539 The parameter "location-when-logout" specifies a location where the 540 client is to be redirected when the user explicitly request a logout. 541 The value of this parameter MUST be a string that contains an 542 absolute URL location. If a given URL is not absolute, the clients 543 MAY consider it a relative URL from the current location. 545 This parameter MAY be used with successfully-authenticated responses. 546 If this parameter is contained in other kinds of responses, the 547 clients MUST ignore this parameter. 549 When the user requests to terminate an authentication period, and if 550 the client currently displays a page supplied by a response with this 551 parameter, the client will be redirected to the specified location by 552 a new GET request (as if it received a 303 response). The log-out 553 operation (e.g. erasing memories of user name, authentication 554 credential and all related one-time credentials such as nonce or 555 keys) SHOULD occur before processing a redirection. 557 When the user requests to terminate an authentication period, if the 558 client supports this parameter but the server response does not 559 contain this parameter, the client's RECOMMENDED behavior is as 560 follows: if the request corresponding to the current content was safe 561 (e.g. GET), reload the page without the authentication credential. 562 If the request was non-idempotent (e.g. POST), keep the current 563 content as-is and simply forget the authentication status. The 564 client SHOULD NOT replay a non-idempotent request without the user's 565 explicit approval. 567 Web applications are encouraged to send this parameter with an 568 appropriate value for any responses (except those with redirection 569 (3XX) statuses) for non-GET requests. 571 4.5. Logout-timeout 573 Authentication-Control: Basic logout-timeout=300 575 The parameter "logout-timeout", when contained in a successfully- 576 authenticated response, means that any authentication credentials and 577 states related to the current protection space are to be discarded if 578 a time specified in this header (in seconds) has been passed from the 579 time received. The value MUST be an integer. As a special case, the 580 value 0 means that the client is requested to immediately log-out 581 from the current authentication space and revert to an 582 unauthenticated status. This does not, however, mean that the long- 583 term memories for the passwords (such as the password reminders and 584 auto fill-ins) should be removed. If a new timeout value is received 585 for the same authentication space, it cancels the previous timeout 586 and sets a new timeout. 588 5. Usage examples (informative) 590 This section shows some examples for applying this extension to 591 typical Web-sites which are using Forms and cookies for managing 592 authentication and authorization. The content of this section is not 593 normative and for illustrative purposes only. 595 We assume that all features described in the previous sections are 596 implemented in clients (Web browsers). We also assume that browsers 597 will have a user interface which allows users to deactivate (log-out 598 from) current authentication sessions. If this assumption is not 599 hold, texts below provides another approach with de-authentication 600 pages used instead of such a UI. 602 Without explicit notices, all settings described below are to be 603 applied with Authentication-Control headers, and these can be sent to 604 clients regardless of authentication statuses (these will be silently 605 ignored whenever not effective). 607 5.1. Example 1: a portal site 609 This subsection provides an example application for a site whose 610 structure is somewhat similar to conventional portal sites. In 611 particular, most of web pages are available for guest 612 (unauthenticated) users, and if authentication is performed, contents 613 of these pages are customized for each user. We assume the site has 614 the following kinds of pages currently: 616 o Content pages. 618 o Pages/mechanism for performing authentication: 620 * There is one page which asks a user name and a password using a 621 HTML POST form. 623 * After the authentication attempt, the user will be redirected 624 to either the page which is previously displayed before the 625 authentication, or some specific page. 627 o A de-authentication (log-out) page. 629 5.1.1. Case 1: a simple application 631 When such a site does not need a specific actions upon log-in and 632 log-out, the following simple settings can be used. 634 o Set up an optional authentication to all pages available to 635 guests. Set up an Authentication-Control header with "auth- 636 style=non-modal" setting. 638 o If there are pages only available to authenticated users, Set up a 639 mandatory authentication with "auth-style=non-modal" setting. 641 o No specific pages for authentication is needed. It will be 642 performed automatically, directed by the above setting. 644 o A de-authentication page is also not needed. If the site will 645 have one, put "logout-timeout=0" there. 647 o For all pages for POST requests, it is advisable to have 648 "location-when-logout=". 650 5.1.2. Case 2: specific action required on log-out 652 If the site needs a specific actions upon log-out, the following 653 settings can be used. 655 o All shown in the Case 1 are to be applied. 657 o For all pages, set up the Authentication-Control header "location- 658 when-logout=". 660 o In de-authentication pages, no specific set-up is needed. If 661 there is any direct links to it, put "logout-timeout=0". 663 5.1.3. Case 3: specific page displayed before log-in 665 If the site needs to display a specific page before log-in actions 666 (some announces, user notices, or even advertisements), the following 667 settings can be applied. 669 o Set up an optional authentication to all pages available to guest. 670 Set up an Authentication-Control header with "no-auth=true". Put 671 a link to a specific log-in page in contents. 673 o If there are pages only available to authenticated users, Set up a 674 mandatory authentication with "location-when-unauthenticated=". 677 o For the specific log-in page, Set up a mandatory authentication. 679 o For all pages for POST requests, it is advisable to have 680 "location-when-logout=", too. 682 o De-authentication pages are not needed. If the site will have 683 one, put "logout-timeout=0". 685 5.2. Example 2: authenticated user-only sites 687 If almost all pages in the target site requires authentication (e.g., 688 an Internet banking site), or there are no needs to support both 689 unauthenticated and authenticated users on the same resource, the 690 setting will become somewhat simple. The following are an example to 691 realize such a site: 693 o Set up a mandatory authentication to all pages available to 694 authenticated. Set up an Authentication-Control header with 695 "auth-style=non-modal" setting. 697 o Set up a handler for the 401-status which requests users to 698 authenticate. 700 o For all pages for POST requests, it is advisable to have 701 "location-when-logout=", too. 703 o De-authentication pages are not needed. If the site will have 704 one, put "logout-timeout=0" there. 706 5.3. When to use Cookies 708 In the current Web sites using Form-based authentications, Cookies 709 [RFC6265] are used for managing both authorization and application 710 sessions. Using the extensions in this document, the former features 711 will be provided by using (extended) HTTP authentication/ 712 authorization mechanisms. In some cases, there will be some 713 ambiguous situations whether some functions are authorization 714 management or session management. The following hints will be 715 helpful for deciding which features to be used. 717 o If there is a need to serve multiple sessions for a single user 718 using multiple browsers concurrently, use a Cookie for 719 distinguishing between sessions for the same user. (C.f. if there 720 is a need to distinguish sessions in the same browser, HTML5 Web 721 Storage [W3C.CR-webstorage-20111208] features may be used instead 722 of Cookies.) 724 o If a web site is currently deploying a session time-out feature, 725 consider who benefits from the feature. In most cases, the main 726 requirement for such feature is to protect users from their 727 consoles and browsers hijacked (i.e. benefits are on the users' 728 side). In such cases, the time-out features provided in this 729 extension may be used. On the other hand, the requirements is to 730 protect server's privilege (e.g. when some regulations require to 731 limit the time difference between user's two-factor authentication 732 and financial transaction commitment; the requirement is strictly 733 on the servers' side), that should be managed on the server side 734 using Cookies or other session management mechanisms. 736 5.4. Parallel deployment with Form/Cookie authentications 738 In some transition periods, sites may need to support both HTTP-layer 739 and Form-based authentications. The following example shows one way 740 to achieve that. 742 o If Cookies are used even for HTTP-authenticated users, each 743 session determined by Cookies should identify which authentication 744 are used for the session. 746 o First, set up any of the above settings for enabling HTTP-layer 747 authentication. 749 o For unauthenticated users, put the following things to the Web 750 pages, unless the client supports this extension and HTTP-level 751 authentication. 753 * For non-mandatory authenticated pages, put a link to Form-based 754 authenticated pages. 756 * For mandatory authenticated pages, either put a link to Form- 757 based authenticated pages, or put a HTML-level redirection 758 (using META element) to such pages. 760 o In Form-based authenticated pages, if users are not authenticated, 761 it may have a diversion for HTTP-level authentication by 762 "location-when-unauthenticated" setting. 764 o Users are identified for authorizations and content customizations 765 by the following logic. 767 * First, check the result of the HTTP-level authentication. If 768 there is a Cookie session tied to a specific user, both ones 769 should match. 771 * If the user is not authenticated on the HTTP-level, use the 772 conventional Form-based method to determine the user. 774 * If there is a Cookie tied to an HTTP authentication, but there 775 is no corresponding HTTP authentication result, that session 776 will be discarded (because it means that authentication is 777 deactivated by the corresponding user). 779 6. Methods to extend this protocol 781 If a private extension to this protocol is implemented, it MUST use 782 the extension-param to avoid conflicts with this protocol and other 783 future official extensions. 785 Extension-tokens MAY be freely used for any non-standard, private, 786 and/or experimental uses. The extension-tokens MUST be with format 787 "-.", where is a validly 788 registered (sub-)domain name on the Internet owned by the party who 789 defines the extensions. Unknown parameter names are to be ignored 790 regardless of whether it is extension-tokens or bare-tokens. 792 7. IANA Considerations 794 The header "Optional-WWW-Authenticate" and "Authentication-Control" 795 should be registered to IANA registry appropriately (TO-DO). 797 Tokens used for the authentication control parameters may be either 798 extension-tokens or bare-tokens as outlined in Section 2.2. When 799 bare-tokens are used in this protocol, these MUST be allocated by 800 IANA. Any tokens used for non-private, non-experimental parameters 801 are RECOMMENDED to be registered to IANA, regardless of the kind of 802 tokens used. 804 To acquire registered tokens, a specification for the use of such 805 tokens MUST be available as a publicly-accessible documents, as 806 outlined as "Specification Required" level in [RFC5226]. 808 Note: More formal declarations will be added in the future drafts to 809 meet the RFC 5226 requirements. 811 8. Security Considerations 813 The purpose of the log-out timeout feature in the Authentication- 814 control header is to protect users of clients from impersonation 815 caused by an attacker having access to the same console. Server 816 application implementors SHOULD be aware that the directive may 817 always be ignored by either malicious clients or clients not 818 supporting this extension. If the purpose of introducing a timeout 819 for an authentication period is to protect server-side resources, 820 such features MUST be implemented by other means such as HTTP Cookies 821 [RFC6265]. 823 All parameters in Authentication-Control header SHOULD NOT be used 824 for any security-enforcement purposes. Server-side applications MUST 825 be implemented always considering that the header may be either 826 ignored by clients or even bypassed by users. 828 9. References 830 9.1. Normative References 832 [I-D.ietf-httpbis-p1-messaging] 833 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 834 (HTTP/1.1): Message Syntax and Routing", 835 draft-ietf-httpbis-p1-messaging-24 (work in progress), 836 September 2013. 838 [I-D.ietf-httpbis-p7-auth] 839 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 840 (HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-24 841 (work in progress), September 2013. 843 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 844 Requirement Levels", BCP 14, RFC 2119, March 1997. 846 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 847 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 848 May 2008. 850 9.2. Informative References 852 [I-D.ietf-httpauth-mutual] 853 Oiwa, Y., Watanabe, H., Takagi, H., Hayashi, T., and Y. 854 Ioku, "Mutual Authentication Protocol for HTTP", 855 draft-ietf-httpauth-mutual-01 (work in progress), 856 October 2013. 858 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 859 April 2011. 861 [W3C.CR-webstorage-20111208] 862 Hickson, I., "Web Storage", World Wide Web Consortium 863 CR CR-webstorage-20111208, December 2011, 864 . 866 Appendix A. (Informative) Applicability of features for each messages 868 This section provides cross-reference table about applicability of 869 each features provided in this specification for each kinds of 870 responses described in Section 2.1. The table provided in this 871 section is for informative purposes only. 873 +-------------------+-------+----------+-----------+------+ 874 | | init. | success. | intermed. | neg. | 875 +-------------------+-------+----------+-----------+------+ 876 | Optional auth. | O | n | N | N | 877 | auth-style | O | - | - | O | 878 | loc.-when-unauth. | O | I | I | i | 879 | no-auth | O | I | I | i | 880 | loc.-when-logout | - | O | - | - | 881 | logout-timeout | - | O | - | - | 882 +-------------------+-------+----------+-----------+------+ 884 Legends: 885 O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain 886 i = SHOULD be ignored; I = MUST be ignored; 887 - = meaningless (to be ignored) 889 Appendix B. (Informative) Draft Notes 891 Things which might be considered for future revisions: 893 o In [I-D.ietf-httpbis-p7-auth], meaning of WWW-Authenticate headers 894 in non-401 responses are defined as "supplying credentials (or 895 different credentials) might affect the response". This 896 clarification change leaves a way for using 200-status responses 897 along with a WWW-Authenticate header for providing optional 898 authentication. 899 Incorporating this possibility, however, needs more detailed 900 analysis on the behavior of existing clients and intermediate 901 proxies for such possibly-confusing responses. Optional-WWW- 902 Authenticate is safer, at least for minimum backward 903 compatibility, because clients not supporting this extension will 904 consider this header as an unrecognized entity-header, possibly 905 providing opportunity for silently falling-back to application- 906 level authentications. 908 Appendix C. (Informative) Draft Change Log 910 C.1. Changes in Httpauth WG revision 01 912 o Clarification on peers' responsibility about handling of relative 913 URLs. 915 o Automatic reloading should be allowed only on safe methods, not 916 always on idempotent methods. 918 C.2. Changes in Httpauth revision 00 and HttpBis revision 00 920 None. 922 C.3. Changes in revision 02 924 o Added usage examples. 926 C.4. Changes in revision 01 928 o Syntax notations and parsing semantics changed to match httpbis 929 style. 931 C.5. Changes in revision 00 933 o Separated from HTTP Mutual authentication proposal (-09). 935 o Adopting httpbis works as a referencing point to HTTP. 937 o Generalized, now applicable for all HTTP authentication schemes. 939 o Added "no-auth" and "auth-style" parameters. 941 o Loosened standardization requirements for parameter-name tokens 942 registration. 944 Authors' Addresses 946 Yutaka Oiwa 947 National Institute of Advanced Industrial Science and Technology 948 Research Institute for Secure Systems 949 3-11-46 Nakouji 950 Amagasaki, Hyogo 951 JP 953 Email: mutual-auth-contact-ml@aist.go.jp 955 Hajime Watanabe 956 National Institute of Advanced Industrial Science and Technology 957 Research Institute for Secure Systems 958 Tsukuba Central 2 959 1-1-1 Umezono 960 Tsukuba-shi, Ibaraki 961 JP 963 Hiromitsu Takagi 964 National Institute of Advanced Industrial Science and Technology 965 Research Institute for Secure Systems 966 Tsukuba Central 2 967 1-1-1 Umezono 968 Tsukuba-shi, Ibaraki 969 JP 971 Tatsuya Hayashi 972 Lepidum Co. Ltd. 973 #602, Village Sasazuka 3 974 1-30-3 Sasazuka 975 Shibuya-ku, Tokyo 976 JP 978 Yuichi Ioku 979 Individual