idnits 2.17.1 draft-oiwa-httpbis-auth-extension-00.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 4342 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-httpbis-auth-extension-00 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 HttpBis revision 00 . . . . . . . . . . . . . . 21 94 C.2. Changes in revision 02 . . . . . . . . . . . . . . . . . . 21 95 C.3. Changes in revision 01 . . . . . . . . . . . . . . . . . . 21 96 C.4. Changes in revision 00 . . . . . . . . . . . . . . . . . . 21 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 21 99 1. Introduction 101 The document proposes several extensions to the current HTTP 102 authentication framework, to provide enough functionality comparable 103 with current widely-used form-based Web authentication. A majority 104 of the recent Web-sites on the Internet use custom application-layer 105 authentication implementations using Web forms. The reasons for 106 these may vary, but many people believe that the current HTTP Basic 107 (and Digest, too) authentication method does not have enough 108 functionality (including a good-feeling user interfaces) to support 109 most of realistic Web-based applications. However, the method is 110 very weak against phishing and other attacks, because the whole 111 behavior of the authentication is controlled from the server-side 112 applications. This makes it really hard to implement any 113 cryptographically strong authentication mechanisms into Web systems. 114 To overcome this problem, we need to "modernize" the HTTP 115 authentication framework so that better client-controlled secure 116 methods can be used with Web applications. The extensions proposed 117 in this document include: 119 o non-mandatory, optional authentication on HTTP (Section 3), 121 o log out from both server and client side (Section 4), and 123 o finer control for redirection depending on authentication status 124 (Section 4). 126 [I-D note: These extensions are initially proposed as a part of 127 [I-D.oiwa-http-mutualauth]. However, since these functionalities 128 might possibly be useful in combination even with other 129 authentication schemes, the extensions were separated from the 130 original document as this independent draft.] 132 1.1. Terminology 134 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 135 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 136 "OPTIONAL" in this document are to be interpreted as described in 137 [RFC2119]. 139 The terms "encouraged" and "advised" are used for suggestions that do 140 not constitute "SHOULD"-level requirements. People MAY freely choose 141 not to include the suggested items regarding [RFC2119], but complying 142 with those suggestions would be a best practice; it will improve the 143 security, interoperability, and/or operational performance. 145 This document distinguishes the terms "client" and "user" in the 146 following way: A "client" is an entity understanding and talking HTTP 147 and the specified authentication protocol, usually computer software; 148 a "user" is a (usually natural) person who wants to access data 149 resources using "a client". 151 2. Definitions 153 2.1. Terms for describing authentication protocol flow 155 HTTP Authentication defined in [I-D.ietf-httpbis-p7-auth] may involve 156 with several pairs of HTTP requests/responses. Throughout this 157 document, the following terms are used to categorize those messages: 158 for requests, 160 o A non-authenticating request is a request not attempting any 161 authentication: a request without any Authorization header. 163 o An authenticating request is the opposite: a request with an 164 Authorization header. 166 For responses, 168 1) A non-authenticated response: is a response which does not 169 involve with any HTTP authentication. It may not contain any 170 WWW-Authenticate or Authentication-Info header. 172 Servers send this response when the requested resource is not 173 protected by HTTP authentication mechanisms. In context of this 174 specification, not-authentication-related negative responses (e.g. 175 403 and 404) are also considered as non-authenticated responses. 177 (See note on successfully-authenticated responses below for some 178 ambiguous cases.) 180 2) An authentication-initializing response: is a response which 181 requires or allows clients to start authentication attempts. 182 Servers send this response when the requested resource is 183 protected by HTTP authentication mechanism, and the request meets 184 one of the following cases: 186 * The request is non-authenticating request, or 188 * The request contained an authentication trial directed to the 189 protection space (realm) other than the server's expected one. 191 The server will specify the protection space for authentication in 192 this response. 194 Upon reception, the client's behavior is further divided to two 195 possible cases. 197 * If the client may have no prior knowledge on authentication 198 credentials (e.g. a user-name and a password) related to the 199 requested protection space, the protocol flow terminates and 200 the client will ask the user to provide authentication 201 credentials, 203 * On the other hand, if client already have an enough credentials 204 for authentication to the requested protection space, the 205 client will automatically send an authenticating request. Such 206 cases often occur when the client did not know beforehand that 207 the current request-URL requires an authentication. 209 3) A successfully-authenticated response: is a response for an 210 authenticating request meaning that the authentication attempt was 211 granted. (Note: if the authentication scheme used does not use an 212 Authentication-Info header, it may be indistinguishable from a 213 non-authenticated response.) 215 4) An intermediate authenticating response: is a response for an 216 authenticating request which requires some more reaction by the 217 client software without involving users. Such a response is 218 required when an authentication scheme requires two or more round- 219 trip messages to perform authentication, or when an authentication 220 scheme uses some speculative short-cut method (such as uses of 221 cached shared secrets) and it failed. 223 5) A negatively-authenticated response: is a response for an 224 authenticating request which means that the authentication attempt 225 was declined and can not continue without another authentication 226 credential. Clients typically erase memory of the currently-using 227 credentials and ask the user for other ones. 229 Usually the format of these responses are as same as the one for 230 authentication-initializing responses. Client can distinguish it 231 by comparing the protection spaces contained in the request and in 232 the response. 234 Figure 1 shows a state diagram of generic HTTP authentication with 235 the above message categorization. Note that many authentication 236 schemes uses only a subset of the transitions described on the 237 diagram. Labels in the figure show the abbreviated names of response 238 types. 240 =========== ----------------- 241 NEW REQUEST ( UNAUTHENTICATED ) 242 =========== ----------------- 243 | ^ non-auth. 244 v | response 245 +----------------------+ NO +-------------+ 246 | The requested URI |--------------------------->| send normal | 247 | known to be auth'ed? | ---------------->| request | 248 +----------------------+ / +-------------+ 249 YES | / initializing| 250 v / | 251 +------------------+ NO / | 252 | Can auth-req (*1)|--------- | 253 | be constructed? | | 254 +------------------+ | 255 YES | initializing | 256 | ---------------------------------------. | 257 | / v v 258 | | ---------------- NO +-----------+ 259 | | ( AUTH-REQUESTED )<------|credentials| 260 | | ---------------- | known? | 261 v | +-----------+ 262 +-----------+ negative ------------- negative |YES 263 | send |---------->( AUTH-FAILED )<---------, | 264 /| auth-req | ------------- | | 265 / +-----------+\ | v 266 | \ \ intermediate +-----------+ 267 | \ -------------------------------->| send | 268 | \ | auth-req | 269 | non-auth. \successful successful +-----------+ 270 | response (*2) \ / | ^ 271 v \ / | | 272 ----------------- \ -------------- / `----' 273 ( UNAUTHENTICATED ) ----->( AUTH-SUCCEED )<---- intermediate 274 ----------------- -------------- 276 Figure 1: Generic state diagram for HTTP authentication 278 Note: (*1) For example, "Digest" scheme requires server-provided 279 nonces to construct client-side challenges. 280 (*2) In "Basic" and some others, this cannot be distinguished from a 281 successfully-authenticated response. 283 2.2. Syntax Notation 285 This specification uses an extended BNF syntax defined in 286 [I-D.ietf-httpbis-p1-messaging]. The following syntax definitions 287 are quoted from [I-D.ietf-httpbis-p1-messaging] and 288 [I-D.ietf-httpbis-p7-auth]: auth-scheme, quoted-string, auth-param, 289 SP, header-field, and challenge. It also uses the convention of 290 using header names for specifying syntax of header values. 292 Additionally, this specification uses the following syntax elements 293 following syntax definitions as a refinement for token and the 294 righthand-side of auth-param in [I-D.ietf-httpbis-p7-auth]. (Note: 295 these definitions are consistent with those in 296 [I-D.oiwa-http-mutualauth].) 298 bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 299 extension-token = "-" bare-token 1*("." bare-token) 300 extensive-token = bare-token / extension-token 301 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 303 Figure 2: the BNF syntax for common notations 305 Extensive-tokens are used in this protocol where the set of 306 acceptable tokens may include private extensions. Any private 307 extensions of this protocol MUST use the extension-tokens with format 308 "-.", where is a validly registered 309 (sub-)domain name on the Internet owned by the party who defines the 310 extensions. 312 3. Optional Authentication 314 The Optional-WWW-Authenticate header enables a non-mandatory 315 authentication, which is not possible under the current HTTP 316 authentication mechanism. In several Web applications, users can 317 access the same contents as both a guest user and an authenticated 318 user. In most Web applications, it is implemented using HTTP cookies 319 [RFC6265] and custom form-based authentications. The new 320 authentication method using this message will provide a replacement 321 for these authentication systems. 323 Servers MAY send HTTP successful responses (response code 200, 206 324 and others) containing the Optional-WWW-Authenticate header as a 325 replacement of a 401 response when it is an authentication- 326 initializing response. The Optional-WWW-Authenticate header MUST NOT 327 be contained in 401 responses. 329 HTTP/1.1 200 OK 330 Optional-WWW-Authenticate: Basic realm="xxxx" 332 Optional-WWW-Authenticate = challenge 334 Figure 3: BNF syntax for Optional-WWW-Authenticate header 336 The challenge contained in the Optional-WWW-Authenticate header are 337 the same as those for a 401 responses corresponding for a same 338 request. For authentication-related matters, an optional 339 authentication request will have the same meaning as a 401 message 340 with a corresponding WWW-Authenticate header (as an authentication- 341 initializing response). (The behavior for other matters, such as 342 caching, MAY be different between the optional authentication and 401 343 messages.) 345 A response with an Optional-WWW-Authenticate header SHOULD be 346 returned from the server only when the request is either non- 347 authenticated or authenticating to a wrong (not the server's 348 expected) protection space. If a response is either an intermediate 349 or a negative response to a client's authentication attempt, the 350 server MUST respond with a 401 status response with a 351 WWW-Authenticate header instead. Failure to comply this rule will 352 make client not able to distinguish authentication successes and 353 failures. 355 The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate 356 header in a positive response when a client's authentication attempt 357 succeeds. 359 Whenever an authentication scheme support for servers to send some 360 parameter which gives a hint of URL space for the corresponding 361 protection space for the same realm (e.g. "path" or "domain"), 362 servers requesting non-mandatory authentication SHOULD send such 363 parameter with the response. Clients supporting non-mandatory 364 authentication MUST recognize the parameter, and MUST send a request 365 with an appropriate authentication credential in an Authorization 366 header for any URI inside the specified paths. 368 Support of this header is OPTIONAL; Clients MAY also choose any set 369 of authentication schemes for which optional authentication is 370 supported (in other words, its support MAY be scheme-dependent). 371 However, some authentication schemes MAY require mandatory/ 372 recommended support for this header, so that server-side applications 373 MAY assume that clients supporting such schemes are likely to support 374 the extension as well. 376 4. Authentication-Control header 377 Authentication-Control = auth-scheme 1*SP 1#auth-param 379 Figure 4: the BNF syntax for the Authentication-Control header 381 The Authentication-Control header provides a more precise control of 382 the client behavior for Web applications using an HTTP authentication 383 protocol. This header is supposed to be generated in the application 384 layer, as opposed to WWW-Authenticate headers which will be generated 385 usually by the Web servers. 387 Support of this header is OPTIONAL, and clients MAY choose any subset 388 of these parameters to be supported. The set of supported parameters 389 MAY also be authentication scheme-dependent. However, some 390 authentication schemes MAY require mandatory/recommended support for 391 some or all of the features provided in this header. 393 The "auth-scheme" specified in this header and other authentication- 394 related headers within the same message MUST be the same. If there 395 are no authentication currently performed, and the auth-scheme 396 contained in this header is not recognizable for the client, the 397 whole header SHOULD be ignored. 399 The header contain one or more parameters, each of which is a name- 400 value pair. The name of each parameter MUST be an extensive-token. 401 Clients MUST ignore any unknown parameters contained in this header. 403 The type of parameter value depends on the parameter name as defined 404 in the following subsections. Regardless of the type, however, the 405 recipients SHOULD accept both quoted and unquoted representations of 406 values as defined in HTTP. If it is defined as a string, it is 407 encouraged to be sent in a quoted-string form. If it defined as a 408 token (or similar) or an integer, the value SHOULD follow the 409 corresponding ABNF syntax after possible unquoting of the quoted- 410 string value (as defined in HTTP), and is encouraged to be sent in a 411 unquoted form. 413 Server-side application SHOULD always be reminded that any parameters 414 contained in this header MAY be ignored by clients. Also, even when 415 a client accepts this header, users may always be able to circumvent 416 semantics of this header. Therefore, if this header is used for 417 security purposes, its use MUST be limited for providing some non- 418 fundamental additional security measures valuable for end-users (such 419 as client-side log-out for protecting against console takeover). 420 Server-side application MUST NOT rely on the use of this header for 421 protecting server-side resources. 423 4.1. Auth-style parameter 425 Authentication-Control: Digest auth-style=modal 427 The parameter "auth-style" specifies the server's preferences over 428 user interface behavior for user authentication. This parameter can 429 be included in any kind of responses, however, it is only meaningful 430 for either authentication-initializing or negatively-authenticated 431 responses. The value of this parameter MUST be one of the bare- 432 tokens "modal" or "non-modal". When the Optional-WWW-Authenticate 433 header is used, the value of this parameter MUST be disregarded and 434 the value "non-modal" is implied. 436 The value "modal" means that the server thinks the content of the 437 response (body and other content-related headers) is valuable only 438 for users refusing authentication request. The clients are expected 439 to ask the user a password before processing the content. This 440 behavior is common for most of the current implementations of Basic 441 and Digest authentication schemes. 443 The value "non-modal" means that the server thinks the content of the 444 response (body and other content-related headers) is valuable for 445 users before processing an authentication request. The clients are 446 expected to first process the content and then provide users 447 opportunities to perform authentication. 449 The default behavior for the clients is implementation-dependent, and 450 clients MAY choose different defaults for different authentication 451 schemes. The proposed default behavior is "modal" for all 452 authentication schemes, but specifications for authentication schemes 453 MAY propose a different default. 455 The above two different methods of authentication may introduce a 456 observable difference of semantics when the response contains state- 457 changing side effects; for example, it may change whether Cookie 458 headers [RFC6265] in 401 responses are processed or not. However, 459 the server applications SHOULD NOT depend on both existence and non- 460 existence of such side effects. 462 4.2. Location-when-unauthenticated parameter 464 Authentication-Control: Mutual 465 location-when-unauthenticated="http://www.example.com/login.html" 467 The parameter "location-when-unauthenticated" specifies a location 468 where any unauthenticated clients should be redirected to. This 469 header may be used, for example, when there is a central login page 470 for the entire Web application. The value of this parameter MUST be 471 a string that contains an absolute URL location. If a given URL is 472 not absolute, the clients MAY consider it a relative URL from the 473 current location. 475 This parameter MAY be used with a 401 response for authentication- 476 initializing response. It can also be contained, although 477 NOT RECOMMENDED, in a positive response with an 478 Optional-WWW-Authenticate header. The clients MUST ignore this 479 parameter, when a response is either successfully-authenticated or 480 intermediately-authenticated. The clients SHOULD ignore this 481 parameter when a response is a negatively-authenticated one (the case 482 is unlikely to happen, though). 484 When a client receives an authentication-initiating response with 485 this parameter, if the client has to ask users for authentication 486 credentials, the client will treat the entire response as if it were 487 a 303 "See Other" response with a Location header that contains the 488 value of this parameter (i.e., client will be redirected to the 489 specified location with a GET request). Unlike a normal 303 490 response, if the client can process authentication without the user's 491 interaction, this parameter MUST be ignored. 493 4.3. No-auth parameter 495 Authentication-Control: Basic no-auth=true 497 The parameter "no-auth" is a variant of the 498 location-when-unauthenticated parameter; it specifies that new 499 authentication attempt is not to be performed on this location for 500 better user experience, without specifying the redirection on the 501 HTTP level. This header may be used, for example, when there is a 502 central login page for the entire Web application, and when a (Web 503 content's level) explicit interaction of users is desired before 504 authentications. The value of this parameter MUST be a token "true". 505 If the value is incorrect, client MAY ignore this parameter. 507 This parameter MAY be used with authentication-initiating responses. 508 It can also be contained, although NOT RECOMMENDED, in a positive 509 response with an Optional-WWW-Authenticate header. The clients MUST 510 ignore this parameter, when a response is either successfully- 511 authenticated or intermediately-authenticated. The clients SHOULD 512 ignore this parameter when a response is a negatively-authenticated 513 one (the case is unlikely to happen, though). 515 When a client receives an authentication-initiating response with 516 this parameter, if the client has to ask users for authentication 517 credentials, the client will ignore the WWW-Authenticate header 518 contained in the response and treat the whole response as a normal 519 negative 4xx-class response instead of giving user an opportunity to 520 start authentication. If the client can process authentication 521 without the user's interaction, this parameter MUST ignored. 523 This parameter SHOULD NOT be used along with the 524 location-when-unauthenticated parameter. If both were supplied, 525 clients MAY choose which one is to be honored. 527 This parameter SHOULD NOT be used as any security measures to prevent 528 authentication attempts, as it is easily circumvented by users. This 529 parameter SHOULD be used solely for improving user experience of web 530 applications. 532 4.4. Location-when-logout parameter 534 Authentication-Control: Digest 535 location-when-logout="http://www.example.com/byebye.html" 537 The parameter "location-when-logout" specifies a location where the 538 client is to be redirected when the user explicitly request a logout. 539 The value of this parameter MUST be a string that contains an 540 absolute URL location. If a given URL is not absolute, the clients 541 MAY consider it a relative URL from the current location. 543 This parameter MAY be used with successfully-authenticated responses. 544 If this parameter is contained in other kinds of responses, the 545 clients MUST ignore this parameter. 547 When the user requests to terminate an authentication period, and if 548 the client currently displays a page supplied by a response with this 549 parameter, the client will be redirected to the specified location by 550 a new GET request (as if it received a 303 response). The log-out 551 operation (e.g. erasing memories of user name, authentication 552 credential and all related one-time credentials such as nonce or 553 keys) SHOULD occur before processing a redirection. 555 When the user requests to terminate an authentication period, if the 556 client supports this parameter but the server response does not 557 contain this parameter, the client's RECOMMENDED behavior is as 558 follows: if the request corresponding to the current content was 559 idempotent (e.g. GET), reload the page without the authentication 560 credential. If the request was non-idempotent (e.g. POST), keep the 561 current content as-is and simply forget the authentication status. 562 The client SHOULD NOT replay a non-idempotent request without the 563 user's explicit approval. 565 Web applications are encouraged to send this parameter with an 566 appropriate value for any responses (except those with redirection 567 (3XX) statuses) for non-GET requests. 569 4.5. Logout-timeout 571 Authentication-Control: Basic logout-timeout=300 573 The parameter "logout-timeout", when contained in a successfully- 574 authenticated response, means that any authentication credentials and 575 states related to the current protection space are to be discarded if 576 a time specified in this header (in seconds) has been passed from the 577 time received. The value MUST be an integer. As a special case, the 578 value 0 means that the client is requested to immediately log-out 579 from the current authentication space and revert to an 580 unauthenticated status. This does not, however, mean that the long- 581 term memories for the passwords (such as the password reminders and 582 auto fill-ins) should be removed. If a new timeout value is received 583 for the same authentication space, it cancels the previous timeout 584 and sets a new timeout. 586 5. Usage examples (informative) 588 This section shows some examples for applying this extension to 589 typical Web-sites which are using Forms and cookies for managing 590 authentication and authorization. The content of this section is not 591 normative and for illustrative purposes only. 593 We assume that all features described in the previous sections are 594 implemented in clients (Web browsers). We also assume that browsers 595 will have a user interface which allows users to deactivate (log-out 596 from) current authentication sessions. If this assumption is not 597 hold, texts below provides another approach with de-authentication 598 pages used instead of such a UI. 600 Without explicit notices, all settings described below are to be 601 applied with Authentication-Control headers, and these can be sent to 602 clients regardless of authentication statuses (these will be silently 603 ignored whenever not effective). 605 5.1. Example 1: a portal site 607 This subsection provides an example application for a site whose 608 structure is somewhat similar to conventional portal sites. In 609 particular, most of web pages are available for guest 610 (unauthenticated) users, and if authentication is performed, contents 611 of these pages are customized for each user. We assume the site has 612 the following kinds of pages currently: 614 o Content pages. 616 o Pages/mechanism for performing authentication: 618 * There is one page which asks a user name and a password using a 619 HTML POST form. 621 * After the authentication attempt, the user will be redirected 622 to either the page which is previously displayed before the 623 authentication, or some specific page. 625 o A de-authentication (log-out) page. 627 5.1.1. Case 1: a simple application 629 When such a site does not need a specific actions upon log-in and 630 log-out, the following simple settings can be used. 632 o Set up an optional authentication to all pages available to 633 guests. Set up an Authentication-Control header with "auth- 634 style=non-modal" setting. 636 o If there are pages only available to authenticated users, Set up a 637 mandatory authentication with "auth-style=non-modal" setting. 639 o No specific pages for authentication is needed. It will be 640 performed automatically, directed by the above setting. 642 o A de-authentication page is also not needed. If the site will 643 have one, put "logout-timeout=0" there. 645 o For all pages for POST requests, it is advisable to have 646 "location-when-logout=". 648 5.1.2. Case 2: specific action required on log-out 650 If the site needs a specific actions upon log-out, the following 651 settings can be used. 653 o All shown in the Case 1 are to be applied. 655 o For all pages, set up the Authentication-Control header "location- 656 when-logout=". 658 o In de-authentication pages, no specific set-up is needed. If 659 there is any direct links to it, put "logout-timeout=0". 661 5.1.3. Case 3: specific page displayed before log-in 663 If the site needs to display a specific page before log-in actions 664 (some announces, user notices, or even advertisements), the following 665 settings can be applied. 667 o Set up an optional authentication to all pages available to guest. 668 Set up an Authentication-Control header with "no-auth=true". Put 669 a link to a specific log-in page in contents. 671 o If there are pages only available to authenticated users, Set up a 672 mandatory authentication with "location-when-unauthenticated=". 675 o For the specific log-in page, Set up a mandatory authentication. 677 o For all pages for POST requests, it is advisable to have 678 "location-when-logout=", too. 680 o De-authentication pages are not needed. If the site will have 681 one, put "logout-timeout=0". 683 5.2. Example 2: authenticated user-only sites 685 If almost all pages in the target site requires authentication (e.g., 686 an Internet banking site), or there are no needs to support both 687 unauthenticated and authenticated users on the same resource, the 688 setting will become somewhat simple. The following are an example to 689 realize such a site: 691 o Set up a mandatory authentication to all pages available to 692 authenticated. Set up an Authentication-Control header with 693 "auth-style=non-modal" setting. 695 o Set up a handler for the 401-status which requests users to 696 authenticate. 698 o For all pages for POST requests, it is advisable to have 699 "location-when-logout=", too. 701 o De-authentication pages are not needed. If the site will have 702 one, put "logout-timeout=0" there. 704 5.3. When to use Cookies 706 In the current Web sites using Form-based authentications, Cookies 707 [RFC6265] are used for managing both authorization and application 708 sessions. Using the extensions in this document, the former features 709 will be provided by using (extended) HTTP authentication/ 710 authorization mechanisms. In some cases, there will be some 711 ambiguous situations whether some functions are authorization 712 management or session management. The following hints will be 713 helpful for deciding which features to be used. 715 o If there is a need to serve multiple sessions for a single user 716 using multiple browsers concurrently, use a Cookie for 717 distinguishing between sessions for the same user. (C.f. if there 718 is a need to distinguish sessions in the same browser, HTML5 Web 719 Storage [W3C.CR-webstorage-20111208] features may be used instead 720 of Cookies.) 722 o If a web site is currently deploying a session time-out feature, 723 consider who benefits from the feature. In most cases, the main 724 requirement for such feature is to protect users from their 725 consoles and browsers hijacked (i.e. benefits are on the users' 726 side). In such cases, the time-out features provided in this 727 extension may be used. On the other hand, the requirements is to 728 protect server's privilege (e.g. when some regulations require to 729 limit the time difference between user's two-factor authentication 730 and financial transaction commitment; the requirement is strictly 731 on the servers' side), that should be managed on the server side 732 using Cookies or other session management mechanisms. 734 5.4. Parallel deployment with Form/Cookie authentications 736 In some transition periods, sites may need to support both HTTP-layer 737 and Form-based authentications. The following example shows one way 738 to achieve that. 740 o If Cookies are used even for HTTP-authenticated users, each 741 session determined by Cookies should identify which authentication 742 are used for the session. 744 o First, set up any of the above settings for enabling HTTP-layer 745 authentication. 747 o For unauthenticated users, put the following things to the Web 748 pages, unless the client supports this extension and HTTP-level 749 authentication. 751 * For non-mandatory authenticated pages, put a link to Form-based 752 authenticated pages. 754 * For mandatory authenticated pages, either put a link to Form- 755 based authenticated pages, or put a HTML-level redirection 756 (using META element) to such pages. 758 o In Form-based authenticated pages, if users are not authenticated, 759 it may have a diversion for HTTP-level authentication by 760 "location-when-unauthenticated" setting. 762 o Users are identified for authorizations and content customizations 763 by the following logic. 765 * First, check the result of the HTTP-level authentication. If 766 there is a Cookie session tied to a specific user, both ones 767 should match. 769 * If the user is not authenticated on the HTTP-level, use the 770 conventional Form-based method to determine the user. 772 * If there is a Cookie tied to an HTTP authentication, but there 773 is no corresponding HTTP authentication result, that session 774 will be discarded (because it means that authentication is 775 deactivated by the corresponding user). 777 6. Methods to extend this protocol 779 If a private extension to this protocol is implemented, it MUST use 780 the extension-param to avoid conflicts with this protocol and other 781 future official extensions. 783 Extension-tokens MAY be freely used for any non-standard, private, 784 and/or experimental uses. The extension-tokens MUST be with format 785 "-.", where is a validly 786 registered (sub-)domain name on the Internet owned by the party who 787 defines the extensions. Unknown parameter names are to be ignored 788 regardless of whether it is extension-tokens or bare-tokens. 790 7. IANA Considerations 792 Tokens used for the authentication control parameters may be either 793 extension-tokens or bare-tokens as outlined in Section 2.2. When 794 bare-tokens are used in this protocol, these MUST be allocated by 795 IANA. Any tokens used for non-private, non-experimental parameters 796 are RECOMMENDED to be registered to IANA, regardless of the kind of 797 tokens used. 799 To acquire registered tokens, a specification for the use of such 800 tokens MUST be available as a publicly-accessible documents, as 801 outlined as "Specification Required" level in [RFC5226]. 803 Note: More formal declarations will be added in the future drafts to 804 meet the RFC 5226 requirements. 806 8. Security Considerations 808 The purpose of the log-out timeout feature in the Authentication- 809 control header is to protect users of clients from impersonation 810 caused by an attacker having access to the same console. Server 811 application implementors SHOULD be aware that the directive may 812 always be ignored by either malicious clients or clients not 813 supporting this extension. If the purpose of introducing a timeout 814 for an authentication period is to protect server-side resources, 815 such features MUST be implemented by other means such as HTTP Cookies 816 [RFC6265]. 818 All parameters in Authentication-Control header SHOULD NOT be used 819 for any security-enforcement purposes. Server-side applications MUST 820 be implemented always considering that the header may be either 821 ignored by clients or even bypassed by users. 823 9. References 825 9.1. Normative References 827 [I-D.ietf-httpbis-p1-messaging] 828 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 829 1: URIs, Connections, and Message Parsing", 830 draft-ietf-httpbis-p1-messaging-19 (work in progress), 831 March 2012. 833 [I-D.ietf-httpbis-p7-auth] 834 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 835 7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in 836 progress), March 2012. 838 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 839 Requirement Levels", BCP 14, RFC 2119, March 1997. 841 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 842 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 843 May 2008. 845 9.2. Informative References 847 [I-D.oiwa-http-mutualauth] 848 Oiwa, Y., Watanabe, H., Takagi, H., Kihara, B., Hayashi, 849 T., and Y. Ioku, "Mutual Authentication Protocol for 850 HTTP", draft-oiwa-httpbis-mutualauth-00 (work in 851 progress), June 2012. 853 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 854 April 2011. 856 [W3C.CR-webstorage-20111208] 857 Hickson, I., "Web Storage", World Wide Web Consortium 858 CR CR-webstorage-20111208, December 2011, 859 . 861 Appendix A. (Informative) Applicability of features for each messages 863 This section provides cross-reference table about applicability of 864 each features provided in this specification for each kinds of 865 responses described in Section 2.1. The table provided in this 866 section is for informative purposes only. 868 +-------------------+-------+----------+-----------+------+ 869 | | init. | success. | intermed. | neg. | 870 +-------------------+-------+----------+-----------+------+ 871 | Optional auth. | O | n | N | N | 872 | auth-style | O | - | - | O | 873 | loc.-when-unauth. | O | I | I | i | 874 | no-auth | O | I | I | i | 875 | loc.-when-logout | - | O | - | - | 876 | logout-timeout | - | O | - | - | 877 +-------------------+-------+----------+-----------+------+ 879 Legends: 880 O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain 881 i = SHOULD be ignored; I = MUST be ignored; 882 - = meaningless (to be ignored) 884 Appendix B. (Informative) Draft Notes 886 Things which might be considered for future revisions: 888 o In [I-D.ietf-httpbis-p7-auth], meaning of WWW-Authenticate headers 889 in non-401 responses are defined as "supplying credentials (or 890 different credentials) might affect the response". This 891 clarification change leaves a way for using 200-status responses 892 along with a WWW-Authenticate header for providing optional 893 authentication. 894 Incorporating this possibility, however, needs more detailed 895 analysis on the behavior of existing clients and intermediate 896 proxies for such possibly-confusing responses. Optional-WWW- 897 Authenticate is safer, at least for minimum backward 898 compatibility, because clients not supporting this extension will 899 consider this header as an unrecognized entity-header, possibly 900 providing opportunity for silently falling-back to application- 901 level authentications. 903 Appendix C. (Informative) Draft Change Log 905 C.1. Changes in HttpBis revision 00 907 None. 909 C.2. Changes in revision 02 911 o Added usage examples. 913 C.3. Changes in revision 01 915 o Syntax notations and parsing semantics changed to match httpbis 916 style. 918 C.4. Changes in revision 00 920 o Separated from HTTP Mutual authentication proposal (-09). 922 o Adopting httpbis works as a referencing point to HTTP. 924 o Generalized, now applicable for all HTTP authentication schemes. 926 o Added "no-auth" and "auth-style" parameters. 928 o Loosened standardization requirements for parameter-name tokens 929 registration. 931 Authors' Addresses 933 Yutaka Oiwa 934 National Institute of Advanced Industrial Science and Technology 935 Research Institute for Secure Systems 936 Tsukuba Central 2 937 1-1-1 Umezono 938 Tsukuba-shi, Ibaraki 939 JP 941 Email: mutual-auth-contact-ml@aist.go.jp 943 Hajime Watanabe 944 National Institute of Advanced Industrial Science and Technology 946 Hiromitsu Takagi 947 National Institute of Advanced Industrial Science and Technology 949 Boku Kihara 950 Lepidum Co. Ltd. 951 #602, Village Sasazuka 3 952 1-30-3 Sasazuka 953 Shibuya-ku, Tokyo 954 JP 956 Tatsuya Hayashi 957 Lepidum Co. Ltd. 959 Yuichi Ioku 960 Yahoo! Japan, Inc. 961 Midtown Tower 962 9-7-1 Akasaka 963 Minato-ku, Tokyo 964 JP