idnits 2.17.1 draft-ietf-httpauth-extension-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 7, 2016) is 2850 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5987 (Obsoleted by RFC 8187) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) == Outdated reference: A later version (-11) exists of draft-ietf-httpauth-mutual-08 -- Obsolete informational reference (is this intentional?): RFC 7564 (Obsoleted by RFC 8264) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPAUTH Working Group Y. Oiwa 3 Internet-Draft H. Watanabe 4 Intended status: Experimental H. Takagi 5 Expires: January 8, 2017 ITRI, AIST 6 T. Hayashi 7 Lepidum 8 Y. Ioku 9 Individual 10 July 7, 2016 12 HTTP Authentication Extensions for Interactive Clients 13 draft-ietf-httpauth-extension-07 15 Abstract 17 This document specifies extensions for the HTTP authentication 18 framework for interactive clients. Currently, fundamental features 19 of HTTP-level authentication are insufficient for complex 20 requirements of various Web-based applications. This forces these 21 applications to implement their own authentication frameworks by 22 means like HTML forms, which becomes one of the hurdles against 23 introducing secure authentication mechanisms handled jointly by 24 servers and user-agent. The extended framework fills gaps between 25 Web application requirements and HTTP authentication provisions to 26 solve the above problems, while maintaining compatibility with 27 existing Web and non-Web uses of HTTP authentications. 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 8, 2017. 46 Copyright Notice 48 Copyright (c) 2016 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 3.1. Note on Optional-WWW-Authenticate and use of 70 WWW-Authenticate header with non-401 status . . . . . . . 9 71 4. Authentication-Control header . . . . . . . . . . . . . . . . 11 72 4.1. Non-ASCII extended header parameters . . . . . . . . . . . 12 73 4.2. Auth-style parameter . . . . . . . . . . . . . . . . . . . 13 74 4.3. Location-when-unauthenticated parameter . . . . . . . . . 14 75 4.4. No-auth parameter . . . . . . . . . . . . . . . . . . . . 15 76 4.5. Location-when-logout parameter . . . . . . . . . . . . . . 15 77 4.6. Logout-timeout parameter . . . . . . . . . . . . . . . . . 16 78 4.7. Username parameter . . . . . . . . . . . . . . . . . . . . 17 79 5. Usage examples . . . . . . . . . . . . . . . . . . . . . . . . 17 80 5.1. Example 1: a portal site . . . . . . . . . . . . . . . . . 18 81 5.1.1. Case 1: a simple application . . . . . . . . . . . . . 18 82 5.1.2. Case 2: specific action required on log-out . . . . . 19 83 5.1.3. Case 3: specific page displayed before log-in . . . . 19 84 5.2. Example 2: authenticated user-only sites . . . . . . . . . 19 85 5.3. When to use Cookies . . . . . . . . . . . . . . . . . . . 20 86 5.4. Parallel deployment with Form/Cookie authentications . . . 20 87 6. Methods to extend this protocol . . . . . . . . . . . . . . . 21 88 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 89 8. Security Considerations . . . . . . . . . . . . . . . . . . . 23 90 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 91 9.1. Normative References . . . . . . . . . . . . . . . . . . . 24 92 9.2. Informative References . . . . . . . . . . . . . . . . . . 24 93 Appendix A. (Informative) Applicability of features for each 94 messages . . . . . . . . . . . . . . . . . . . . . . 25 95 Appendix B. (Informative) Draft Change Log . . . . . . . . . . . 25 96 B.1. Changes in Httpauth WG Revision 07 . . . . . . . . . . . . 25 97 B.2. Changes in Httpauth WG Revision 06 . . . . . . . . . . . . 25 98 B.3. Changes in Httpauth WG Revision 05 . . . . . . . . . . . . 26 99 B.4. Changes in Httpauth WG revision 04 . . . . . . . . . . . . 26 100 B.5. Changes in Httpauth WG revision 03 . . . . . . . . . . . . 26 101 B.6. Changes in Httpauth WG revision 02 . . . . . . . . . . . . 26 102 B.7. Changes in Httpauth WG revision 01 . . . . . . . . . . . . 26 103 B.8. Changes in Httpauth revision 00 and HttpBis revision 00 . 26 104 B.9. Changes in revision 02 . . . . . . . . . . . . . . . . . . 26 105 B.10. Changes in revision 01 . . . . . . . . . . . . . . . . . . 26 106 B.11. Changes in revision 00 . . . . . . . . . . . . . . . . . . 26 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 109 1. Introduction 111 This document defines several extensions to the current HTTP 112 authentication framework, to provide functionality comparable with 113 current widely-used form-based Web authentication. A majority of the 114 recent websites on the Internet use custom application-layer 115 authentication implementations using Web forms. The reasons for 116 these may vary, but many people believe that the current HTTP Basic 117 and Digest authentication methods do not have enough functionality 118 (including good user interfaces) to support most realistic Web-based 119 applications. However, such use of form-based Web authentication has 120 several weakness against attacks like phishing, because all behavior 121 of the authentication is controlled from the server-side application. 122 This makes it really hard to implement any cryptographically strong 123 authentication mechanisms into Web systems. To overcome this 124 problem, we need to "modernize" the HTTP authentication framework so 125 that better client-controlled secure methods can be used with Web 126 applications. The extensions proposed in this document include: 128 o optional authentication on HTTP (Section 3), 130 o log out from both server and client side (Section 4), and 132 o finer control for redirection depending on authentication status 133 (Section 4). 135 1.1. Terminology 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 139 "OPTIONAL" in this document are to be interpreted as described in 140 [RFC2119]. 142 The terms "encouraged" and "advised" are used for suggestions that do 143 not constitute "SHOULD"-level requirements. People MAY freely choose 144 not to include the suggested items. However, complying with those 145 suggestions would be a best practice; it will improve the security, 146 interoperability, and/or operational performance. 148 This document distinguishes the terms "client" and "user" in the 149 following way: A "client" is an entity understanding and talking HTTP 150 and the specified authentication protocol, usually computer software; 151 a "user" is a (usually natural) person who wants to access data 152 resources using "a client". 154 2. Definitions 156 2.1. Terms for describing authentication protocol flow 158 HTTP Authentication defined in [RFC7235] can involve several pairs of 159 HTTP requests/responses. Throughout this document, the following 160 terms are used to categorize those messages: for requests, 162 1) A non-authenticating request is a request not attempting any 163 authentication: a request without any Authorization header field. 165 2) An authenticating request is the opposite: a request with an 166 Authorization header field. 168 For responses, 170 1) A non-authenticated response is a response which does not involve 171 any HTTP authentication. It does not contain any WWW-Authenticate 172 or Authentication-Info header field. 174 Servers send this response when the requested resource is not 175 protected by an HTTP authentication mechanism. In context of this 176 specification, non-authentication-related negative responses (e.g. 177 403 and 404) are also considered non-authenticated responses. 179 (See note on successfully-authenticated responses below for some 180 ambiguous cases.) 182 2) An authentication-initializing response is a response which 183 requires or allows clients to start authentication attempts. 184 Servers send this response when the requested resource is 185 protected by HTTP authentication mechanism, and the request meets 186 one of the following cases: 188 * The request is a non-authenticating request, or 190 * The request contained an authentication trial directed to a 191 protection space (realm) other than the one the server 192 expected. 194 The server will specify the protection space for authentication in 195 this response. 197 Upon receiving this response, the client's behavior is further 198 divided to two possible cases. 200 * If the client has no prior knowledge on authentication 201 credentials (e.g. a user-name and a password) related to the 202 requested protection space, the protocol flow terminates and 203 the client will ask the user to provide authentication 204 credentials, 206 * On the other hand, if client already has enough authentication 207 credentials to the requested protection space, the client will 208 automatically send an authenticating request. Such cases often 209 occur when the client did not know beforehand that the current 210 request-URL requires authentication. 212 3) A successfully-authenticated response is a response for an 213 authenticating request meaning that the authentication attempt was 214 granted. (Note: if the authentication scheme used does not use an 215 Authentication-Info header field, it can't be distinguishable from 216 a non-authenticated response.) 218 4) An intermediate authenticating response is a response for an 219 authenticating request which requires more reaction by the client 220 software without involving users. Such a response is required 221 when an authentication scheme requires two or more round-trip 222 messages to perform authentication, or when an authentication 223 scheme uses some speculative short-cut method (such as uses of 224 cached shared secrets) and it failed. 226 5) A negatively-authenticated response is a response for an 227 authenticating request which means that the authentication attempt 228 was declined and can not continue without a different set of 229 authentication credentials. Clients typically erase memory of the 230 active credentials and ask the user for other ones. 232 Usually the format of these responses are as same as the one for 233 authentication-initializing responses. Clients can distinguish 234 negatively-authenticated responses from authentication- 235 initializing responses by comparing the protection spaces 236 contained in the request and in the response. 238 Figure 1 shows a state diagram of generic HTTP authentication with 239 the above message categorization. Note that many authentication 240 schemes use only a subset of the transitions described on the 241 diagram. Labels in the figure show the abbreviated names of response 242 types. 244 =========== ----------------- 245 NEW REQUEST ( UNAUTHENTICATED ) 246 =========== ----------------- 247 | ^ non-auth. 248 v | response 249 +----------------------+ NO +-------------+ 250 | The requested URI |--------------------------->| send normal | 251 | known to be auth'ed? | ---------------->| request | 252 +----------------------+ / +-------------+ 253 YES | / initializing| 254 v / | 255 +------------------+ NO / | 256 | Can auth-req.(*1)|--------- | 257 | be constructed? | | 258 +------------------+ | 259 YES | initializing | 260 | ---------------------------------------. | 261 | / v v 262 | | ---------------- NO +-----------+ 263 | | ( AUTH-REQUESTED )<------|credentials| 264 | | ---------------- | known? | 265 v | +-----------+ 266 +-----------+ negative ------------- negative |YES 267 | send |---------->( AUTH-FAILED )<---------, | 268 /| auth-req | ------------- | | 269 / +-----------+\ | v 270 | \ \ intermediate +-----------+ 271 | \ -------------------------------->| send | 272 | \ | auth-req | 273 | non-auth. \successful successful +-----------+ 274 | response (*2) \ / | ^ 275 v \ / | | 276 ----------------- \ -------------- / `----' 277 ( UNAUTHENTICATED ) ----->( AUTH-SUCCEED )<---- intermediate 278 ----------------- -------------- 280 Figure 1: Generic state diagram for HTTP authentication 282 Note: (*1) For example, "Digest" scheme requires server-provided 283 nonce to construct client-side challenges. 284 (*2) In "Basic" and some others, this cannot be distinguished from a 285 successfully-authenticated response. 287 2.2. Syntax Notation 289 This specification uses an extended ABNF syntax defined in [RFC7230] 290 and [RFC5234]. The following syntax definitions are quoted from 292 [RFC7230] and [RFC7235]: auth-scheme, quoted-string, auth-param, SP, 293 BWS, header-field, and challenge. It also uses the convention of 294 using header field names for specifying the syntax of values for the 295 header field. 297 Additionally, this specification uses the following syntax 298 definitions as a refinement for token and the right-hand-side of 299 auth-param in [RFC7235]. (Note: these definitions are consistent 300 with those in [I-D.ietf-httpauth-mutual].) 302 bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") 303 extension-token = "-" bare-token 1*("." bare-token) 304 extensive-token = bare-token / extension-token 305 integer = "0" / (%x31-39 *%x30-39) ; no leading zeros 307 Figure 2: the BNF syntax for common notations 309 Extensive-tokens are used in this protocol where the set of 310 acceptable tokens includes private extensions. Any extensions of 311 this protocol MAY use either bare-tokens allocated by IANA (under the 312 procedure described in Section 7), or extension-tokens with the 313 format "-.", where is a valid 314 (sub-)domain name on the Internet owned by the party who defines the 315 extension. 317 3. Optional Authentication 319 The Optional-WWW-Authenticate header enables a non-mandatory 320 authentication, which is not possible under the current HTTP 321 authentication mechanism. 323 In several Web applications, users can access the same contents as 324 both a guest user and an authenticated user. In most Web 325 applications, this functionality is implemented using HTTP cookies 326 [RFC6265] and custom form-based authentication. The new 327 authentication method using this message will provide a replacement 328 for these authentication systems. 330 Servers MAY send HTTP non-interim responses containing the 331 Optional-WWW-Authenticate header as a replacement of a 401 response 332 when it the response is authentication-initializing. The 333 Optional-WWW-Authenticate header MUST NOT sent on 401 responses (i.e. 334 a usual WWW-Authenticate header MUST be used on 401 responses.) 336 HTTP/1.1 200 OK 337 Optional-WWW-Authenticate: Basic realm="xxxx" 339 Optional-WWW-Authenticate = 1#challenge 341 Figure 3: BNF syntax for Optional-WWW-Authenticate header 343 The challenges contained in the Optional-WWW-Authenticate header are 344 the same as those for a 401 responses corresponding to the same 345 request. For authentication-related matters, an optional 346 authentication request will have the same meaning as a 401 message 347 with a corresponding WWW-Authenticate header (as an authentication- 348 initializing response). (The behavior for other matters MAY be 349 different between the optional authentication and 401 messages. For 350 example, clients MAY choose to cache the 200 messages with 351 Optional-WWW-Authenticate header field but not the 401 messages by 352 default.) 354 A response with an Optional-WWW-Authenticate header SHOULD be 355 returned from the server only when the request is either non- 356 authenticated or authenticating to a wrong (not the server's 357 expected) protection space. If a response is either an intermediate 358 or a negative response to a client's authentication attempt, the 359 server MUST respond with a 401 status response with a 360 WWW-Authenticate header instead. Failure to comply with this rule 361 will render clients unable to distinguish authentication successes 362 and failures. 364 The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate 365 header in a positive response when a client's authentication attempt 366 succeeds. 368 Whenever an authentication scheme supports servers sending some 369 parameter which gives a hint of the URL space for the corresponding 370 protection space for the same realm (e.g. "path" or "domain"), 371 servers requesting non-mandatory authentication SHOULD send such 372 parameter with the response. Clients supporting non-mandatory 373 authentication MUST recognize the parameter, and MUST send a request 374 with an appropriate authentication credential in an Authorization 375 header for any URI inside the specified paths. 377 Support of this header is OPTIONAL; clients MAY also implement this 378 extension only for some selected authentication schemes. New 379 authentication schemes can make support of the optional 380 authentication mandatory by its specification, though. 382 3.1. Note on Optional-WWW-Authenticate and use of WWW-Authenticate 383 header with non-401 status 385 In the current specification of HTTP/1.1, it is clarified that the 386 WWW-Authenticate header can be used with messages with status codes 387 other than 401 (Authentication Required). Especially, the use of 388 WWW-Authenticate header with the 200 status messages implies a very 389 similar meaning to the above-defined Optional-WWW-Authenticate 390 header. 392 The design of Optional-WWW-Authenticate header expects that the use 393 of a new header guarantees that clients which is unaware of this 394 extension will ignore the header, and that Web developers can rely on 395 that behavior to implement a secondary fallback method of 396 authentications. Several behavioral requirements written in the 397 above section also assumes this property, and defines a necessary 398 functionality to implement an HTTP optional authentication reliably 399 and consistently. 401 On the other hand, some experiments and discussions on the IETF 402 mailing list revealed that most of (but not necessarily all of) the 403 existing HTTP clients, at the time of writing, just ignores the WWW- 404 Authenticate headers in non-401 messages, giving the similar behavior 405 with the Optional-WWW-Authenticate. However, every corner case of 406 behavior was not fully tested, nor well-defined in the existing 407 specifications. 409 Considering these situations, the author of this document chose to 410 use a new header for a new feature "experiment". This is to avoid 411 defining every corner-case behavior for the existing standard WWW- 412 Authentication header in this experimental document, which could be 413 considered by some implementer as an "incompatible changes to 414 existing specification". 416 Experimentally, the authors propose implementer of the standard 417 HTTP/1.1 specification (especially implementer of this extension) to 418 implement undefined (implementation-dependant) detailed handling of 419 WWW-Authenticate header with non-401 status messages as similar as 420 those defined above for the Optional-WWW-Authenticate header. For 421 example, we propose for servers to return 401 status for failed 422 authentication attempts, even when the unauthenticated request to the 423 same resource will result in the 200 status. This can realize how 424 (whether) we can implement non-mandatory authentication using the 425 standard header fields and status codes. If this experiment is 426 successful, the future revision of this experimental document may 427 "bless" and recommend the use of standard WWW-Authenticate header, 428 with some "standard-level" requirements on some corner case behavior. 430 4. Authentication-Control header 432 Authentication-Control = 1#auth-control-entry 433 auth-control-entry = auth-scheme 1*SP 1#auth-control-param 434 auth-control-param = extensive-token BWS "=" BWS token 435 / extensive-token "*" BWS "=" BWS ext-value 436 ext-value = 438 Figure 4: the BNF syntax for the Authentication-Control header 440 The Authentication-Control header provides a more precise control of 441 the client behavior for Web applications using an HTTP authentication 442 protocol. This header is supposed to be generated in the application 443 layer, as opposed to WWW-Authenticate headers which will usually be 444 generated by the Web servers. 446 Support of this header is OPTIONAL, and clients MAY choose any subset 447 of these parameters to be supported. The set of supported parameters 448 MAY also be authentication scheme-dependent. However, some 449 authentication schemes can require mandatory/recommended support for 450 some or all of the features provided in this header. 452 The Authentication-Control header contains one or more 453 "authentication control entries" each of which corresponds to a 454 single realm for a specific authentication scheme. If the 455 auth-scheme specified for an entry supports the HTTP "realm" feature, 456 that entry MUST contain the "realm" parameter. If not, the entry 457 MUST NOT contain the "realm" parameter. 459 Among the multiple entries in the header, the relevant entries in the 460 header are those corresponding to an auth-scheme and a realm (if 461 any), for which "the authentication process is being performed, or 462 going to be performed". In more detail, 464 (1) If the response is either an authentication-initializing 465 response or a negatively-authenticated response, there can be 466 multiple challenges in the WWW-Authenticate header (or the 467 Optional-WWW-Authenticate header defined in this extension), 468 each of which corresponds to a different scheme and realm. In 469 this case, the client has a choice on the scheme and realm they 470 will use to authenticate. Only the entry in the 471 Authentication-Control header corresponding to that scheme and 472 realm are relevant. 474 (2) If the response is either an intermediate authenticating 475 response or a successfully-authenticated response, the scheme 476 and realm given in the Authorization header of the HTTP request 477 will determine the currently-ongoing authentication process. 479 Only the entry corresponding to that scheme and realm are 480 relevant. 482 The server MAY send an Authentication-Control header containing non- 483 relevant entries. The client MUST ignore all non-relevant entries it 484 received. 486 Each entry contains one or more parameters, each of which is a name- 487 value pair. The name of each parameter MUST be an extensive-token. 488 Clients MUST ignore any unknown parameters contained in this header. 489 The entries for the same auth-scheme and the realm MUST NOT contain 490 duplicated parameters for the same name. Clients MAY either take any 491 one of those duplicated entries or ignore all of them. 493 The type of parameter value depends on the parameter name as defined 494 in the following subsections. Regardless of the type, however, the 495 recipients MUST accept both quoted and unquoted representations of 496 values as defined in HTTP. If the parameter is defined to have a 497 string value, implementations MUST send any value outside of the 498 "token" ABNF syntax in either a quoted form or an an ext-value form 499 (see Section 4.1). If the parameter is defined as a token (or 500 similar) or an integer, the value SHOULD follow the corresponding 501 ABNF syntax after possible unquoting of the quoted-string value (as 502 defined in HTTP), and MUST be sent in an plain (not an ext-value) 503 form. (Note: the rest of this document will show all string-value 504 parameters in quoted forms, and others in unquoted forms.) 506 Any parameters contained in this header MAY be ignored by clients. 507 Also, even when a client accepts this header, users are able to 508 circumvent the semantics of this header. Therefore, if this header 509 is used for security purposes, its use MUST be limited to providing 510 some non-fundamental additional security measures valuable for end- 511 users (such as client-side log-out for protecting against console 512 takeover). Server-side applications MUST NOT rely on the use of this 513 header for protecting server-side resources. 515 Note: The header syntax allows servers to specify Authentication- 516 Control for multiple authentication schemes, either as multiple 517 occurrences of this header or as a combined single header (see 518 Section 3.2.2 of [RFC7230] for rationale). The same care as for 519 parsing multiple authentication challenges needs to be taken. 521 4.1. Non-ASCII extended header parameters 523 Parameters contained in the Authentication-Control header MAY be 524 extended to non-ASCII values using the framework described in 525 [RFC5987]. All servers and clients MUST be capable of receiving and 526 sending values encoded in [RFC5987] syntax. 528 If a value to be sent contains only ASCII characters, the field MUST 529 be sent using plain RFC 7235 syntax. The syntax as extended by ext- 530 value MUST NOT be used in this case. 532 If a value (except the "realm" header) contains one or more non-ASCII 533 characters, the parameter SHOULD be sent using the ext-value syntax 534 defined in Section 3.2 of [RFC5987]. Such a parameter MUST have a 535 charset value of "UTF-8", and the language value MUST always be 536 omitted (have an empty value). The same parameter MUST NOT be sent 537 more than once, regardless of the used syntax. 539 For example, a parameter "username" with value "Renee of France" 540 SHOULD be sent as < username="Renee of France" >. If the value is 541 "Rene of France", it SHOULD be sent as 542 < username*=UTF-8''Ren%C3%89e%20of%20France > instead. 544 Interoperability note: [RFC7235], Section 2.2, defines the "realm" 545 authentication parameter which cannot be replaced by the "realm*" 546 extend parameter. It means that the use of non-ASCII values for an 547 authentication realm is not the defined behavior in the HTTP. 548 Unfortunately, some people currently use non-ASCII realm parameter in 549 reality, but even its encoding scheme is not well-defined. 550 Given this background, this document does not specify how to handle 551 non-ASCII "realm" parameter in the extended header fields. If 552 needed, the authors propose to use a non-extended "realm" parameter 553 form, with a wish for maximum interoperability. 555 4.2. Auth-style parameter 557 Example: 558 Authentication-Control: Digest realm="protected space", 559 auth-style=modal 561 The parameter "auth-style" specifies the server's preferences for 562 user interface behavior for user authentication. This parameter can 563 be included in any kind of response, however, it is only meaningful 564 for either authentication-initializing or negatively-authenticated 565 responses. The value of this parameter MUST be one of the bare- 566 tokens "modal" or "non-modal". When the Optional-WWW-Authenticate 567 header is used, the value of this parameter MUST be disregarded and 568 the value "non-modal" is implied. 570 The value "modal" means that the server thinks the content of the 571 response (body and other content-related headers) is valuable only 572 for users refusing the authentication request. The clients are 573 expected to ask the user for a password before processing the 574 content. This behavior is common for most of the current 575 implementations of Basic and Digest authentication schemes. 577 The value "non-modal" means that the server thinks the content of the 578 response (body and other content-related headers) is valuable for 579 users before processing an authentication request. The clients are 580 expected to first process the content and then provide users the 581 opportunity to perform authentication. 583 The default behavior for clients is implementation-dependent, and it 584 may also depending on authentication schemes. The proposed default 585 behavior is "modal" for all authentication schemes unless otherwise 586 specified. 588 The above two different methods of authentication possibly introduce 589 a observable difference of semantics when the response contains 590 state-changing side effects; for example, it can affect how Cookie 591 headers [RFC6265] in 401 responses are processed. However, the 592 server applications SHOULD NOT depend on existence of such side 593 effects. 595 4.3. Location-when-unauthenticated parameter 597 Example: 598 Authentication-Control: Mutual realm="auth-space-1", 599 location-when-unauthenticated="http://www.example.com/login.html" 601 The parameter "location-when-unauthenticated" specifies a location 602 where any unauthenticated clients should be redirected to. This 603 header can be used, for example, when there is a central login page 604 for the entire Web application. The value of this parameter is a 605 string that contains an URL location. If a received URL is not 606 absolute, the clients SHOULD consider it a relative URL from the 607 current location. 609 This parameter MAY be used with a 401 response for an authentication- 610 initializing response. It can also be contained, although this is 611 NOT RECOMMENDED, in a positive response with an 612 Optional-WWW-Authenticate header. The clients MUST ignore this 613 parameter when a response is either successfully-authenticated or 614 intermediately-authenticated. 616 When a client receives an authentication-initiating response with 617 this parameter, and if the client has to ask users for authentication 618 credentials, the client will treat the entire response as if it were 619 a 303 "See Other" response with a Location header that contains the 620 value of this parameter (i.e., client will be redirected to the 621 specified location with a GET request). Unlike a normal 303 622 response, if the client can process authentication without the user's 623 interaction, this parameter MUST be ignored. 625 4.4. No-auth parameter 627 Example: 628 Authentication-Control: Basic realm="entrance", no-auth=true 630 The parameter "no-auth" is a variant of the 631 location-when-unauthenticated parameter; it specifies that new 632 authentication attempts are not to be performed on this location in 633 order to improve the user experience, without specifying the 634 redirection on the HTTP level. This header can be used, for example, 635 when there is a central login page for the entire Web application, 636 and when an explicit user interaction with the Web content is desired 637 before authentications. The value of this parameter MUST be a token 638 "true". If the value is incorrect, client MAY ignore this parameter. 640 This parameter MAY be used with authentication-initiating responses. 641 It can also be contained, although this is NOT RECOMMENDED, in a 642 positive response with an Optional-WWW-Authenticate header. The 643 clients MUST ignore this parameter when a response is either 644 successfully-authenticated or intermediately-authenticated. 646 When a client receives an authentication-initiating response with 647 this parameter, if the client has to ask users for authentication 648 credentials, the client will ignore the WWW-Authenticate header 649 contained in the response and treat the whole response as a normal 650 negative 4xx-class response instead of giving the user an opportunity 651 to start authentication. If the client can process authentication 652 without the user's interaction, this parameter MUST be ignored. 654 This parameter SHOULD NOT be used along with the 655 location-when-unauthenticated parameter. If both were supplied, 656 clients MAY choose which one is to be honored. 658 This parameter SHOULD NOT be used as a security measure to prevent 659 authentication attempts, as it is easily circumvented by users. This 660 parameter SHOULD be used solely for improving user experience of Web 661 applications. 663 4.5. Location-when-logout parameter 665 Example: 666 Authentication-Control: Digest realm="protected space", 667 location-when-logout="http://www.example.com/byebye.html" 669 The parameter "location-when-logout" specifies a location where the 670 client is to be redirected when the user explicitly requests a 671 logout. The value of this parameter MUST be a string that contains 672 an URL location. If a given URL is not absolute, the clients MUST 673 consider it a relative URL from the current location. 675 This parameter MAY be used with successfully-authenticated responses. 676 If this parameter is contained in other kinds of responses, the 677 clients MUST ignore this parameter. 679 When the user requests termination of an authentication period, and 680 if the client currently displays a page supplied by a response with 681 this parameter, the client will be redirected to the specified 682 location by a new GET request (as if it received a 303 response). 683 The log-out operation (e.g. erasing memories of user name, 684 authentication credential and all related one-time credentials such 685 as nonce or keys) SHOULD occur before processing a redirection. 687 When the user requests termination of an authentication period, if 688 the client supports this parameter but the server response does not 689 contain this parameter, the client's RECOMMENDED behavior is as 690 follows: if the request corresponding to the current content was GET 691 method, reload the page without the authentication credential. 692 Otherwise, keep the current content as-is and simply forget the 693 authentication status. The client SHOULD NOT replay a non-idempotent 694 request without the user's explicit approval. 696 Web applications are encouraged to send this parameter with an 697 appropriate value for any responses (except those with redirection 698 (3XX) statuses) for non-GET requests. 700 4.6. Logout-timeout parameter 702 Example: 703 Authentication-Control: Basic realm="entrance", logout-timeout=300 705 The parameter "logout-timeout", when contained in a successfully- 706 authenticated response, means that any authentication credentials and 707 state related to the current protection space are to be discarded if 708 a time specified in this header (in seconds) has passed since from 709 the time this header was received. The value MUST be an integer. As 710 a special case, the value 0 means that the client is requested to 711 immediately log-out from the current authentication space and revert 712 to an unauthenticated status. This does not, however, mean that the 713 long-term memories for the passwords and passwords-related details 714 (such as the password reminders and auto fill-ins) should be removed. 715 If a new timeout value is received for the same authentication space, 716 it cancels the previous timeout and sets a new timeout. 718 4.7. Username parameter 720 Example: 721 Authentication-Control: Basic realm="configuration", username="admin" 723 The parameter "username" tells that the only "user name" to be 724 accepted by the server is the value given in this parameter. This 725 parameter is particularly useful, for example, for routers and other 726 appliances with a Web configuration interface. 728 This parameter MAY be used with authentication-initiating responses 729 or negatively-authenticated responses requiring another attempt of 730 authentication. The clients MUST ignore this parameter when a 731 response is either successfully-authenticated or intermediately- 732 authenticated. 734 If the authentication scheme to be used has a syntax limitation on 735 the allowed user names (e.g. Basic and Digest do not allow colons in 736 user names), the specified value MUST follow that limitation. 737 Clients SHOULD ignore any values which do not conform to such 738 limitations. 740 Also, if the used authentication scheme requires a specific style of 741 text preparation for the user name (e.g., PRECIS [RFC7564] string 742 preparation or Unicode normalization), the server SHOULD send the 743 values satisfying such requirements (so that clients can use the 744 given user name as is). 746 Clients MAY still send any authentication requests with other user 747 names, possibly in vain. Servers are not strictly required to reject 748 user names other than specified, but doing so will give bad user 749 experiences and may confuse users and clients. 751 5. Usage examples 753 This section shows some examples for applying this extension to 754 typical websites which are using Forms and cookies for managing 755 authentication and authorization. The content of this section is not 756 normative and for illustrative purposes only. 758 In these examples, we assume that there are two kinds of clients (Web 759 browsers). One kind of these implements all features described in 760 the previous sections. We also assume that browsers will have a user 761 interface which allows users to deactivate (log-out from) current 762 authentication sessions. The other kind are the "existing" 763 implementations which do not support any of these features. 765 When not explicitly specified, all settings described below are to be 766 applied with Authentication-Control headers, and these can be sent to 767 clients regardless of the authentication status (these will be 768 silently ignored whenever not effective). 770 5.1. Example 1: a portal site 772 This subsection provides an example application for a site whose 773 structure is somewhat similar to conventional portal sites. In 774 particular, most web pages are available for guest (unauthenticated) 775 users, and if authentication is performed, the content of these pages 776 is customized for each user. We assume the site has the following 777 kinds of pages currently: 779 o Content pages. 781 o Pages/mechanism for performing authentication: 783 * There is one page which asks a user name and a password using a 784 HTML POST form. 786 * After the authentication attempt, the user will be redirected 787 to either the page which is previously displayed before the 788 authentication, or some specific page. 790 o A de-authentication (log-out) page. 792 5.1.1. Case 1: a simple application 794 When such a site does not require specific actions upon log-in and 795 log-out, the following simple settings can be used. 797 o Set up an optional authentication to all pages available to 798 guests. Set up an Authentication-Control header with "auth- 799 style=non-modal" setting. 801 o If there are pages only available to authenticated users, set up a 802 mandatory authentication with "auth-style=non-modal" setting. 804 o No specific pages for authentication are needed. It will be 805 performed automatically, directed by the above setting. 807 o A de-authentication page is also not needed. If the site has one, 808 put "logout-timeout=0" there. 810 o For all pages for POST requests, it is advisable to have 811 "location-when-logout=". 813 5.1.2. Case 2: specific action required on log-out 815 If the site requires specific actions upon log-out, the following 816 settings can be used. 818 o All settings in the Case 1 are applied. 820 o For all pages, set up the Authentication-Control header "location- 821 when-logout=". 823 o In the de-authentication page, no specific set-up is needed. If 824 there are any direct links to the de-authentication page, put 825 "logout-timeout=0". 827 5.1.3. Case 3: specific page displayed before log-in 829 If the site needs to display a specific page before log-in actions 830 (some announcements, user notices, or even advertisements), the 831 following settings can be applied. 833 o Set up an optional authentication to all pages available to 834 guests. Set up an Authentication-Control header with "no- 835 auth=true". Put a link to a specific log-in page in contents. 837 o If there are pages only available to authenticated users, set up a 838 mandatory authentication with "location-when-unauthenticated=". 841 o For the specific log-in page, set up a mandatory authentication. 843 o For all pages for POST requests, it is advisable to have 844 "location-when-logout=", too. 846 o De-authentication pages are not needed. If the site has one, put 847 "logout-timeout=0". 849 5.2. Example 2: authenticated user-only sites 851 If almost all pages in the target site require authentication (e.g., 852 an Internet banking site), or if there are no needs to support both 853 unauthenticated and authenticated users on the same resource, the 854 settings will become simpler. The following are an example for such 855 a site: 857 o Set up a mandatory authentication to all pages available to 858 authenticated users. Set up an Authentication-Control header with 859 "auth-style=non-modal" setting. 861 o Set up a handler for the 401-status which requests users to 862 authenticate. 864 o For all pages for POST requests, it is advisable to have 865 "location-when-logout=", too. 867 o De-authentication pages are not needed. If the site will have 868 one, put "logout-timeout=0" there. 870 5.3. When to use Cookies 872 In the current Web sites using form-based authentications, Cookies 873 [RFC6265] are used for managing both authorization and application 874 sessions. Using the extensions in this document, the former features 875 will be provided by using (extended) HTTP authentication/ 876 authorization mechanisms. In some cases, there will be ambiguity on 877 whether some functions are for authorization management or for 878 session management. The following hints will be helpful for deciding 879 which features to use. 881 o If there is a need to serve multiple sessions for a single user 882 using multiple browsers concurrently, use a Cookie for 883 distinguishing between sessions for the same user. (C.f. if there 884 is a need to distinguish sessions in the same browser, HTML5 Web 885 Storage [W3C.REC-webstorage-20130730] features can be used instead 886 of Cookies.) 888 o If a web site is currently deploying a session time-out feature, 889 consider who benefits from the feature. In most cases, the main 890 requirement for such a feature is to protect users from having 891 their consoles and browsers hijacked (i.e. benefits are on the 892 users' side). In such cases, the time-out features provided in 893 this extension can be used. On the other hand, the requirement is 894 to protect server's privilege (e.g. when some regulations require 895 to limit the time difference between user's two-factor 896 authentication and financial transaction commitment; the 897 requirement is strictly on the servers' side), that should be 898 managed on the server side using Cookies or other session 899 management mechanisms. 901 5.4. Parallel deployment with Form/Cookie authentications 903 In some transition periods, sites can need to support both HTTP-layer 904 and form-based authentication. The following example shows one way 905 to achieve that. 907 o If Cookies are used even for HTTP-authenticated users, each 908 session determined by Cookies SHOULD identify which authentication 909 has been used for the session. 911 o First, set up any of the above settings for enabling HTTP-layer 912 authentication. 914 o For unauthenticated users, add the following things to the Web 915 pages, unless the client supports this extension and HTTP-level 916 authentication. 918 * For non-mandatory authenticated pages, put a link to Form-based 919 authenticated pages. 921 * For mandatory authenticated pages, either put a link to Form- 922 based authenticated pages, or put a HTML-level redirection 923 (using >META http-equiv="refresh" ...< element) to such pages. 925 o In Form-based authenticated pages, if users are not authenticated, 926 the page can provide a redirection for HTTP-level authentication 927 by "location-when-unauthenticated" setting. 929 o Users are identified to authorization and content customization by 930 the following logic. 932 * First, check the result of the HTTP-level authentication. If 933 there is a Cookie session tied to a specific user, both should 934 match. 936 * If the user is not authenticated on the HTTP-level, use the 937 conventional Form-based method to determine the user. 939 * If there is a Cookie tied to HTTP authentication, but there is 940 no corresponding HTTP authentication result, that session will 941 be discarded (because it means that authentication is 942 deactivated by the corresponding user). 944 6. Methods to extend this protocol 946 If a private extension to this protocol is implemented, it MUST use 947 the extension-param to avoid conflicts with this protocol and any 948 other extensions. (Standardized or being-standardized extensions MAY 949 use either bare-tokens or extension-tokens.) 951 When bare-tokens are used in this protocol, these MUST be allocated 952 by IANA. Any tokens used for non-private, non-experimental 953 parameters are RECOMMENDED to be registered to IANA, regardless of 954 the kind of tokens used. 956 Extension-tokens MAY be freely used for any non-standard, private, 957 and/or experimental uses. An extension-tokens MUST use the format 958 "-.", where is a validly 959 registered (sub-)domain name on the Internet owned by the party who 960 defines the extensions. Any unknown parameter name is to be ignored 961 regardless of whether it is an extension-token or a bare-token. 963 7. IANA Considerations 965 This document defines two new entries for the "Permanent Message 966 Header Field Names" registry. 968 +---------------------------+----------+----------------------------+ 969 | Header Field Name | Protocol | Specification | 970 +---------------------------+----------+----------------------------+ 971 | Optional-WWW-Authenticate | http | Section 3 of this document | 972 | Authentication-Control | http | Section 4 of this document | 973 +---------------------------+----------+----------------------------+ 975 This document also establishes a registry for HTTP authentication 976 control parameters. The registry manages case-insensitive ASCII 977 strings. The string MUST follow the extensive-token syntax defined 978 in Section 2.2. 980 To acquire registered tokens, a specification for the use of such 981 tokens MUST be available as a publicly-accessible documents, as 982 outlined as "Specification Required" level in [RFC5226]. 984 Registrations for authentication control parameters are required to 985 include a description of the control extension. New registrations 986 are advised to provide the following information: 988 o Token: a token used in HTTP headers for identifying the algorithm. 990 o Specification: A reference for a specification defining the 991 algorithm. 993 The initial content of this registry is as follows: 995 +-------------------------------+------------------------------+ 996 | Token | Specification | 997 +-------------------------------+------------------------------+ 998 | auth-style | Section 4.2 of this document | 999 | location-when-unauthenticated | Section 4.3 of this document | 1000 | no-auth | Section 4.4 of this document | 1001 | location-when-logout | Section 4.5 of this document | 1002 | logout-timeout | Section 4.6 of this document | 1003 | username | Section 4.7 of this document | 1004 +-------------------------------+------------------------------+ 1006 8. Security Considerations 1008 The purpose of the log-out timeout feature in the Authentication- 1009 control header is to protect users of clients from impersonation 1010 caused by an attacker having access to the same console. The server 1011 application implementer SHOULD be aware that the directive may always 1012 be ignored by either malicious clients or clients not supporting this 1013 extension. If the purpose of introducing a timeout for an 1014 authentication period is to protect server-side resources, this 1015 protection MUST be implemented by other means such as HTTP Cookies 1016 [RFC6265]. 1018 All parameters in the Authentication-Control header SHOULD NOT be 1019 used for any security-enforcement purposes. Server-side applications 1020 MUST NOT assume that the header will be honored by clients and users. 1022 The "username" parameter sometimes reveals sensitive information 1023 about the HTTP server and its configurations, useful for security 1024 attacks. The use of the "username" parameter SHOULD be limited to 1025 cases where the all of the following conditions are met: 1027 (1) the valid user name is pre-configured and not modifiable (such 1028 as root, admin or similar ones); 1030 (2) the valid user name for such an appliance is publicly known (for 1031 example, written in a manual document); and 1033 (3) either the valid user name for the server is easily guessable by 1034 other means (for example, from the model number shown in an 1035 unauthenticated page), or the server is only accessible from 1036 limited networks. 1038 Most importantly, the "username" parameter SHOULD NOT be used in any 1039 case when the valid user names can be changed by users or 1040 administrators. 1042 9. References 1044 9.1. Normative References 1046 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1047 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1048 RFC2119, March 1997, 1049 . 1051 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1052 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1053 DOI 10.17487/RFC5226, May 2008, 1054 . 1056 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1057 Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/ 1058 RFC5234, January 2008, 1059 . 1061 [RFC5987] Reschke, J., "Character Set and Language Encoding for 1062 Hypertext Transfer Protocol (HTTP) Header Field 1063 Parameters", RFC 5987, DOI 10.17487/RFC5987, August 2010, 1064 . 1066 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1067 Protocol (HTTP/1.1): Message Syntax and Routing", 1068 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1069 . 1071 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1072 Protocol (HTTP/1.1): Authentication", RFC 7235, 1073 DOI 10.17487/RFC7235, June 2014, 1074 . 1076 9.2. Informative References 1078 [I-D.ietf-httpauth-mutual] 1079 Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, 1080 T., and Y. Ioku, "Mutual Authentication Protocol for 1081 HTTP", draft-ietf-httpauth-mutual-08 (work in progress), 1082 July 2016. 1084 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 1085 DOI 10.17487/RFC6265, April 2011, 1086 . 1088 [RFC7564] Saint-Andre, P. and M. Blanchet, "PRECIS Framework: 1089 Preparation, Enforcement, and Comparison of 1090 Internationalized Strings in Application Protocols", 1091 RFC 7564, DOI 10.17487/RFC7564, May 2015, 1092 . 1094 [W3C.REC-webstorage-20130730] 1095 Hickson, I., "Web Storage", World Wide Web Consortium 1096 Recommendation REC-webstorage-20130730, July 2013, 1097 . 1099 Appendix A. (Informative) Applicability of features for each messages 1101 This section provides a cross-reference table showing the 1102 applicability of the features provided in this specification to each 1103 kind of responses described in Section 2.1. The table provided in 1104 this section is for informative purposes only. 1106 +-------------------+-------+----------+-----------+------+ 1107 | | init. | success. | intermed. | neg. | 1108 +-------------------+-------+----------+-----------+------+ 1109 | Optional auth. | O | n | N | N | 1110 | auth-style | O | - | - | O | 1111 | loc.-when-unauth. | O | I | I | i | 1112 | no-auth | O | I | I | i | 1113 | loc.-when-logout | - | O | - | - | 1114 | logout-timeout | - | O | - | - | 1115 | username | O | - | - | O | 1116 +-------------------+-------+----------+-----------+------+ 1118 Legends: 1119 O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain 1120 i = SHOULD be ignored; I = MUST be ignored; 1121 - = meaningless (to be ignored) 1123 Appendix B. (Informative) Draft Change Log 1125 [To be removed on final publication] 1127 B.1. Changes in Httpauth WG Revision 07 1129 o WGLC comments are reflected to the text. 1131 B.2. Changes in Httpauth WG Revision 06 1133 o Several comments from reviewers are reflected to the text. 1135 B.3. Changes in Httpauth WG Revision 05 1137 o Authors' addresses updated. 1139 B.4. Changes in Httpauth WG revision 04 1141 o IANA consideration section added. 1143 B.5. Changes in Httpauth WG revision 03 1145 o Adopting RFC 5987 extended syntax for non-ASCII parameter values. 1147 B.6. Changes in Httpauth WG revision 02 1149 o Added realm parameter. 1151 o Added username parameter. We acknowledge Michael Sweet's proposal 1152 for including this to the Basic authentication. 1154 B.7. Changes in Httpauth WG revision 01 1156 o Clarification on peers' responsibility about handling of relative 1157 URLs. 1159 o Automatic reloading should be allowed only on safe methods, not 1160 always on idempotent methods. 1162 B.8. Changes in Httpauth revision 00 and HttpBis revision 00 1164 None. 1166 B.9. Changes in revision 02 1168 o Added usage examples. 1170 B.10. Changes in revision 01 1172 o Syntax notations and parsing semantics changed to match httpbis 1173 style. 1175 B.11. Changes in revision 00 1177 o Separated from HTTP Mutual authentication proposal (-09). 1179 o Adopting httpbis works as a referencing point to HTTP. 1181 o Generalized, now applicable for all HTTP authentication schemes. 1183 o Added "no-auth" and "auth-style" parameters. 1185 o Loosened standardization requirements for parameter-name tokens 1186 registration. 1188 Authors' Addresses 1190 Yutaka Oiwa 1191 National Institute of Advanced Industrial Science and Technology 1192 Information Technology Research Institute 1193 Tsukuba Central 1 1194 1-1-1 Umezono 1195 Tsukuba-shi, Ibaraki 1196 JP 1198 Email: mutual-auth-contact-ml@aist.go.jp 1200 Hajime Watanabe 1201 National Institute of Advanced Industrial Science and Technology 1202 Information Technology Research Institute 1203 Tsukuba Central 1 1204 1-1-1 Umezono 1205 Tsukuba-shi, Ibaraki 1206 JP 1208 Hiromitsu Takagi 1209 National Institute of Advanced Industrial Science and Technology 1210 Information Technology Research Institute 1211 Tsukuba Central 1 1212 1-1-1 Umezono 1213 Tsukuba-shi, Ibaraki 1214 JP 1216 Tatsuya Hayashi 1217 Lepidum Co. Ltd. 1218 #602, Village Sasazuka 3 1219 1-30-3 Sasazuka 1220 Shibuya-ku, Tokyo 1221 JP 1222 Yuichi Ioku 1223 Individual