idnits 2.17.1 draft-oiwa-http-auth-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 (June 4, 2012) is 4344 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-19 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Standards Track H. Takagi 5 Expires: December 6, 2012 RISEC, AIST 6 B. Kihara 7 T. Hayashi 8 Lepidum 9 Y. Ioku 10 Yahoo! Japan 11 June 4, 2012 13 HTTP Authentication Extensions for Interactive Clients 14 draft-oiwa-http-auth-extension-02 16 Abstract 18 This document specifies a few extensions of HTTP authentication 19 framework for interactive clients. Recently, fundamental features of 20 HTTP-level authentication is not enough for complex requirements of 21 various Web-based applications. This makes these applications to 22 implement their own authentication frameworks using HTML Forms and 23 other means, which becomes one of the hurdles against introducing 24 secure authentication mechanisms handled jointly by servers and user- 25 agent clients. The extended framework fills gaps between Web 26 application requirements and HTTP authentication provisions to solve 27 the above problems, while maintaining compatibility against existing 28 Web and non-Web uses of HTTP authentications. 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on December 6, 2012. 47 Copyright Notice 48 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . 19 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 revision 02 . . . . . . . . . . . . . . . . . . 21 94 C.2. Changes in revision 01 . . . . . . . . . . . . . . . . . . 21 95 C.3. Changes in revision 00 . . . . . . . . . . . . . . . . . . 21 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 98 1. Introduction 100 The document proposes several extensions to the current HTTP 101 authentication framework, to provide enough functionality comparable 102 with current widely-used form-based Web authentication. A majority 103 of the recent Web-sites on the Internet use custom application-layer 104 authentication implementations using Web forms. The reasons for 105 these may vary, but many people believe that the current HTTP Basic 106 (and Digest, too) authentication method does not have enough 107 functionality (including a good-feeling user interfaces) to support 108 most of realistic Web-based applications. However, the method is 109 very weak against phishing and other attacks, because the whole 110 behavior of the authentication is controlled from the server-side 111 applications. This makes it really hard to implement any 112 cryptographically strong authentication mechanisms into Web systems. 113 To overcome this problem, we need to "modernize" the HTTP 114 authentication framework so that better client-controlled secure 115 methods can be used with Web applications. The extensions proposed 116 in this document include: 118 o non-mandatory, optional authentication on HTTP (Section 3), 120 o log out from both server and client side (Section 4), and 122 o finer control for redirection depending on authentication status 123 (Section 4). 125 [I-D note: These extensions are initially proposed as a part of 126 [I-D.oiwa-http-mutualauth]. However, since these functionalities 127 might possibly be useful in combination even with other 128 authentication schemes, the extensions were separated from the 129 original document as this independent draft.] 131 1.1. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in 136 [RFC2119]. 138 The terms "encouraged" and "advised" are used for suggestions that do 139 not constitute "SHOULD"-level requirements. People MAY freely choose 140 not to include the suggested items regarding [RFC2119], but complying 141 with those suggestions would be a best practice; it will improve the 142 security, interoperability, and/or operational performance. 144 This document distinguishes the terms "client" and "user" in the 145 following way: A "client" is an entity understanding and talking HTTP 146 and the specified authentication protocol, usually computer software; 147 a "user" is a (usually natural) person who wants to access data 148 resources using "a client". 150 2. Definitions 152 2.1. Terms for describing authentication protocol flow 154 HTTP Authentication defined in [I-D.ietf-httpbis-p7-auth] may involve 155 with several pairs of HTTP requests/responses. Throughout this 156 document, the following terms are used to categorize those messages: 157 for requests, 159 o A non-authenticating request is a request not attempting any 160 authentication: a request without any Authorization header. 162 o An authenticating request is the opposite: a request with an 163 Authorization header. 165 For responses, 167 1) A non-authenticated response: is a response which does not 168 involve with any HTTP authentication. It may not contain any 169 WWW-Authenticate or Authentication-Info header. 171 Servers send this response when the requested resource is not 172 protected by HTTP authentication mechanisms. In context of this 173 specification, not-authentication-related negative responses (e.g. 174 403 and 404) are also considered as non-authenticated responses. 176 (See note on successfully-authenticated responses below for some 177 ambiguous cases.) 179 2) An authentication-initializing response: is a response which 180 requires or allows clients to start authentication attempts. 181 Servers send this response when the requested resource is 182 protected by HTTP authentication mechanism, and the request meets 183 one of the following cases: 185 * The request is non-authenticating request, or 187 * The request contained an authentication trial directed to the 188 protection space (realm) other than the server's expected one. 190 The server will specify the protection space for authentication in 191 this response. 193 Upon reception, the client's behavior is further divided to two 194 possible cases. 196 * If the client may have no prior knowledge on authentication 197 credentials (e.g. a user-name and a password) related to the 198 requested protection space, the protocol flow terminates and 199 the client will ask the user to provide authentication 200 credentials, 202 * On the other hand, if client already have an enough credentials 203 for authentication to the requested protection space, the 204 client will automatically send an authenticating request. Such 205 cases often occur when the client did not know beforehand that 206 the current request-URL requires an authentication. 208 3) A successfully-authenticated response: is a response for an 209 authenticating request meaning that the authentication attempt was 210 granted. (Note: if the authentication scheme used does not use an 211 Authentication-Info header, it may be indistinguishable from a 212 non-authenticated response.) 214 4) An intermediate authenticating response: is a response for an 215 authenticating request which requires some more reaction by the 216 client software without involving users. Such a response is 217 required when an authentication scheme requires two or more round- 218 trip messages to perform authentication, or when an authentication 219 scheme uses some speculative short-cut method (such as uses of 220 cached shared secrets) and it failed. 222 5) A negatively-authenticated response: is a response for an 223 authenticating request which means that the authentication attempt 224 was declined and can not continue without another authentication 225 credential. Clients typically erase memory of the currently-using 226 credentials and ask the user for other ones. 228 Usually the format of these responses are as same as the one for 229 authentication-initializing responses. Client can distinguish it 230 by comparing the protection spaces contained in the request and in 231 the response. 233 Figure 1 shows a state diagram of generic HTTP authentication with 234 the above message categorization. Note that many authentication 235 schemes uses only a subset of the transitions described on the 236 diagram. Labels in the figure show the abbreviated names of response 237 types. 239 =========== ----------------- 240 NEW REQUEST ( UNAUTHENTICATED ) 241 =========== ----------------- 242 | ^ non-auth. 243 v | response 244 +----------------------+ NO +-------------+ 245 | The requested URI |--------------------------->| send normal | 246 | known to be auth'ed? | ---------------->| request | 247 +----------------------+ / +-------------+ 248 YES | / initializing| 249 v / | 250 +------------------+ NO / | 251 | Can auth-req (*1)|--------- | 252 | be constructed? | | 253 +------------------+ | 254 YES | initializing | 255 | ---------------------------------------. | 256 | / v v 257 | | ---------------- NO +-----------+ 258 | | ( AUTH-REQUESTED )<------|credentials| 259 | | ---------------- | known? | 260 v | +-----------+ 261 +-----------+ negative ------------- negative |YES 262 | send |---------->( AUTH-FAILED )<---------, | 263 /| auth-req | ------------- | | 264 / +-----------+\ | v 265 | \ \ intermediate +-----------+ 266 | \ -------------------------------->| send | 267 | \ | auth-req | 268 | non-auth. \successful successful +-----------+ 269 | response (*2) \ / | ^ 270 v \ / | | 271 ----------------- \ -------------- / `----' 272 ( UNAUTHENTICATED ) ----->( AUTH-SUCCEED )<---- intermediate 273 ----------------- -------------- 275 Figure 1: Generic state diagram for HTTP authentication 277 Note: (*1) For example, "Digest" scheme requires server-provided 278 nonces to construct client-side challenges. 279 (*2) In "Basic" and some others, this cannot be distinguished from a 280 successfully-authenticated response. 282 2.2. Syntax Notation 284 This specification uses an extended BNF syntax defined in 285 [I-D.ietf-httpbis-p1-messaging]. The following syntax definitions 286 are quoted from [I-D.ietf-httpbis-p1-messaging] and 287 [I-D.ietf-httpbis-p7-auth]: auth-scheme, quoted-string, auth-param, 288 SP, header-field, and challenge. It also uses the convention of 289 using header names for specifying syntax of header values. 291 Additionally, this specification uses the following syntax elements 292 following syntax definitions as a refinement for token and the 293 righthand-side of auth-param in [I-D.ietf-httpbis-p7-auth]. (Note: 294 these definitions are consistent with those in 295 [I-D.oiwa-http-mutualauth].) 297 bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 298 extension-token = "-" bare-token 1*("." bare-token) 299 extensive-token = bare-token / extension-token 300 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 302 Figure 2: the BNF syntax for common notations 304 Extensive-tokens are used in this protocol where the set of 305 acceptable tokens may include private extensions. Any private 306 extensions of this protocol MUST use the extension-tokens with format 307 "-.", where is a validly registered 308 (sub-)domain name on the Internet owned by the party who defines the 309 extensions. 311 3. Optional Authentication 313 The Optional-WWW-Authenticate header enables a non-mandatory 314 authentication, which is not possible under the current HTTP 315 authentication mechanism. In several Web applications, users can 316 access the same contents as both a guest user and an authenticated 317 user. In most Web applications, it is implemented using HTTP cookies 318 [RFC6265] and custom form-based authentications. The new 319 authentication method using this message will provide a replacement 320 for these authentication systems. 322 Servers MAY send HTTP successful responses (response code 200, 206 323 and others) containing the Optional-WWW-Authenticate header as a 324 replacement of a 401 response when it is an authentication- 325 initializing response. The Optional-WWW-Authenticate header MUST NOT 326 be contained in 401 responses. 328 HTTP/1.1 200 OK 329 Optional-WWW-Authenticate: Basic realm="xxxx" 331 Optional-WWW-Authenticate = challenge 333 Figure 3: BNF syntax for Optional-WWW-Authenticate header 335 The challenge contained in the Optional-WWW-Authenticate header are 336 the same as those for a 401 responses corresponding for a same 337 request. For authentication-related matters, an optional 338 authentication request will have the same meaning as a 401 message 339 with a corresponding WWW-Authenticate header (as an authentication- 340 initializing response). (The behavior for other matters, such as 341 caching, MAY be different between the optional authentication and 401 342 messages.) 344 A response with an Optional-WWW-Authenticate header SHOULD be 345 returned from the server only when the request is either non- 346 authenticated or authenticating to a wrong (not the server's 347 expected) protection space. If a response is either an intermediate 348 or a negative response to a client's authentication attempt, the 349 server MUST respond with a 401 status response with a 350 WWW-Authenticate header instead. Failure to comply this rule will 351 make client not able to distinguish authentication successes and 352 failures. 354 The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate 355 header in a positive response when a client's authentication attempt 356 succeeds. 358 Whenever an authentication scheme support for servers to send some 359 parameter which gives a hint of URL space for the corresponding 360 protection space for the same realm (e.g. "path" or "domain"), 361 servers requesting non-mandatory authentication SHOULD send such 362 parameter with the response. Clients supporting non-mandatory 363 authentication MUST recognize the parameter, and MUST send a request 364 with an appropriate authentication credential in an Authorization 365 header for any URI inside the specified paths. 367 Support of this header is OPTIONAL; Clients MAY also choose any set 368 of authentication schemes for which optional authentication is 369 supported (in other words, its support MAY be scheme-dependent). 370 However, some authentication schemes MAY require mandatory/ 371 recommended support for this header, so that server-side applications 372 MAY assume that clients supporting such schemes are likely to support 373 the extension as well. 375 4. Authentication-Control header 376 Authentication-Control = auth-scheme 1*SP 1#auth-param 378 Figure 4: the BNF syntax for the Authentication-Control header 380 The Authentication-Control header provides a more precise control of 381 the client behavior for Web applications using an HTTP authentication 382 protocol. This header is supposed to be generated in the application 383 layer, as opposed to WWW-Authenticate headers which will be generated 384 usually by the Web servers. 386 Support of this header is OPTIONAL, and clients MAY choose any subset 387 of these parameters to be supported. The set of supported parameters 388 MAY also be authentication scheme-dependent. However, some 389 authentication schemes MAY require mandatory/recommended support for 390 some or all of the features provided in this header. 392 The "auth-scheme" specified in this header and other authentication- 393 related headers within the same message MUST be the same. If there 394 are no authentication currently performed, and the auth-scheme 395 contained in this header is not recognizable for the client, the 396 whole header SHOULD be ignored. 398 The header contain one or more parameters, each of which is a name- 399 value pair. The name of each parameter MUST be an extensive-token. 400 Clients MUST ignore any unknown parameters contained in this header. 402 The type of parameter value depends on the parameter name as defined 403 in the following subsections. Regardless of the type, however, the 404 recipients SHOULD accept both quoted and unquoted representations of 405 values as defined in HTTP. If it is defined as a string, it is 406 encouraged to be sent in a quoted-string form. If it defined as a 407 token (or similar) or an integer, the value SHOULD follow the 408 corresponding ABNF syntax after possible unquoting of the quoted- 409 string value (as defined in HTTP), and is encouraged to be sent in a 410 unquoted form. 412 Server-side application SHOULD always be reminded that any parameters 413 contained in this header MAY be ignored by clients. Also, even when 414 a client accepts this header, users may always be able to circumvent 415 semantics of this header. Therefore, if this header is used for 416 security purposes, its use MUST be limited for providing some non- 417 fundamental additional security measures valuable for end-users (such 418 as client-side log-out for protecting against console takeover). 419 Server-side application MUST NOT rely on the use of this header for 420 protecting server-side resources. 422 4.1. Auth-style parameter 424 Authentication-Control: Digest auth-style=modal 426 The parameter "auth-style" specifies the server's preferences over 427 user interface behavior for user authentication. This parameter can 428 be included in any kind of responses, however, it is only meaningful 429 for either authentication-initializing or negatively-authenticated 430 responses. The value of this parameter MUST be one of the bare- 431 tokens "modal" or "non-modal". When the Optional-WWW-Authenticate 432 header is used, the value of this parameter MUST be disregarded and 433 the value "non-modal" is implied. 435 The value "modal" means that the server thinks the content of the 436 response (body and other content-related headers) is valuable only 437 for users refusing authentication request. The clients are expected 438 to ask the user a password before processing the content. This 439 behavior is common for most of the current implementations of Basic 440 and Digest authentication schemes. 442 The value "non-modal" means that the server thinks the content of the 443 response (body and other content-related headers) is valuable for 444 users before processing an authentication request. The clients are 445 expected to first process the content and then provide users 446 opportunities to perform authentication. 448 The default behavior for the clients is implementation-dependent, and 449 clients MAY choose different defaults for different authentication 450 schemes. The proposed default behavior is "modal" for all 451 authentication schemes, but specifications for authentication schemes 452 MAY propose a different default. 454 The above two different methods of authentication may introduce a 455 observable difference of semantics when the response contains state- 456 changing side effects; for example, it may change whether Cookie 457 headers [RFC6265] in 401 responses are processed or not. However, 458 the server applications SHOULD NOT depend on both existence and non- 459 existence of such side effects. 461 4.2. Location-when-unauthenticated parameter 463 Authentication-Control: Mutual 464 location-when-unauthenticated="http://www.example.com/login.html" 466 The parameter "location-when-unauthenticated" specifies a location 467 where any unauthenticated clients should be redirected to. This 468 header may be used, for example, when there is a central login page 469 for the entire Web application. The value of this parameter MUST be 470 a string that contains an absolute URL location. If a given URL is 471 not absolute, the clients MAY consider it a relative URL from the 472 current location. 474 This parameter MAY be used with a 401 response for authentication- 475 initializing response. It can also be contained, although 476 NOT RECOMMENDED, in a positive response with an 477 Optional-WWW-Authenticate header. The clients MUST ignore this 478 parameter, when a response is either successfully-authenticated or 479 intermediately-authenticated. The clients SHOULD ignore this 480 parameter when a response is a negatively-authenticated one (the case 481 is unlikely to happen, though). 483 When a client receives an authentication-initiating response with 484 this parameter, if the client has to ask users for authentication 485 credentials, the client will treat the entire response as if it were 486 a 303 "See Other" response with a Location header that contains the 487 value of this parameter (i.e., client will be redirected to the 488 specified location with a GET request). Unlike a normal 303 489 response, if the client can process authentication without the user's 490 interaction, this parameter MUST be ignored. 492 4.3. No-auth parameter 494 Authentication-Control: Basic no-auth=true 496 The parameter "no-auth" is a variant of the 497 location-when-unauthenticated parameter; it specifies that new 498 authentication attempt is not to be performed on this location for 499 better user experience, without specifying the redirection on the 500 HTTP level. This header may be used, for example, when there is a 501 central login page for the entire Web application, and when a (Web 502 content's level) explicit interaction of users is desired before 503 authentications. The value of this parameter MUST be a token "true". 504 If the value is incorrect, client MAY ignore this parameter. 506 This parameter MAY be used with authentication-initiating responses. 507 It can also be contained, although NOT RECOMMENDED, in a positive 508 response with an Optional-WWW-Authenticate header. The clients MUST 509 ignore this parameter, when a response is either successfully- 510 authenticated or intermediately-authenticated. The clients SHOULD 511 ignore this parameter when a response is a negatively-authenticated 512 one (the case is unlikely to happen, though). 514 When a client receives an authentication-initiating response with 515 this parameter, if the client has to ask users for authentication 516 credentials, the client will ignore the WWW-Authenticate header 517 contained in the response and treat the whole response as a normal 518 negative 4xx-class response instead of giving user an opportunity to 519 start authentication. If the client can process authentication 520 without the user's interaction, this parameter MUST ignored. 522 This parameter SHOULD NOT be used along with the 523 location-when-unauthenticated parameter. If both were supplied, 524 clients MAY choose which one is to be honored. 526 This parameter SHOULD NOT be used as any security measures to prevent 527 authentication attempts, as it is easily circumvented by users. This 528 parameter SHOULD be used solely for improving user experience of web 529 applications. 531 4.4. Location-when-logout parameter 533 Authentication-Control: Digest 534 location-when-logout="http://www.example.com/byebye.html" 536 The parameter "location-when-logout" specifies a location where the 537 client is to be redirected when the user explicitly request a logout. 538 The value of this parameter MUST be a string that contains an 539 absolute URL location. If a given URL is not absolute, the clients 540 MAY consider it a relative URL from the current location. 542 This parameter MAY be used with successfully-authenticated responses. 543 If this parameter is contained in other kinds of responses, the 544 clients MUST ignore this parameter. 546 When the user requests to terminate an authentication period, and if 547 the client currently displays a page supplied by a response with this 548 parameter, the client will be redirected to the specified location by 549 a new GET request (as if it received a 303 response). The log-out 550 operation (e.g. erasing memories of user name, authentication 551 credential and all related one-time credentials such as nonce or 552 keys) SHOULD occur before processing a redirection. 554 When the user requests to terminate an authentication period, if the 555 client supports this parameter but the server response does not 556 contain this parameter, the client's RECOMMENDED behavior is as 557 follows: if the request corresponding to the current content was 558 idempotent (e.g. GET), reload the page without the authentication 559 credential. If the request was non-idempotent (e.g. POST), keep the 560 current content as-is and simply forget the authentication status. 561 The client SHOULD NOT replay a non-idempotent request without the 562 user's explicit approval. 564 Web applications are encouraged to send this parameter with an 565 appropriate value for any responses (except those with redirection 566 (3XX) statuses) for non-GET requests. 568 4.5. Logout-timeout 570 Authentication-Control: Basic logout-timeout=300 572 The parameter "logout-timeout", when contained in a successfully- 573 authenticated response, means that any authentication credentials and 574 states related to the current protection space are to be discarded if 575 a time specified in this header (in seconds) has been passed from the 576 time received. The value MUST be an integer. As a special case, the 577 value 0 means that the client is requested to immediately log-out 578 from the current authentication space and revert to an 579 unauthenticated status. This does not, however, mean that the long- 580 term memories for the passwords (such as the password reminders and 581 auto fill-ins) should be removed. If a new timeout value is received 582 for the same authentication space, it cancels the previous timeout 583 and sets a new timeout. 585 5. Usage examples (informative) 587 This section shows some examples for applying this extension to 588 typical Web-sites which are using Forms and cookies for managing 589 authentication and authorization. The content of this section is not 590 normative and for illustrative purposes only. 592 We assume that all features described in the previous sections are 593 implemented in clients (Web browsers). We also assume that browsers 594 will have a user interface which allows users to deactivate (log-out 595 from) current authentication sessions. If this assumption is not 596 hold, texts below provides another approach with de-authentication 597 pages used instead of such a UI. 599 Without explicit notices, all settings described below are to be 600 applied with Authentication-Control headers, and these can be sent to 601 clients regardless of authentication statuses (these will be silently 602 ignored whenever not effective). 604 5.1. Example 1: a portal site 606 This subsection provides an example application for a site whose 607 structure is somewhat similar to conventional portal sites. In 608 particular, most of web pages are available for guest 609 (unauthenticated) users, and if authentication is performed, contents 610 of these pages are customized for each user. We assume the site has 611 the following kinds of pages currently: 613 o Content pages. 615 o Pages/mechanism for performing authentication: 617 * There is one page which asks a user name and a password using a 618 HTML POST form. 620 * After the authentication attempt, the user will be redirected 621 to either the page which is previously displayed before the 622 authentication, or some specific page. 624 o A de-authentication (log-out) page. 626 5.1.1. Case 1: a simple application 628 When such a site does not need a specific actions upon log-in and 629 log-out, the following simple settings can be used. 631 o Set up an optional authentication to all pages available to 632 guests. Set up an Authentication-Control header with "auth- 633 style=non-modal" setting. 635 o If there are pages only available to authenticated users, Set up a 636 mandatory authentication with "auth-style=non-modal" setting. 638 o No specific pages for authentication is needed. It will be 639 performed automatically, directed by the above setting. 641 o A de-authentication page is also not needed. If the site will 642 have one, put "logout-timeout=0" there. 644 o For all pages for POST requests, it is advisable to have 645 "location-when-logout=". 647 5.1.2. Case 2: specific action required on log-out 649 If the site needs a specific actions upon log-out, the following 650 settings can be used. 652 o All shown in the Case 1 are to be applied. 654 o For all pages, set up the Authentication-Control header "location- 655 when-logout=". 657 o In de-authentication pages, no specific set-up is needed. If 658 there is any direct links to it, put "logout-timeout=0". 660 5.1.3. Case 3: specific page displayed before log-in 662 If the site needs to display a specific page before log-in actions 663 (some announces, user notices, or even advertisements), the following 664 settings can be applied. 666 o Set up an optional authentication to all pages available to guest. 667 Set up an Authentication-Control header with "no-auth=true". Put 668 a link to a specific log-in page in contents. 670 o If there are pages only available to authenticated users, Set up a 671 mandatory authentication with "location-when-unauthenticated=". 674 o For the specific log-in page, Set up a mandatory authentication. 676 o For all pages for POST requests, it is advisable to have 677 "location-when-logout=", too. 679 o De-authentication pages are not needed. If the site will have 680 one, put "logout-timeout=0". 682 5.2. Example 2: authenticated user-only sites 684 If almost all pages in the target site requires authentication (e.g., 685 an Internet banking site), or there are no needs to support both 686 unauthenticated and authenticated users on the same resource, the 687 setting will become somewhat simple. The following are an example to 688 realize such a site: 690 o Set up a mandatory authentication to all pages available to 691 authenticated. Set up an Authentication-Control header with 692 "auth-style=non-modal" setting. 694 o Set up a handler for the 401-status which requests users to 695 authenticate. 697 o For all pages for POST requests, it is advisable to have 698 "location-when-logout=", too. 700 o De-authentication pages are not needed. If the site will have 701 one, put "logout-timeout=0" there. 703 5.3. When to use Cookies 705 In the current Web sites using Form-based authentications, Cookies 706 [RFC6265] are used for managing both authorization and application 707 sessions. Using the extensions in this document, the former features 708 will be provided by using (extended) HTTP authentication/ 709 authorization mechanisms. In some cases, there will be some 710 ambiguous situations whether some functions are authorization 711 management or session management. The following hints will be 712 helpful for deciding which features to be used. 714 o If there is a need to serve multiple sessions for a single user 715 using multiple browsers concurrently, use a Cookie for 716 distinguishing between sessions for the same user. (C.f. if there 717 is a need to distinguish sessions in the same browser, HTML5 Web 718 Storage [W3C.CR-webstorage-20111208] features may be used instead 719 of Cookies.) 721 o If a web site is currently deploying a session time-out feature, 722 consider who benefits from the feature. In most cases, the main 723 requirement for such feature is to protect users from their 724 consoles and browsers hijacked (i.e. benefits are on the users' 725 side). In such cases, the time-out features provided in this 726 extension may be used. On the other hand, the requirements is to 727 protect server's privilege (e.g. when some regulations require to 728 limit the time difference between user's two-factor authentication 729 and financial transaction commitment; the requirement is strictly 730 on the servers' side), that should be managed on the server side 731 using Cookies or other session management mechanisms. 733 5.4. Parallel deployment with Form/Cookie authentications 735 In some transition periods, sites may need to support both HTTP-layer 736 and Form-based authentications. The following example shows one way 737 to achieve that. 739 o If Cookies are used even for HTTP-authenticated users, each 740 session determined by Cookies should identify which authentication 741 are used for the session. 743 o First, set up any of the above settings for enabling HTTP-layer 744 authentication. 746 o For unauthenticated users, put the following things to the Web 747 pages, unless the client supports this extension and HTTP-level 748 authentication. 750 * For non-mandatory authenticated pages, put a link to Form-based 751 authenticated pages. 753 * For mandatory authenticated pages, either put a link to Form- 754 based authenticated pages, or put a HTML-level redirection 755 (using META element) to such pages. 757 o In Form-based authenticated pages, if users are not authenticated, 758 it may have a diversion for HTTP-level authentication by 759 "location-when-unauthenticated" setting. 761 o Users are identified for authorizations and content customizations 762 by the following logic. 764 * First, check the result of the HTTP-level authentication. If 765 there is a Cookie session tied to a specific user, both ones 766 should match. 768 * If the user is not authenticated on the HTTP-level, use the 769 conventional Form-based method to determine the user. 771 * If there is a Cookie tied to an HTTP authentication, but there 772 is no corresponding HTTP authentication result, that session 773 will be discarded (because it means that authentication is 774 deactivated by the corresponding user). 776 6. Methods to extend this protocol 778 If a private extension to this protocol is implemented, it MUST use 779 the extension-param to avoid conflicts with this protocol and other 780 future official extensions. 782 Extension-tokens MAY be freely used for any non-standard, private, 783 and/or experimental uses. The extension-tokens MUST be with format 784 "-.", where is a validly 785 registered (sub-)domain name on the Internet owned by the party who 786 defines the extensions. Unknown parameter names are to be ignored 787 regardless of whether it is extension-tokens or bare-tokens. 789 7. IANA Considerations 791 Tokens used for the authentication control parameters may be either 792 extension-tokens or bare-tokens as outlined in Section 2.2. When 793 bare-tokens are used in this protocol, these MUST be allocated by 794 IANA. Any tokens used for non-private, non-experimental parameters 795 are RECOMMENDED to be registered to IANA, regardless of the kind of 796 tokens used. 798 To acquire registered tokens, a specification for the use of such 799 tokens MUST be available as a publicly-accessible documents, as 800 outlined as "Specification Required" level in [RFC5226]. 802 Note: More formal declarations will be added in the future drafts to 803 meet the RFC 5226 requirements. 805 8. Security Considerations 807 The purpose of the log-out timeout feature in the Authentication- 808 control header is to protect users of clients from impersonation 809 caused by an attacker having access to the same console. Server 810 application implementors SHOULD be aware that the directive may 811 always be ignored by either malicious clients or clients not 812 supporting this extension. If the purpose of introducing a timeout 813 for an authentication period is to protect server-side resources, 814 such features MUST be implemented by other means such as HTTP Cookies 815 [RFC6265]. 817 All parameters in Authentication-Control header SHOULD NOT be used 818 for any security-enforcement purposes. Server-side applications MUST 819 be implemented always considering that the header may be either 820 ignored by clients or even bypassed by users. 822 9. References 824 9.1. Normative References 826 [I-D.ietf-httpbis-p1-messaging] 827 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 828 1: URIs, Connections, and Message Parsing", 829 draft-ietf-httpbis-p1-messaging-19 (work in progress), 830 March 2012. 832 [I-D.ietf-httpbis-p7-auth] 833 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 834 7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in 835 progress), March 2012. 837 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 838 Requirement Levels", BCP 14, RFC 2119, March 1997. 840 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 841 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 842 May 2008. 844 9.2. Informative References 846 [I-D.oiwa-http-mutualauth] 847 Oiwa, Y., Watanabe, H., Takagi, H., Kihara, B., Hayashi, 848 T., and Y. Ioku, "Mutual Authentication Protocol for 849 HTTP", draft-oiwa-http-mutualauth-12 (work in progress), 850 June 2012. 852 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 853 April 2011. 855 [W3C.CR-webstorage-20111208] 856 Hickson, I., "Web Storage", World Wide Web Consortium 857 CR CR-webstorage-20111208, December 2011, 858 . 860 Appendix A. (Informative) Applicability of features for each messages 862 This section provides cross-reference table about applicability of 863 each features provided in this specification for each kinds of 864 responses described in Section 2.1. The table provided in this 865 section is for informative purposes only. 867 +-------------------+-------+----------+-----------+------+ 868 | | init. | success. | intermed. | neg. | 869 +-------------------+-------+----------+-----------+------+ 870 | Optional auth. | O | n | N | N | 871 | auth-style | O | - | - | O | 872 | loc.-when-unauth. | O | I | I | i | 873 | no-auth | O | I | I | i | 874 | loc.-when-logout | - | O | - | - | 875 | logout-timeout | - | O | - | - | 876 +-------------------+-------+----------+-----------+------+ 878 Legends: 879 O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain 880 i = SHOULD be ignored; I = MUST be ignored; 881 - = meaningless (to be ignored) 883 Appendix B. (Informative) Draft Notes 885 Things which might be considered for future revisions: 887 o In [I-D.ietf-httpbis-p7-auth], meaning of WWW-Authenticate headers 888 in non-401 responses are defined as "supplying credentials (or 889 different credentials) might affect the response". This 890 clarification change leaves a way for using 200-status responses 891 along with a WWW-Authenticate header for providing optional 892 authentication. 893 Incorporating this possibility, however, needs more detailed 894 analysis on the behavior of existing clients and intermediate 895 proxies for such possibly-confusing responses. Optional-WWW- 896 Authenticate is safer, at least for minimum backward 897 compatibility, because clients not supporting this extension will 898 consider this header as an unrecognized entity-header, possibly 899 providing opportunity for silently falling-back to application- 900 level authentications. 902 Appendix C. (Informative) Draft Change Log 904 C.1. Changes in revision 02 906 o Added usage examples. 908 C.2. Changes in revision 01 910 o Syntax notations and parsing semantics changed to match httpbis 911 style. 913 C.3. Changes in revision 00 915 o Separated from HTTP Mutual authentication proposal (-09). 917 o Adopting httpbis works as a referencing point to HTTP. 919 o Generalized, now applicable for all HTTP authentication schemes. 921 o Added "no-auth" and "auth-style" parameters. 923 o Loosened standardization requirements for parameter-name tokens 924 registration. 926 Authors' Addresses 928 Yutaka Oiwa 929 National Institute of Advanced Industrial Science and Technology 930 Research Institute for Secure Systems 931 Tsukuba Central 2 932 1-1-1 Umezono 933 Tsukuba-shi, Ibaraki 934 JP 936 Email: mutual-auth-contact-ml@aist.go.jp 937 Hajime Watanabe 938 National Institute of Advanced Industrial Science and Technology 940 Hiromitsu Takagi 941 National Institute of Advanced Industrial Science and Technology 943 Boku Kihara 944 Lepidum Co. Ltd. 945 #602, Village Sasazuka 3 946 1-30-3 Sasazuka 947 Shibuya-ku, Tokyo 948 JP 950 Tatsuya Hayashi 951 Lepidum Co. Ltd. 953 Yuichi Ioku 954 Yahoo! Japan, Inc. 955 Midtown Tower 956 9-7-1 Akasaka 957 Minato-ku, Tokyo 958 JP