draft-ietf-httpauth-extension-05.txt   draft-ietf-httpauth-extension-06.txt 
HTTPAUTH Working Group Y. Oiwa HTTPAUTH Working Group Y. Oiwa
Internet-Draft H. Watanabe Internet-Draft H. Watanabe
Intended status: Experimental H. Takagi Intended status: Experimental H. Takagi
Expires: July 10, 2016 ITRI, AIST Expires: November 23, 2016 ITRI, AIST
T. Hayashi T. Hayashi
Lepidum Lepidum
Y. Ioku Y. Ioku
Individual Individual
January 7, 2016 May 22, 2016
HTTP Authentication Extensions for Interactive Clients HTTP Authentication Extensions for Interactive Clients
draft-ietf-httpauth-extension-05 draft-ietf-httpauth-extension-06
Abstract Abstract
This document specifies a few extensions of HTTP authentication This document specifies extensions of HTTP authentication framework
framework for interactive clients. Recently, fundamental features of for interactive clients. Recently, fundamental features of HTTP-
HTTP-level authentication is not enough for complex requirements of level authentication are insufficient for complex requirements of
various Web-based applications. This makes these applications to various Web-based applications. This forces these applications to
implement their own authentication frameworks using HTML Forms and implement their own authentication frameworks using HTML Forms and
other means, which becomes one of the hurdles against introducing other means, which becomes one of the hurdles against introducing
secure authentication mechanisms handled jointly by servers and user- secure authentication mechanisms handled jointly by servers and user-
agent clients. The extended framework fills gaps between Web agent. The extended framework fills gaps between Web application
application requirements and HTTP authentication provisions to solve requirements and HTTP authentication provisions to solve the above
the above problems, while maintaining compatibility against existing problems, while maintaining compatibility against existing Web and
Web and non-Web uses of HTTP authentications. non-Web uses of HTTP authentications.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 10, 2016. This Internet-Draft will expire on November 23, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 25 skipping to change at page 3, line 25
4.2. Auth-style parameter . . . . . . . . . . . . . . . . . . . 12 4.2. Auth-style parameter . . . . . . . . . . . . . . . . . . . 12
4.3. Location-when-unauthenticated parameter . . . . . . . . . 13 4.3. Location-when-unauthenticated parameter . . . . . . . . . 13
4.4. No-auth parameter . . . . . . . . . . . . . . . . . . . . 13 4.4. No-auth parameter . . . . . . . . . . . . . . . . . . . . 13
4.5. Location-when-logout parameter . . . . . . . . . . . . . . 14 4.5. Location-when-logout parameter . . . . . . . . . . . . . . 14
4.6. Logout-timeout parameter . . . . . . . . . . . . . . . . . 15 4.6. Logout-timeout parameter . . . . . . . . . . . . . . . . . 15
4.7. Username parameter . . . . . . . . . . . . . . . . . . . . 15 4.7. Username parameter . . . . . . . . . . . . . . . . . . . . 15
5. Usage examples (informative) . . . . . . . . . . . . . . . . . 16 5. Usage examples (informative) . . . . . . . . . . . . . . . . . 16
5.1. Example 1: a portal site . . . . . . . . . . . . . . . . . 16 5.1. Example 1: a portal site . . . . . . . . . . . . . . . . . 16
5.1.1. Case 1: a simple application . . . . . . . . . . . . . 17 5.1.1. Case 1: a simple application . . . . . . . . . . . . . 17
5.1.2. Case 2: specific action required on log-out . . . . . 17 5.1.2. Case 2: specific action required on log-out . . . . . 17
5.1.3. Case 3: specific page displayed before log-in . . . . 17 5.1.3. Case 3: specific page displayed before log-in . . . . 18
5.2. Example 2: authenticated user-only sites . . . . . . . . . 18 5.2. Example 2: authenticated user-only sites . . . . . . . . . 18
5.3. When to use Cookies . . . . . . . . . . . . . . . . . . . 18 5.3. When to use Cookies . . . . . . . . . . . . . . . . . . . 18
5.4. Parallel deployment with Form/Cookie authentications . . . 19 5.4. Parallel deployment with Form/Cookie authentications . . . 19
6. Methods to extend this protocol . . . . . . . . . . . . . . . 20 6. Methods to extend this protocol . . . . . . . . . . . . . . . 20
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
8. Security Considerations . . . . . . . . . . . . . . . . . . . 21 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22
9.1. Normative References . . . . . . . . . . . . . . . . . . . 22 9.1. Normative References . . . . . . . . . . . . . . . . . . . 22
9.2. Informative References . . . . . . . . . . . . . . . . . . 23 9.2. Informative References . . . . . . . . . . . . . . . . . . 23
Appendix A. (Informative) Applicability of features for each Appendix A. (Informative) Applicability of features for each
messages . . . . . . . . . . . . . . . . . . . . . . 23 messages . . . . . . . . . . . . . . . . . . . . . . 23
Appendix B. (Informative) Draft Notes . . . . . . . . . . . . . . 23 Appendix B. (Informative) Draft Change Log . . . . . . . . . . . 24
Appendix C. (Informative) Draft Change Log . . . . . . . . . . . 24 B.1. Changes in Httpauth WG Revision 06 . . . . . . . . . . . . 24
C.1. Changes in Httpauth WG revision 04 . . . . . . . . . . . . 24 B.2. Changes in Httpauth WG Revision 05 . . . . . . . . . . . . 24
C.2. Changes in Httpauth WG revision 03 . . . . . . . . . . . . 24 B.3. Changes in Httpauth WG revision 04 . . . . . . . . . . . . 24
C.3. Changes in Httpauth WG revision 02 . . . . . . . . . . . . 24 B.4. Changes in Httpauth WG revision 03 . . . . . . . . . . . . 24
C.4. Changes in Httpauth WG revision 01 . . . . . . . . . . . . 24 B.5. Changes in Httpauth WG revision 02 . . . . . . . . . . . . 24
C.5. Changes in Httpauth revision 00 and HttpBis revision 00 . 24 B.6. Changes in Httpauth WG revision 01 . . . . . . . . . . . . 24
C.6. Changes in revision 02 . . . . . . . . . . . . . . . . . . 24 B.7. Changes in Httpauth revision 00 and HttpBis revision 00 . 24
C.7. Changes in revision 01 . . . . . . . . . . . . . . . . . . 25 B.8. Changes in revision 02 . . . . . . . . . . . . . . . . . . 24
C.8. Changes in revision 00 . . . . . . . . . . . . . . . . . . 25 B.9. Changes in revision 01 . . . . . . . . . . . . . . . . . . 25
B.10. Changes in revision 00 . . . . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction 1. Introduction
The document proposes several extensions to the current HTTP The document proposes several extensions to the current HTTP
authentication framework, to provide enough functionality comparable authentication framework, to provide functionality comparable with
with current widely-used form-based Web authentication. A majority current widely-used form-based Web authentication. A majority of the
of the recent Web-sites on the Internet use custom application-layer recent websites on the Internet use custom application-layer
authentication implementations using Web forms. The reasons for authentication implementations using Web forms. The reasons for
these may vary, but many people believe that the current HTTP Basic these may vary, but many people believe that the current HTTP Basic
(and Digest, too) authentication method does not have enough and Digest authentication methods do not have enough functionality
functionality (including a good-feeling user interfaces) to support (including good user interfaces) to support most realistic Web-based
most of realistic Web-based applications. However, the method is applications. However, this method is very weak against phishing and
very weak against phishing and other attacks, because the whole other attacks, because all behavior of the authentication is
behavior of the authentication is controlled from the server-side controlled from the server-side application. This makes it really
applications. This makes it really hard to implement any hard to implement any cryptographically strong authentication
cryptographically strong authentication mechanisms into Web systems. mechanisms into Web systems. To overcome this problem, we need to
To overcome this problem, we need to "modernize" the HTTP "modernize" the HTTP authentication framework so that better client-
authentication framework so that better client-controlled secure controlled secure methods can be used with Web applications. The
methods can be used with Web applications. The extensions proposed extensions proposed in this document include:
in this document include:
o non-mandatory, optional authentication on HTTP (Section 3), o optional authentication on HTTP (Section 3),
o log out from both server and client side (Section 4), and o log out from both server and client side (Section 4), and
o finer control for redirection depending on authentication status o finer control for redirection depending on authentication status
(Section 4). (Section 4).
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
skipping to change at page 5, line 9 skipping to change at page 5, line 9
This document distinguishes the terms "client" and "user" in the This document distinguishes the terms "client" and "user" in the
following way: A "client" is an entity understanding and talking HTTP following way: A "client" is an entity understanding and talking HTTP
and the specified authentication protocol, usually computer software; and the specified authentication protocol, usually computer software;
a "user" is a (usually natural) person who wants to access data a "user" is a (usually natural) person who wants to access data
resources using "a client". resources using "a client".
2. Definitions 2. Definitions
2.1. Terms for describing authentication protocol flow 2.1. Terms for describing authentication protocol flow
HTTP Authentication defined in [RFC7235] may involve with several HTTP Authentication defined in [RFC7235] may involve several pairs of
pairs of HTTP requests/responses. Throughout this document, the HTTP requests/responses. Throughout this document, the following
following terms are used to categorize those messages: for requests, terms are used to categorize those messages: for requests,
o A non-authenticating request is a request not attempting any 1) A non-authenticating request is a request not attempting any
authentication: a request without any Authorization header. authentication: a request without any Authorization header.
o An authenticating request is the opposite: a request with an 2) An authenticating request is the opposite: a request with an
Authorization header. Authorization header.
For responses, For responses,
1) A non-authenticated response: is a response which does not 1) A non-authenticated response is a response which does not involve
involve with any HTTP authentication. It may not contain any any HTTP authentication. It does not contain any WWW-Authenticate
WWW-Authenticate or Authentication-Info header. or Authentication-Info header.
Servers send this response when the requested resource is not Servers send this response when the requested resource is not
protected by HTTP authentication mechanisms. In context of this protected by an HTTP authentication mechanism. In context of this
specification, not-authentication-related negative responses (e.g. specification, non-authentication-related negative responses (e.g.
403 and 404) are also considered as non-authenticated responses. 403 and 404) are also considered non-authenticated responses.
(See note on successfully-authenticated responses below for some (See note on successfully-authenticated responses below for some
ambiguous cases.) ambiguous cases.)
2) An authentication-initializing response: is a response which 2) An authentication-initializing response is a response which
requires or allows clients to start authentication attempts. requires or allows clients to start authentication attempts.
Servers send this response when the requested resource is Servers send this response when the requested resource is
protected by HTTP authentication mechanism, and the request meets protected by HTTP authentication mechanism, and the request meets
one of the following cases: one of the following cases:
* The request is non-authenticating request, or * The request is a non-authenticating request, or
* The request contained an authentication trial directed to the * The request contained an authentication trial directed to a
protection space (realm) other than the server's expected one. protection space (realm) other than the one the server
expected.
The server will specify the protection space for authentication in The server will specify the protection space for authentication in
this response. this response.
Upon reception, the client's behavior is further divided to two Upon receiving this response, the client's behavior is further
possible cases. divided to two possible cases.
* If the client may have no prior knowledge on authentication * If the client has no prior knowledge on authentication
credentials (e.g. a user-name and a password) related to the credentials (e.g. a user-name and a password) related to the
requested protection space, the protocol flow terminates and requested protection space, the protocol flow terminates and
the client will ask the user to provide authentication the client will ask the user to provide authentication
credentials, credentials,
* On the other hand, if client already have an enough credentials * On the other hand, if client already has enough authentication
for authentication to the requested protection space, the credentials to the requested protection space, the client will
client will automatically send an authenticating request. Such automatically send an authenticating request. Such cases often
cases often occur when the client did not know beforehand that occur when the client did not know beforehand that the current
the current request-URL requires an authentication. request-URL requires authentication.
3) A successfully-authenticated response: is a response for an 3) A successfully-authenticated response is a response for an
authenticating request meaning that the authentication attempt was authenticating request meaning that the authentication attempt was
granted. (Note: if the authentication scheme used does not use an granted. (Note: if the authentication scheme used does not use an
Authentication-Info header, it may be indistinguishable from a Authentication-Info header, it may be indistinguishable from a
non-authenticated response.) non-authenticated response.)
4) An intermediate authenticating response: is a response for an 4) An intermediate authenticating response is a response for an
authenticating request which requires some more reaction by the authenticating request which requires more reaction by the client
client software without involving users. Such a response is software without involving users. Such a response is required
required when an authentication scheme requires two or more round- when an authentication scheme requires two or more round-trip
trip messages to perform authentication, or when an authentication messages to perform authentication, or when an authentication
scheme uses some speculative short-cut method (such as uses of scheme uses some speculative short-cut method (such as uses of
cached shared secrets) and it failed. cached shared secrets) and it failed.
5) A negatively-authenticated response: is a response for an 5) A negatively-authenticated response is a response for an
authenticating request which means that the authentication attempt authenticating request which means that the authentication attempt
was declined and can not continue without another authentication was declined and can not continue without a different set of
credential. Clients typically erase memory of the currently-using authentication credentials. Clients typically erase memory of the
credentials and ask the user for other ones. active credentials and ask the user for other ones.
Usually the format of these responses are as same as the one for Usually the format of these responses are as same as the one for
authentication-initializing responses. Client can distinguish it authentication-initializing responses. Client can distinguish
by comparing the protection spaces contained in the request and in negatively-authenticated responses from authentication-
the response. initializing responses by comparing the protection spaces
contained in the request and in the response.
Figure 1 shows a state diagram of generic HTTP authentication with Figure 1 shows a state diagram of generic HTTP authentication with
the above message categorization. Note that many authentication the above message categorization. Note that many authentication
schemes use only a subset of the transitions described on the schemes use only a subset of the transitions described on the
diagram. Labels in the figure show the abbreviated names of response diagram. Labels in the figure show the abbreviated names of response
types. types.
=========== ----------------- =========== -----------------
NEW REQUEST ( UNAUTHENTICATED ) NEW REQUEST ( UNAUTHENTICATED )
=========== ----------------- =========== -----------------
skipping to change at page 8, line 7 skipping to change at page 8, line 7
(*2) In "Basic" and some others, this cannot be distinguished from a (*2) In "Basic" and some others, this cannot be distinguished from a
successfully-authenticated response. successfully-authenticated response.
2.2. Syntax Notation 2.2. Syntax Notation
This specification uses an extended BNF syntax defined in [RFC7230]. This specification uses an extended BNF syntax defined in [RFC7230].
The following syntax definitions are quoted from [RFC7230] and The following syntax definitions are quoted from [RFC7230] and
[RFC7235]: auth-scheme, quoted-string, auth-param, SP, BWS, header- [RFC7235]: auth-scheme, quoted-string, auth-param, SP, BWS, header-
field, and challenge. It also uses the convention of using header field, and challenge. It also uses the convention of using header
names for specifying syntax of header values. names for specifying the syntax of header values.
Additionally, this specification uses the following syntax elements Additionally, this specification uses the following syntax
following syntax definitions as a refinement for token and the right- definitions as a refinement for token and the right-hand-side of
hand-side of auth-param in [RFC7235]. (Note: these definitions are auth-param in [RFC7235]. (Note: these definitions are consistent
consistent with those in [I-D.ietf-httpauth-mutual].) with those in [I-D.ietf-httpauth-mutual].)
bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_") bare-token = 1*(%x30-39 / %x41-5A / %x61-7A / "-" / "_")
extension-token = "-" bare-token 1*("." bare-token) extension-token = "-" bare-token 1*("." bare-token)
extensive-token = bare-token / extension-token extensive-token = bare-token / extension-token
integer = "0" / (%x31-39 *%x30-39) ; no leading zeros integer = "0" / (%x31-39 *%x30-39) ; no leading zeros
Figure 2: the BNF syntax for common notations Figure 2: the BNF syntax for common notations
Extensive-tokens are used in this protocol where the set of Extensive-tokens are used in this protocol where the set of
acceptable tokens may include private extensions. Any private acceptable tokens may include private extensions. Any private
extensions of this protocol MUST use the extension-tokens with format extensions of this protocol MUST use extension-tokens with the format
"-<token>.<domain-name>", where <domain-name> is a validly registered "-<token>.<domain-name>", where <domain-name> is a valid (sub-)domain
(sub-)domain name on the Internet owned by the party who defines the name on the Internet owned by the party who defines the extension.
extensions.
3. Optional Authentication 3. Optional Authentication
The Optional-WWW-Authenticate header enables a non-mandatory The Optional-WWW-Authenticate header enables a non-mandatory
authentication, which is not possible under the current HTTP authentication, which is not possible under the current HTTP
authentication mechanism. In several Web applications, users can authentication mechanism. In several Web applications, users can
access the same contents as both a guest user and an authenticated access the same contents as both a guest user and an authenticated
user. In most Web applications, it is implemented using HTTP cookies user. In most Web applications, This functionality is implemented
[RFC6265] and custom form-based authentications. The new using HTTP cookies [RFC6265] and custom form-based authentication.
authentication method using this message will provide a replacement The new authentication method using this message will provide a
for these authentication systems. replacement for these authentication systems.
Servers MAY send HTTP successful responses (response code 200, 206 Servers MAY send HTTP non-interim responses containing the
and others) containing the Optional-WWW-Authenticate header as a Optional-WWW-Authenticate header as a replacement of a 401 response
replacement of a 401 response when it is an authentication- when it the response is authentication-initializing. The
initializing response. The Optional-WWW-Authenticate header MUST NOT Optional-WWW-Authenticate header MUST NOT sent on 401 responses (i.e.
be contained in 401 responses. a usual WWW-Authenticate header MUST be used on 401 responses.)
HTTP/1.1 200 OK HTTP/1.1 200 OK
Optional-WWW-Authenticate: Basic realm="xxxx" Optional-WWW-Authenticate: Basic realm="xxxx"
Optional-WWW-Authenticate = 1#challenge Optional-WWW-Authenticate = 1#challenge
Figure 3: BNF syntax for Optional-WWW-Authenticate header Figure 3: BNF syntax for Optional-WWW-Authenticate header
The challenges contained in the Optional-WWW-Authenticate header are The challenges contained in the Optional-WWW-Authenticate header are
the same as those for a 401 responses corresponding for a same the same as those for a 401 responses corresponding to the same
request. For authentication-related matters, an optional request. For authentication-related matters, an optional
authentication request will have the same meaning as a 401 message authentication request will have the same meaning as a 401 message
with a corresponding WWW-Authenticate header (as an authentication- with a corresponding WWW-Authenticate header (as an authentication-
initializing response). (The behavior for other matters, such as initializing response). (The behavior for other matters, such as
caching, MAY be different between the optional authentication and 401 caching, MAY be different between the optional authentication and 401
messages.) messages.)
A response with an Optional-WWW-Authenticate header SHOULD be A response with an Optional-WWW-Authenticate header SHOULD be
returned from the server only when the request is either non- returned from the server only when the request is either non-
authenticated or authenticating to a wrong (not the server's authenticated or authenticating to a wrong (not the server's
expected) protection space. If a response is either an intermediate expected) protection space. If a response is either an intermediate
or a negative response to a client's authentication attempt, the or a negative response to a client's authentication attempt, the
server MUST respond with a 401 status response with a server MUST respond with a 401 status response with a
WWW-Authenticate header instead. Failure to comply this rule will WWW-Authenticate header instead. Failure to comply with this rule
make client not able to distinguish authentication successes and will render clients unable to distinguish authentication successes
failures. and failures.
The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate The server is NOT RECOMMENDED to include an Optional-WWW-Authenticate
header in a positive response when a client's authentication attempt header in a positive response when a client's authentication attempt
succeeds. succeeds.
Whenever an authentication scheme support for servers to send some Whenever an authentication scheme supports servers sending some
parameter which gives a hint of URL space for the corresponding parameter which gives a hint of the URL space for the corresponding
protection space for the same realm (e.g. "path" or "domain"), protection space for the same realm (e.g. "path" or "domain"),
servers requesting non-mandatory authentication SHOULD send such servers requesting non-mandatory authentication SHOULD send such
parameter with the response. Clients supporting non-mandatory parameter with the response. Clients supporting non-mandatory
authentication MUST recognize the parameter, and MUST send a request authentication MUST recognize the parameter, and MUST send a request
with an appropriate authentication credential in an Authorization with an appropriate authentication credential in an Authorization
header for any URI inside the specified paths. header for any URI inside the specified paths.
Support of this header is OPTIONAL; Clients MAY also choose any set Support of this header is OPTIONAL; Clients MAY also choose any set
of authentication schemes for which optional authentication is of authentication schemes for which optional authentication is
supported (in other words, its support MAY be scheme-dependent). supported (in other words, its support MAY be scheme-dependent).
skipping to change at page 10, line 15 skipping to change at page 10, line 15
Auth-Control-Entry = auth-scheme 1*SP 1#auth-control-param Auth-Control-Entry = auth-scheme 1*SP 1#auth-control-param
auth-control-param = extensive-token BWS "=" BWS token auth-control-param = extensive-token BWS "=" BWS token
/ extensive-token "*" BWS "=" BWS ext-value / extensive-token "*" BWS "=" BWS ext-value
ext-value = <see RFC 5987, Section 3.2> ext-value = <see RFC 5987, Section 3.2>
Figure 4: the BNF syntax for the Authentication-Control header Figure 4: the BNF syntax for the Authentication-Control header
The Authentication-Control header provides a more precise control of The Authentication-Control header provides a more precise control of
the client behavior for Web applications using an HTTP authentication the client behavior for Web applications using an HTTP authentication
protocol. This header is supposed to be generated in the application protocol. This header is supposed to be generated in the application
layer, as opposed to WWW-Authenticate headers which will be generated layer, as opposed to WWW-Authenticate headers which will usually be
usually by the Web servers. generated by the Web servers.
Support of this header is OPTIONAL, and clients MAY choose any subset Support of this header is OPTIONAL, and clients MAY choose any subset
of these parameters to be supported. The set of supported parameters of these parameters to be supported. The set of supported parameters
MAY also be authentication scheme-dependent. However, some MAY also be authentication scheme-dependent. However, some
authentication schemes MAY require mandatory/recommended support for authentication schemes MAY require mandatory/recommended support for
some or all of the features provided in this header. some or all of the features provided in this header.
The Authentication-Control header contains one or more The Authentication-Control header contains one or more
"authentication control entries" each of which corresponds to a "authentication control entries" each of which corresponds to a
single realm for a specific authentication scheme. If the single realm for a specific authentication scheme. If the
skipping to change at page 10, line 38 skipping to change at page 10, line 38
that entry MUST contain the "realm" parameter. If not, the entry that entry MUST contain the "realm" parameter. If not, the entry
MUST NOT contain the "realm" parameter. MUST NOT contain the "realm" parameter.
Among the multiple entries in the header, the meaningful entries in Among the multiple entries in the header, the meaningful entries in
the header are those corresponding to an auth-scheme and a realm (if the header are those corresponding to an auth-scheme and a realm (if
any), for which "the authentication process is being performed, or any), for which "the authentication process is being performed, or
going to be performed". In more detail, going to be performed". In more detail,
(1) If the response is either an authentication-initializing (1) If the response is either an authentication-initializing
response or a negatively-authenticated response, there may be response or a negatively-authenticated response, there may be
multiple challenges in the WWW-Authenticate (or Optional-WWW- multiple challenges in the WWW-Authenticate header (or the
Authenticate defined in this extension) header, each of which Optional-WWW-Authenticate header defined in this extension),
corresponds to a different scheme and realm. The client will each of which corresponds to a different scheme and realm. In
determine the scheme and realm to perform an authentication, and this case, the client has a choice on the scheme and realm they
the entries corresponding to the chosen scheme and realm will be will use to authenticate. Only the entry in the
meaningful. &Authentication-Control; header corresponding to that scheme and
realm are meaningful.
(2) If the response is either an intermediate authenticating (2) If the response is either an intermediate authenticating
response or a successfully-authenticated response, the scheme response or a successfully-authenticated response, the scheme
and a realm given in the Authorization header of the HTTP and realm given in the Authorization header of the HTTP request
request will determine the currently-ongoing authentication will determine the currently-ongoing authentication process.
process. Only the entries correspond to that scheme and realm Only the entry corresponding to that scheme and realm are
are meaningful. meaningful.
The server MAY send an Authentication-Control header containing non- The server MAY send an Authentication-Control header containing non-
meaningful entries. The client MUST ignore all non-meaningful meaningful entries. The client MUST ignore all non-meaningful
entries it received. entries it received.
Each entry contains one or more parameters, each of which is a name- Each entry contains one or more parameters, each of which is a name-
value pair. The name of each parameter MUST be an extensive-token. value pair. The name of each parameter MUST be an extensive-token.
Clients MUST ignore any unknown parameters contained in this header. Clients MUST ignore any unknown parameters contained in this header.
The entries for the same auth-scheme and the realm MUST NOT contain The entries for the same auth-scheme and the realm MUST NOT contain
the duplicated parameters for the same name. duplicated parameters for the same name.
The type of parameter value depends on the parameter name as defined The type of parameter value depends on the parameter name as defined
in the following subsections. Regardless of the type, however, the in the following subsections. Regardless of the type, however, the
recipients SHOULD accept both quoted and unquoted representations of recipients SHOULD accept both quoted and unquoted representations of
values as defined in HTTP. If the parameter is defined to have a values as defined in HTTP. If the parameter is defined to have a
string value, is is encouraged t be sent either in a quoted form or string value, implementations SHOULD send the parameter in a quoted
an ext-value form (see Section 4.1). If it is defined as a token (or form or an ext-value form (see Section 4.1). If the parameter is
similar) or an integer, the value SHOULD follow the corresponding defined as a token (or similar) or an integer, the value SHOULD
ABNF syntax after possible unquoting of the quoted-string value (as follow the corresponding ABNF syntax after possible unquoting of the
defined in HTTP), and is encouraged to be sent in a unquoted form. quoted-string value (as defined in HTTP), and SHOULD be sent in a
unquoted form.
Server-side application SHOULD always be reminded that any parameters Server-side applications SHOULD be aware that any parameters
contained in this header MAY be ignored by clients. Also, even when contained in this header MAY be ignored by clients. Also, even when
a client accepts this header, users may always be able to circumvent a client accepts this header, users may always be able to circumvent
semantics of this header. Therefore, if this header is used for the semantics of this header. Therefore, if this header is used for
security purposes, its use MUST be limited for providing some non- security purposes, its use MUST be limited to providing some non-
fundamental additional security measures valuable for end-users (such fundamental additional security measures valuable for end-users (such
as client-side log-out for protecting against console takeover). as client-side log-out for protecting against console takeover).
Server-side application MUST NOT rely on the use of this header for Server-side applications MUST NOT rely on the use of this header for
protecting server-side resources. protecting server-side resources.
Note: The header syntax allows servers to specify Authentication- Note: The header syntax allows servers to specify Authentication-
Control for multiple authentication schemes, either as multiple Control for multiple authentication schemes, either as multiple
occurrences of this header or as a combined single header (see occurrences of this header or as a combined single header (see
Section 3.2.2 of [RFC7230] for rationale). The same care as for Section 3.2.2 of [RFC7230] for rationale). The same care as for
parsing multiple authentication challenges SHALL be taken. parsing multiple authentication challenges SHALL be taken.
4.1. Non-ASCII extended header parameters 4.1. Non-ASCII extended header parameters
Parameters contained in the Authentication-Control header MAY be Parameters contained in the Authentication-Control header MAY be
extended to ISO 10646-1 values using the framework described in extended to ISO 10646-1 values using the framework described in
[RFC5987]. All servers and clients MUST be capable of receiving and [RFC5987]. All servers and clients MUST be capable of receiving and
sending values encoded in [RFC5987] syntax. sending values encoded in [RFC5987] syntax.
If a value to be sent contains only ASCII characters, the field MUST If a value to be sent contains only ASCII characters, the field MUST
be sent in clear using plain RFC 7235 syntax. The syntax extended by be sent using plain RFC 7235 syntax. The syntax as extended by RFC
RFC 5987 MUST NOT be used in this case. 5987 MUST NOT be used in this case.
If a value (except the "realm" header) contains one or more non-ASCII If a value (except the "realm" header) contains one or more non-ASCII
characters, the parameter SHOULD be sent using the ext-value syntax characters, the parameter SHOULD be sent using the ext-value syntax
defined in Section 3.2 of [RFC5987]. Such parameter MUST have defined in Section 3.2 of [RFC5987]. Such a parameter MUST have a
charset value of "UTF-8", and the language value MUST always be charset value of "UTF-8", and the language value MUST always be
omitted (have an empty value). The same parameter MUST NOT be sent omitted (have an empty value). The same parameter MUST NOT be sent
twice or more, those in both plain- and extended-syntax. more than once, regardless of the used syntax.
For example, a parameter "username" with value "Renee or France" For example, a parameter "username" with value "Renee of France"
SHOULD be sent as < username="Renee of France" >. If the value is SHOULD be sent as < username="Renee of France" >. If the value is
"Ren<e acute>e of France", it SHOULD be sent as < username*=UTF- "Ren<e acute>e of France", it SHOULD be sent as < username*=UTF-
8''Ren%C3%89e%20of%20France > instead. 8''Ren%C3%89e%20of%20France > instead.
4.2. Auth-style parameter 4.2. Auth-style parameter
Authentication-Control: Digest realm="protected space", Authentication-Control: Digest realm="protected space",
auth-style=modal auth-style=modal
The parameter "auth-style" specifies the server's preferences over The parameter "auth-style" specifies the server's preferences for
user interface behavior for user authentication. This parameter can user interface behavior for user authentication. This parameter can
be included in any kind of responses, however, it is only meaningful be included in any kind of response, however, it is only meaningful
for either authentication-initializing or negatively-authenticated for either authentication-initializing or negatively-authenticated
responses. The value of this parameter MUST be one of the bare- responses. The value of this parameter MUST be one of the bare-
tokens "modal" or "non-modal". When the Optional-WWW-Authenticate tokens "modal" or "non-modal". When the Optional-WWW-Authenticate
header is used, the value of this parameter MUST be disregarded and header is used, the value of this parameter MUST be disregarded and
the value "non-modal" is implied. the value "non-modal" is implied.
The value "modal" means that the server thinks the content of the The value "modal" means that the server thinks the content of the
response (body and other content-related headers) is valuable only response (body and other content-related headers) is valuable only
for users refusing authentication request. The clients are expected for users refusing the authentication request. The clients are
to ask the user a password before processing the content. This expected to ask the user for a password before processing the
behavior is common for most of the current implementations of Basic content. This behavior is common for most of the current
and Digest authentication schemes. implementations of Basic and Digest authentication schemes.
The value "non-modal" means that the server thinks the content of the The value "non-modal" means that the server thinks the content of the
response (body and other content-related headers) is valuable for response (body and other content-related headers) is valuable for
users before processing an authentication request. The clients are users before processing an authentication request. The clients are
expected to first process the content and then provide users expected to first process the content and then provide users the
opportunities to perform authentication. opportunity to perform authentication.
The default behavior for the clients is implementation-dependent, and The default behavior for clients is implementation-dependent, and
clients MAY choose different defaults for different authentication clients MAY choose different defaults for different authentication
schemes. The proposed default behavior is "modal" for all schemes. The proposed default behavior is "modal" for all
authentication schemes, but specifications for authentication schemes authentication schemes, but specifications for authentication schemes
MAY propose a different default. MAY propose a different default.
The above two different methods of authentication may introduce a The above two different methods of authentication may introduce a
observable difference of semantics when the response contains state- observable difference of semantics when the response contains state-
changing side effects; for example, it may change whether Cookie changing side effects; for example, it may change whether Cookie
headers [RFC6265] in 401 responses are processed or not. However, headers [RFC6265] in 401 responses are processed or not. However,
the server applications SHOULD NOT depend on both existence and non- the server applications SHOULD NOT depend on both existence and non-
skipping to change at page 13, line 21 skipping to change at page 13, line 22
The parameter "location-when-unauthenticated" specifies a location The parameter "location-when-unauthenticated" specifies a location
where any unauthenticated clients should be redirected to. This where any unauthenticated clients should be redirected to. This
header may be used, for example, when there is a central login page header may be used, for example, when there is a central login page
for the entire Web application. The value of this parameter is a for the entire Web application. The value of this parameter is a
string that contains an absolute URL location. Senders MUST always string that contains an absolute URL location. Senders MUST always
send an absolute URL location. If a received URL is not absolute, send an absolute URL location. If a received URL is not absolute,
the clients SHOULD either ignore it or consider it a relative URL the clients SHOULD either ignore it or consider it a relative URL
from the current location. from the current location.
This parameter MAY be used with a 401 response for authentication- This parameter MAY be used with a 401 response for an authentication-
initializing response. It can also be contained, although initializing response. It can also be contained, although this is
NOT RECOMMENDED, in a positive response with an NOT RECOMMENDED, in a positive response with an
Optional-WWW-Authenticate header. The clients MUST ignore this Optional-WWW-Authenticate header. The clients MUST ignore this
parameter, when a response is either successfully-authenticated or parameter when a response is either successfully-authenticated or
intermediately-authenticated. The clients SHOULD ignore this intermediately-authenticated. The clients SHOULD ignore this
parameter when a response is a negatively-authenticated one (the case parameter when a response is a negatively-authenticated one (the case
is unlikely to happen, though). is unlikely to happen, though).
When a client receives an authentication-initiating response with When a client receives an authentication-initiating response with
this parameter, if the client has to ask users for authentication this parameter, if the client has to ask users for authentication
credentials, the client will treat the entire response as if it were credentials, the client will treat the entire response as if it were
a 303 "See Other" response with a Location header that contains the a 303 "See Other" response with a Location header that contains the
value of this parameter (i.e., client will be redirected to the value of this parameter (i.e., client will be redirected to the
specified location with a GET request). Unlike a normal 303 specified location with a GET request). Unlike a normal 303
response, if the client can process authentication without the user's response, if the client can process authentication without the user's
interaction, this parameter MUST be ignored. interaction, this parameter MUST be ignored.
4.4. No-auth parameter 4.4. No-auth parameter
Authentication-Control: Basic realm="entrance", no-auth=true Authentication-Control: Basic realm="entrance", no-auth=true
The parameter "no-auth" is a variant of the The parameter "no-auth" is a variant of the
location-when-unauthenticated parameter; it specifies that new location-when-unauthenticated parameter; it specifies that new
authentication attempt is not to be performed on this location for authentication attempts are not to be performed on this location in
better user experience, without specifying the redirection on the order to improve the user experience, without specifying the
HTTP level. This header may be used, for example, when there is a redirection on the HTTP level. This header may be used, for example,
central login page for the entire Web application, and when a (Web when there is a central login page for the entire Web application,
content's level) explicit interaction of users is desired before and when an explicit user interaction with the Web content is desired
authentications. The value of this parameter MUST be a token "true". before authentications. The value of this parameter MUST be a token
If the value is incorrect, client MAY ignore this parameter. "true". If the value is incorrect, client MAY ignore this parameter.
This parameter MAY be used with authentication-initiating responses. This parameter MAY be used with authentication-initiating responses.
It can also be contained, although NOT RECOMMENDED, in a positive It can also be contained, although this is NOT RECOMMENDED, in a
response with an Optional-WWW-Authenticate header. The clients MUST positive response with an Optional-WWW-Authenticate header. The
ignore this parameter, when a response is either successfully- clients MUST ignore this parameter when a response is either
authenticated or intermediately-authenticated. The clients SHOULD successfully-authenticated or intermediately-authenticated. The
ignore this parameter when a response is a negatively-authenticated clients SHOULD ignore this parameter when a response is a negatively-
one (the case is unlikely to happen, though). authenticated one (the case is unlikely to happen, though).
When a client receives an authentication-initiating response with When a client receives an authentication-initiating response with
this parameter, if the client has to ask users for authentication this parameter, if the client has to ask users for authentication
credentials, the client will ignore the WWW-Authenticate header credentials, the client will ignore the WWW-Authenticate header
contained in the response and treat the whole response as a normal contained in the response and treat the whole response as a normal
negative 4xx-class response instead of giving user an opportunity to negative 4xx-class response instead of giving the user an opportunity
start authentication. If the client can process authentication to start authentication. If the client can process authentication
without the user's interaction, this parameter MUST ignored. without the user's interaction, this parameter MUST be ignored.
This parameter SHOULD NOT be used along with the This parameter SHOULD NOT be used along with the
location-when-unauthenticated parameter. If both were supplied, location-when-unauthenticated parameter. If both were supplied,
clients MAY choose which one is to be honored. clients MAY choose which one is to be honored.
This parameter SHOULD NOT be used as any security measures to prevent This parameter SHOULD NOT be used as a security measure to prevent
authentication attempts, as it is easily circumvented by users. This authentication attempts, as it is easily circumvented by users. This
parameter SHOULD be used solely for improving user experience of web parameter SHOULD be used solely for improving user experience of Web
applications. applications.
4.5. Location-when-logout parameter 4.5. Location-when-logout parameter
Authentication-Control: Digest realm="protected space", Authentication-Control: Digest realm="protected space",
location-when-logout="http://www.example.com/byebye.html" location-when-logout="http://www.example.com/byebye.html"
The parameter "location-when-logout" specifies a location where the The parameter "location-when-logout" specifies a location where the
client is to be redirected when the user explicitly request a logout. client is to be redirected when the user explicitly requests a
The value of this parameter MUST be a string that contains an logout. The value of this parameter MUST be a string that contains
absolute URL location. If a given URL is not absolute, the clients an absolute URL location. If a given URL is not absolute, the
MAY consider it a relative URL from the current location. clients MAY consider it a relative URL from the current location.
This parameter MAY be used with successfully-authenticated responses. This parameter MAY be used with successfully-authenticated responses.
If this parameter is contained in other kinds of responses, the If this parameter is contained in other kinds of responses, the
clients MUST ignore this parameter. clients MUST ignore this parameter.
When the user requests to terminate an authentication period, and if When the user requests termination of an authentication period, and
the client currently displays a page supplied by a response with this if the client currently displays a page supplied by a response with
parameter, the client will be redirected to the specified location by this parameter, the client will be redirected to the specified
a new GET request (as if it received a 303 response). The log-out location by a new GET request (as if it received a 303 response).
operation (e.g. erasing memories of user name, authentication The log-out operation (e.g. erasing memories of user name,
credential and all related one-time credentials such as nonce or authentication credential and all related one-time credentials such
keys) SHOULD occur before processing a redirection. as nonce or keys) SHOULD occur before processing a redirection.
When the user requests to terminate an authentication period, if the When the user requests termination of an authentication period, if
client supports this parameter but the server response does not the client supports this parameter but the server response does not
contain this parameter, the client's RECOMMENDED behavior is as contain this parameter, the client's RECOMMENDED behavior is as
follows: if the request corresponding to the current content was safe follows: if the request corresponding to the current content was safe
(e.g. GET), reload the page without the authentication credential. (e.g. GET), reload the page without the authentication credential.
If the request was non-idempotent (e.g. POST), keep the current If the request was non-idempotent (e.g. POST), keep the current
content as-is and simply forget the authentication status. The content as-is and simply forget the authentication status. The
client SHOULD NOT replay a non-idempotent request without the user's client SHOULD NOT replay a non-idempotent request without the user's
explicit approval. explicit approval.
Web applications are encouraged to send this parameter with an Web applications are encouraged to send this parameter with an
appropriate value for any responses (except those with redirection appropriate value for any responses (except those with redirection
(3XX) statuses) for non-GET requests. (3XX) statuses) for non-GET requests.
4.6. Logout-timeout parameter 4.6. Logout-timeout parameter
Authentication-Control: Basic realm="entrance", logout-timeout=300 Authentication-Control: Basic realm="entrance", logout-timeout=300
The parameter "logout-timeout", when contained in a successfully- The parameter "logout-timeout", when contained in a successfully-
authenticated response, means that any authentication credentials and authenticated response, means that any authentication credentials and
states related to the current protection space are to be discarded if state related to the current protection space are to be discarded if
a time specified in this header (in seconds) has been passed from the a time specified in this header (in seconds) has passed since from
time received. The value MUST be an integer. As a special case, the the time this header was received. The value MUST be an integer. As
value 0 means that the client is requested to immediately log-out a special case, the value 0 means that the client is requested to
from the current authentication space and revert to an immediately log-out from the current authentication space and revert
unauthenticated status. This does not, however, mean that the long- to an unauthenticated status. This does not, however, mean that the
term memories for the passwords (such as the password reminders and long-term memories for the passwords and passwords-related details
auto fill-ins) should be removed. If a new timeout value is received (such as the password reminders and auto fill-ins) should be removed.
for the same authentication space, it cancels the previous timeout If a new timeout value is received for the same authentication space,
and sets a new timeout. it cancels the previous timeout and sets a new timeout.
4.7. Username parameter 4.7. Username parameter
Authentication-Control: Basic realm="configuration", username="admin" Authentication-Control: Basic realm="configuration", username="admin"
The parameter "username" tells that the only "user name" to be The parameter "username" tells that the only "user name" to be
accepted by the server is the value given in this parameter. This accepted by the server is the value given in this parameter. This
parameter is particularly useful, for example, for routers and other parameter is particularly useful, for example, for routers and other
appliances with a Web configuration interface. appliances with a Web configuration interface.
This parameter MAY be used with authentication-initiating responses This parameter MAY be used with authentication-initiating responses
or negatively-authenticated responses requiring another attempt of or negatively-authenticated responses requiring another attempt of
authentication. The clients MUST ignore this parameter, when a authentication. The clients MUST ignore this parameter when a
response is either successfully-authenticated or intermediately- response is either successfully-authenticated or intermediately-
authenticated. authenticated.
If the authentication scheme to be used has syntax limitation on the If the authentication scheme to be used has a syntax limitation on
allowed user names (e.g. Basic and Digest do not allow colons in the allowed user names (e.g. Basic and Digest do not allow colons in
user names), the specified value MUST follow that limitation. Client user names), the specified value MUST follow that limitation.
SHOULD ignore any values which do not conform to such limitations. Clients SHOULD ignore any values which do not conform to such
limitations.
Clients MAY still send any authentication requests with other user Clients MAY still send any authentication requests with other user
names, possibly in vain. Servers are not strictly required to reject names, possibly in vain. Servers are not strictly required to reject
user names other than specified, but doing it will give bad user user names other than specified, but doing so will give bad user
experiences and may confuse users and clients. experiences and may confuse users and clients.
If the used authentication scheme requires specific style of text If the used authentication scheme requires a specific style of text
preparation for the user name (e.g., PRECIS string preparation or preparation for the user name (e.g., PRECIS string preparation or
Unicode normalization), the specified user name SHOULD follow such Unicode normalization), the specified user name SHOULD follow such
requirements. requirements.
5. Usage examples (informative) 5. Usage examples (informative)
This section shows some examples for applying this extension to This section shows some examples for applying this extension to
typical Web-sites which are using Forms and cookies for managing typical websites which are using Forms and cookies for managing
authentication and authorization. The content of this section is not authentication and authorization. The content of this section is not
normative and for illustrative purposes only. normative and for illustrative purposes only.
We assume that all features described in the previous sections are We assume that all features described in the previous sections are
implemented in clients (Web browsers). We also assume that browsers implemented in clients (Web browsers). We also assume that browsers
will have a user interface which allows users to deactivate (log-out will have a user interface which allows users to deactivate (log-out
from) current authentication sessions. If this assumption is not from) current authentication sessions. If this assumption is not
hold, texts below provides another approach with de-authentication value, the text below provides another approach with de-
pages used instead of such a UI. authentication pages used instead of such a UI.
Without explicit notices, all settings described below are to be When not explicitly specified, all settings described below are to be
applied with Authentication-Control headers, and these can be sent to applied with Authentication-Control headers, and these can be sent to
clients regardless of authentication statuses (these will be silently clients regardless of the authentication status (these will be
ignored whenever not effective). silently ignored whenever not effective).
5.1. Example 1: a portal site 5.1. Example 1: a portal site
This subsection provides an example application for a site whose This subsection provides an example application for a site whose
structure is somewhat similar to conventional portal sites. In structure is somewhat similar to conventional portal sites. In
particular, most of web pages are available for guest particular, most web pages are available for guest (unauthenticated)
(unauthenticated) users, and if authentication is performed, contents users, and if authentication is performed, the content of these pages
of these pages are customized for each user. We assume the site has is customized for each user. We assume the site has the following
the following kinds of pages currently: kinds of pages currently:
o Content pages. o Content pages.
o Pages/mechanism for performing authentication: o Pages/mechanism for performing authentication:
* There is one page which asks a user name and a password using a * There is one page which asks a user name and a password using a
HTML POST form. HTML POST form.
* After the authentication attempt, the user will be redirected * After the authentication attempt, the user will be redirected
to either the page which is previously displayed before the to either the page which is previously displayed before the
authentication, or some specific page. authentication, or some specific page.
o A de-authentication (log-out) page. o A de-authentication (log-out) page.
5.1.1. Case 1: a simple application 5.1.1. Case 1: a simple application
When such a site does not need a specific actions upon log-in and When such a site does not require specific actions upon log-in and
log-out, the following simple settings can be used. log-out, the following simple settings can be used.
o Set up an optional authentication to all pages available to o Set up an optional authentication to all pages available to
guests. Set up an Authentication-Control header with "auth- guests. Set up an Authentication-Control header with "auth-
style=non-modal" setting. style=non-modal" setting.
o If there are pages only available to authenticated users, Set up a o If there are pages only available to authenticated users, set up a
mandatory authentication with "auth-style=non-modal" setting. mandatory authentication with "auth-style=non-modal" setting.
o No specific pages for authentication is needed. It will be o No specific pages for authentication are needed. It will be
performed automatically, directed by the above setting. performed automatically, directed by the above setting.
o A de-authentication page is also not needed. If the site will o A de-authentication page is also not needed. If the site has one,
have one, put "logout-timeout=0" there. put "logout-timeout=0" there.
o For all pages for POST requests, it is advisable to have o For all pages for POST requests, it is advisable to have
"location-when-logout=<some page>". "location-when-logout=<some page>".
5.1.2. Case 2: specific action required on log-out 5.1.2. Case 2: specific action required on log-out
If the site needs a specific actions upon log-out, the following If the site requires specific actions upon log-out, the following
settings can be used. settings can be used.
o All shown in the Case 1 are to be applied. o All settings in the Case 1 are applied.
o For all pages, set up the Authentication-Control header "location- o For all pages, set up the Authentication-Control header "location-
when-logout=<de-authentication page>". when-logout=<de-authentication page>".
o In de-authentication pages, no specific set-up is needed. If o In the de-authentication page, no specific set-up is needed. If
there is any direct links to it, put "logout-timeout=0". there are any direct links to the de-authentication page, put
"logout-timeout=0".
5.1.3. Case 3: specific page displayed before log-in 5.1.3. Case 3: specific page displayed before log-in
If the site needs to display a specific page before log-in actions If the site needs to display a specific page before log-in actions
(some announces, user notices, or even advertisements), the following (some announcements, user notices, or even advertisements), the
settings can be applied. following settings can be applied.
o Set up an optional authentication to all pages available to guest. o Set up an optional authentication to all pages available to
Set up an Authentication-Control header with "no-auth=true". Put guests. Set up an Authentication-Control header with "no-
a link to a specific log-in page in contents. auth=true". Put a link to a specific log-in page in contents.
o If there are pages only available to authenticated users, Set up a o If there are pages only available to authenticated users, set up a
mandatory authentication with "location-when-unauthenticated=<the mandatory authentication with "location-when-unauthenticated=<the
log-in page>". log-in page>".
o For the specific log-in page, Set up a mandatory authentication. o For the specific log-in page, set up a mandatory authentication.
o For all pages for POST requests, it is advisable to have o For all pages for POST requests, it is advisable to have
"location-when-logout=<some page>", too. "location-when-logout=<some page>", too.
o De-authentication pages are not needed. If the site will have o De-authentication pages are not needed. If the site has one, put
one, put "logout-timeout=0". "logout-timeout=0".
5.2. Example 2: authenticated user-only sites 5.2. Example 2: authenticated user-only sites
If almost all pages in the target site requires authentication (e.g., If almost all pages in the target site require authentication (e.g.,
an Internet banking site), or there are no needs to support both an Internet banking site), or if there are no needs to support both
unauthenticated and authenticated users on the same resource, the unauthenticated and authenticated users on the same resource, the
setting will become somewhat simple. The following are an example to settings will become simpler. The following are an example for such
realize such a site: a site:
o Set up a mandatory authentication to all pages available to o Set up a mandatory authentication to all pages available to
authenticated. Set up an Authentication-Control header with authenticated users. Set up an Authentication-Control header with
"auth-style=non-modal" setting. "auth-style=non-modal" setting.
o Set up a handler for the 401-status which requests users to o Set up a handler for the 401-status which requests users to
authenticate. authenticate.
o For all pages for POST requests, it is advisable to have o For all pages for POST requests, it is advisable to have
"location-when-logout=<some page>", too. "location-when-logout=<some page>", too.
o De-authentication pages are not needed. If the site will have o De-authentication pages are not needed. If the site will have
one, put "logout-timeout=0" there. one, put "logout-timeout=0" there.
5.3. When to use Cookies 5.3. When to use Cookies
In the current Web sites using Form-based authentications, Cookies In the current Web sites using form-based authentications, Cookies
[RFC6265] are used for managing both authorization and application [RFC6265] are used for managing both authorization and application
sessions. Using the extensions in this document, the former features sessions. Using the extensions in this document, the former features
will be provided by using (extended) HTTP authentication/ will be provided by using (extended) HTTP authentication/
authorization mechanisms. In some cases, there will be some authorization mechanisms. In some cases, there will be ambiguity on
ambiguous situations whether some functions are authorization whether some functions are for authorization management or for
management or session management. The following hints will be session management. The following hints will be helpful for deciding
helpful for deciding which features to be used. which features to use.
o If there is a need to serve multiple sessions for a single user o If there is a need to serve multiple sessions for a single user
using multiple browsers concurrently, use a Cookie for using multiple browsers concurrently, use a Cookie for
distinguishing between sessions for the same user. (C.f. if there distinguishing between sessions for the same user. (C.f. if there
is a need to distinguish sessions in the same browser, HTML5 Web is a need to distinguish sessions in the same browser, HTML5 Web
Storage [W3C.REC-webstorage-20130730] features may be used instead Storage [W3C.REC-webstorage-20130730] features may be used instead
of Cookies.) of Cookies.)
o If a web site is currently deploying a session time-out feature, o If a web site is currently deploying a session time-out feature,
consider who benefits from the feature. In most cases, the main consider who benefits from the feature. In most cases, the main
requirement for such feature is to protect users from their requirement for such a feature is to protect users from having
consoles and browsers hijacked (i.e. benefits are on the users' their consoles and browsers hijacked (i.e. benefits are on the
side). In such cases, the time-out features provided in this users' side). In such cases, the time-out features provided in
extension may be used. On the other hand, the requirements is to this extension may be used. On the other hand, the requirement is
protect server's privilege (e.g. when some regulations require to to protect server's privilege (e.g. when some regulations require
limit the time difference between user's two-factor authentication to limit the time difference between user's two-factor
and financial transaction commitment; the requirement is strictly authentication and financial transaction commitment; the
on the servers' side), that should be managed on the server side requirement is strictly on the servers' side), that should be
using Cookies or other session management mechanisms. managed on the server side using Cookies or other session
management mechanisms.
5.4. Parallel deployment with Form/Cookie authentications 5.4. Parallel deployment with Form/Cookie authentications
In some transition periods, sites may need to support both HTTP-layer In some transition periods, sites may need to support both HTTP-layer
and Form-based authentications. The following example shows one way and form-based authentication. The following example shows one way
to achieve that. to achieve that.
o If Cookies are used even for HTTP-authenticated users, each o If Cookies are used even for HTTP-authenticated users, each
session determined by Cookies should identify which authentication session determined by Cookies should identify which authentication
are used for the session. has been used for the session.
o First, set up any of the above settings for enabling HTTP-layer o First, set up any of the above settings for enabling HTTP-layer
authentication. authentication.
o For unauthenticated users, put the following things to the Web o For unauthenticated users, add the following things to the Web
pages, unless the client supports this extension and HTTP-level pages, unless the client supports this extension and HTTP-level
authentication. authentication.
* For non-mandatory authenticated pages, put a link to Form-based * For non-mandatory authenticated pages, put a link to Form-based
authenticated pages. authenticated pages.
* For mandatory authenticated pages, either put a link to Form- * For mandatory authenticated pages, either put a link to Form-
based authenticated pages, or put a HTML-level redirection based authenticated pages, or put a HTML-level redirection
(using META element) to such pages. (using META element) to such pages.
o In Form-based authenticated pages, if users are not authenticated, o In Form-based authenticated pages, if users are not authenticated,
it may have a diversion for HTTP-level authentication by the page may have a diversion for HTTP-level authentication by
"location-when-unauthenticated" setting. "location-when-unauthenticated" setting.
o Users are identified for authorizations and content customization o Users are identified to authorization and content customization by
by the following logic. the following logic.
* First, check the result of the HTTP-level authentication. If * First, check the result of the HTTP-level authentication. If
there is a Cookie session tied to a specific user, both ones there is a Cookie session tied to a specific user, both should
should match. match.
* If the user is not authenticated on the HTTP-level, use the * If the user is not authenticated on the HTTP-level, use the
conventional Form-based method to determine the user. conventional Form-based method to determine the user.
* If there is a Cookie tied to an HTTP authentication, but there * If there is a Cookie tied to HTTP authentication, but there is
is no corresponding HTTP authentication result, that session no corresponding HTTP authentication result, that session will
will be discarded (because it means that authentication is be discarded (because it means that authentication is
deactivated by the corresponding user). deactivated by the corresponding user).
6. Methods to extend this protocol 6. Methods to extend this protocol
If a private extension to this protocol is implemented, it MUST use If a private extension to this protocol is implemented, it MUST use
the extension-param to avoid conflicts with this protocol and other the extension-param to avoid conflicts with this protocol and other
future official extensions. future official extensions.
When bare-tokens are used in this protocol, these MUST be allocated When bare-tokens are used in this protocol, these MUST be allocated
by IANA. Any tokens used for non-private, non-experimental by IANA. Any tokens used for non-private, non-experimental
parameters are RECOMMENDED to be registered to IANA, regardless of parameters are RECOMMENDED to be registered to IANA, regardless of
the kind of tokens used. the kind of tokens used.
Extension-tokens MAY be freely used for any non-standard, private, Extension-tokens MAY be freely used for any non-standard, private,
and/or experimental uses. The extension-tokens MUST be with format and/or experimental uses. An extension-tokens MUST use the format
"-<bare-token>.<domain-name>", where <domain-name> is a validly "-<bare-token>.<domain-name>", where <domain-name> is a validly
registered (sub-)domain name on the Internet owned by the party who registered (sub-)domain name on the Internet owned by the party who
defines the extensions. Unknown parameter names are to be ignored defines the extensions. Unknown parameter names are to be ignored
regardless of whether it is extension-tokens or bare-tokens. regardless of whether it is extension-tokens or bare-tokens.
7. IANA Considerations 7. IANA Considerations
This document defines two new entries for the "Permanent Message This document defines two new entries for the "Permanent Message
Header Field Names" registry. Header Field Names" registry.
skipping to change at page 21, line 38 skipping to change at page 21, line 47
| no-auth | Section 4.4 of this document | | no-auth | Section 4.4 of this document |
| location-when-logout | Section 4.5 of this document | | location-when-logout | Section 4.5 of this document |
| logout-timeout | Section 4.6 of this document | | logout-timeout | Section 4.6 of this document |
| username | Section 4.7 of this document | | username | Section 4.7 of this document |
+-------------------------------+------------------------------+ +-------------------------------+------------------------------+
8. Security Considerations 8. Security Considerations
The purpose of the log-out timeout feature in the Authentication- The purpose of the log-out timeout feature in the Authentication-
control header is to protect users of clients from impersonation control header is to protect users of clients from impersonation
caused by an attacker having access to the same console. Server caused by an attacker having access to the same console. The server
application implementer SHOULD be aware that the directive may always application implementer SHOULD be aware that the directive may always
be ignored by either malicious clients or clients not supporting this be ignored by either malicious clients or clients not supporting this
extension. If the purpose of introducing a timeout for an extension. If the purpose of introducing a timeout for an
authentication period is to protect server-side resources, such authentication period is to protect server-side resources, this
features MUST be implemented by other means such as HTTP Cookies protection MUST be implemented by other means such as HTTP Cookies
[RFC6265]. [RFC6265].
All parameters in Authentication-Control header SHOULD NOT be used All parameters in Authentication-Control header SHOULD NOT be used
for any security-enforcement purposes. Server-side applications MUST for any security-enforcement purposes. Server-side applications MUST
be implemented always considering that the header may be either always consider that the header may be either ignored by clients or
ignored by clients or even bypassed by users. even bypassed by users.
The "username" parameter may reveal sensitive information about the The "username" parameter may reveal sensitive information about the
HTTP server and its configurations, useful for security attacks. The HTTP server and its configurations, useful for security attacks. The
use of the "username" parameter SHOULD be limited to cases where the use of the "username" parameter SHOULD be limited to cases where the
all of the following conditions are met: all of the following conditions are met:
(1) the valid user name is pre-configured and not modifiable (such (1) the valid user name is pre-configured and not modifiable (such
as root, admin or similar ones); as root, admin or similar ones);
(2) the valid user name for such an appliance is publicly known (for (2) the valid user name for such an appliance is publicly known (for
example, written in a manual); and example, written in a manual); and
(3) either the valid user name for the server is easily guessable by (3) either the valid user name for the server is easily guessable by
other means (for example, from the model number shown in an other means (for example, from the model number shown in an
unauthenticated page), or the server is only accessible from unauthenticated page), or the server is only accessible from
limited networks. limited networks.
Especially, it SHOULD NOT be used in any case when the valid user Most importantly, the "username" parameter SHOULD NOT be used in any
names are configured by its users or administrators. case when the valid user names are configured by users or
administrators.
9. References 9. References
9.1. Normative References 9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997, RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 23, line 10 skipping to change at page 23, line 20
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Authentication", RFC 7235, Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014, DOI 10.17487/RFC7235, June 2014,
<http://www.rfc-editor.org/info/rfc7235>. <http://www.rfc-editor.org/info/rfc7235>.
9.2. Informative References 9.2. Informative References
[I-D.ietf-httpauth-mutual] [I-D.ietf-httpauth-mutual]
Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi,
T., and Y. Ioku, "Mutual Authentication Protocol for T., and Y. Ioku, "Mutual Authentication Protocol for
HTTP", draft-ietf-httpauth-mutual-06 (work in progress), HTTP", draft-ietf-httpauth-mutual-07 (work in progress),
January 2016. January 2016.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011, DOI 10.17487/RFC6265, April 2011,
<http://www.rfc-editor.org/info/rfc6265>. <http://www.rfc-editor.org/info/rfc6265>.
[W3C.REC-webstorage-20130730] [W3C.REC-webstorage-20130730]
Hickson, I., "Web Storage", World Wide Web Consortium Hickson, I., "Web Storage", World Wide Web Consortium
Recommendation REC-webstorage-20130730, July 2013, Recommendation REC-webstorage-20130730, July 2013,
<http://www.w3.org/TR/2013/REC-webstorage-20130730>. <http://www.w3.org/TR/2013/REC-webstorage-20130730>.
Appendix A. (Informative) Applicability of features for each messages Appendix A. (Informative) Applicability of features for each messages
This section provides cross-reference table about applicability of This section provides a cross-reference table showing the
each features provided in this specification for each kinds of applicability of the features provided in this specification to each
responses described in Section 2.1. The table provided in this kind of responses described in Section 2.1. The table provided in
section is for informative purposes only. this section is for informative purposes only.
+-------------------+-------+----------+-----------+------+ +-------------------+-------+----------+-----------+------+
| | init. | success. | intermed. | neg. | | | init. | success. | intermed. | neg. |
+-------------------+-------+----------+-----------+------+ +-------------------+-------+----------+-----------+------+
| Optional auth. | O | n | N | N | | Optional auth. | O | n | N | N |
| auth-style | O | - | - | O | | auth-style | O | - | - | O |
| loc.-when-unauth. | O | I | I | i | | loc.-when-unauth. | O | I | I | i |
| no-auth | O | I | I | i | | no-auth | O | I | I | i |
| loc.-when-logout | - | O | - | - | | loc.-when-logout | - | O | - | - |
| logout-timeout | - | O | - | - | | logout-timeout | - | O | - | - |
skipping to change at page 23, line 42 skipping to change at page 24, line 4
| Optional auth. | O | n | N | N | | Optional auth. | O | n | N | N |
| auth-style | O | - | - | O | | auth-style | O | - | - | O |
| loc.-when-unauth. | O | I | I | i | | loc.-when-unauth. | O | I | I | i |
| no-auth | O | I | I | i | | no-auth | O | I | I | i |
| loc.-when-logout | - | O | - | - | | loc.-when-logout | - | O | - | - |
| logout-timeout | - | O | - | - | | logout-timeout | - | O | - | - |
| username | O | - | - | O | | username | O | - | - | O |
+-------------------+-------+----------+-----------+------+ +-------------------+-------+----------+-----------+------+
Legends: Legends:
O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain
i = SHOULD be ignored; I = MUST be ignored; i = SHOULD be ignored; I = MUST be ignored;
- = meaningless (to be ignored) - = meaningless (to be ignored)
Appendix B. (Informative) Draft Notes Appendix B. (Informative) Draft Change Log
Things which might be considered for future revisions: [To be removed on final publication]
o In [RFC7235], meaning of WWW-Authenticate headers in non-401 B.1. Changes in Httpauth WG Revision 06
responses are defined as "supplying credentials (or different
credentials) might affect the response". This clarification
change leaves a way for using 200-status responses along with a
WWW-Authenticate header for providing optional authentication.
Incorporating this possibility, however, needs more detailed
analysis on the behavior of existing clients and intermediate
proxies for such possibly-confusing responses. Optional-WWW-
Authenticate is safer, at least for minimum backward
compatibility, because clients not supporting this extension will
consider this header as an unrecognized entity-header, possibly
providing opportunity for silently falling-back to application-
level authentications.
Appendix C. (Informative) Draft Change Log o Several comments from reviewers are reflected to the text.
C.1. Changes in Httpauth WG revision 04 B.2. Changes in Httpauth WG Revision 05
o Authors' addresses updated.
B.3. Changes in Httpauth WG revision 04
o IANA consideration section added. o IANA consideration section added.
C.2. Changes in Httpauth WG revision 03 B.4. Changes in Httpauth WG revision 03
o Adopting RFC 5987 extended syntax for non-ASCII parameter values. o Adopting RFC 5987 extended syntax for non-ASCII parameter values.
C.3. Changes in Httpauth WG revision 02 B.5. Changes in Httpauth WG revision 02
o Added realm parameter. o Added realm parameter.
o Added username parameter. We acknowledge Michael Sweet's proposal o Added username parameter. We acknowledge Michael Sweet's proposal
for including this to the Basic authentication. for including this to the Basic authentication.
C.4. Changes in Httpauth WG revision 01 B.6. Changes in Httpauth WG revision 01
o Clarification on peers' responsibility about handling of relative o Clarification on peers' responsibility about handling of relative
URLs. URLs.
o Automatic reloading should be allowed only on safe methods, not o Automatic reloading should be allowed only on safe methods, not
always on idempotent methods. always on idempotent methods.
C.5. Changes in Httpauth revision 00 and HttpBis revision 00 B.7. Changes in Httpauth revision 00 and HttpBis revision 00
None. None.
C.6. Changes in revision 02 B.8. Changes in revision 02
o Added usage examples. o Added usage examples.
C.7. Changes in revision 01 B.9. Changes in revision 01
o Syntax notations and parsing semantics changed to match httpbis o Syntax notations and parsing semantics changed to match httpbis
style. style.
C.8. Changes in revision 00 B.10. Changes in revision 00
o Separated from HTTP Mutual authentication proposal (-09). o Separated from HTTP Mutual authentication proposal (-09).
o Adopting httpbis works as a referencing point to HTTP. o Adopting httpbis works as a referencing point to HTTP.
o Generalized, now applicable for all HTTP authentication schemes. o Generalized, now applicable for all HTTP authentication schemes.
o Added "no-auth" and "auth-style" parameters. o Added "no-auth" and "auth-style" parameters.
o Loosened standardization requirements for parameter-name tokens o Loosened standardization requirements for parameter-name tokens
 End of changes. 117 change blocks. 
280 lines changed or deleted 280 lines changed or added

This html diff was produced by rfcdiff 1.45. The latest version is available from http://tools.ietf.org/tools/rfcdiff/