RFC 8053

HTTP Authentication Extensions for Interactive Clients

📅 published January 2017, from ietf

HTTP Authentication Extensions for Interactive Clients 🎀

okay so this is RFC 8053 💖 and it's an Experimental spec, which means it's out there for people to try, test, and poke at, not a finished Internet Standard yet 🧪. It came out in January 2017 (ISSN 2070-1721), and it's written by Y. Oiwa, H. Watanabe, H. Takagi, K. Maeda, T. Hayashi, and Y. Ioku. The affiliations are ITRI, AIST, Lepidum, and one Individual Contributor 🌸. It doesn't list any documents it obsoletes or updates.

Abstract ✨

okay so this one is about extending the HTTP authentication framework for interactive clients 🦋. Right now, the basic features of HTTP-level authentication aren't enough for the complicated stuff that lots of web apps need, so apps end up building their own authentication systems with things like HTML forms 😭. That's a big reason why it's hard to bring in secure auth that servers and user agents handle together. The extended framework fills in the gaps between what web apps need and what HTTP authentication gives them, and it still stays compatible with existing web and non-web uses of HTTP authentication 💜.

Status of This Memo

This document is not an Internet Standards Track specification; it is published for examination, experimental implementation, and evaluation.

This document defines an Experimental Protocol for the Internet community. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are a candidate for any level of Internet Standard; see Section 2 of RFC 7841.

Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc8053. 🔍

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. ⚖️

Table of Contents 📑

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Definitions . . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Terms for Describing Authentication Protocol Flow . . . .   5
     2.2.  Syntax Notation . . . . . . . . . . . . . . . . . . . . .   8
   3.  Optional Authentication . . . . . . . . . . . . . . . . . . .   8
     3.1.  Note on Optional-WWW-Authenticate and Use of
           WWW-Authenticate Header with Non-401 Status . . . . . . .  10
   4.  Authentication-Control Header . . . . . . . . . . . . . . . .  11
     4.1.  Non-ASCII Extended Header Parameters  . . . . . . . . . .  13
     4.2.  Auth-Style Parameter  . . . . . . . . . . . . . . . . . .  13
     4.3.  Location-When-Unauthenticated Parameter . . . . . . . . .  14
     4.4.  No-Auth Parameter . . . . . . . . . . . . . . . . . . . .  15
     4.5.  Location-When-Logout Parameter  . . . . . . . . . . . . .  16
     4.6.  Logout-Timeout Parameter  . . . . . . . . . . . . . . . .  17
     4.7.  Username Parameter  . . . . . . . . . . . . . . . . . . .  17
   5.  Usage Examples  . . . . . . . . . . . . . . . . . . . . . . .  18
     5.1.  Example 1: A Portal Site  . . . . . . . . . . . . . . . .  19
       5.1.1.  Case 1: A Simple Application  . . . . . . . . . . . .  19
       5.1.2.  Case 2: Specific Action Required on Logout  . . . . .  20
       5.1.3.  Case 3: Specific Page Displayed before Login  . . . .  20
     5.2.  Example 2: Authenticated User-Only Sites  . . . . . . . .  20
     5.3.  When to Use Cookies . . . . . . . . . . . . . . . . . . .  21
     5.4.  Parallel Deployment with Form/Cookie Authentication . . .  22
   6.  Methods to Extend This Protocol . . . . . . . . . . . . . . .  23
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  23
   8.  Security Considerations . . . . . . . . . . . . . . . . . . .  24
     8.1.  Security Implication of the Username Parameter  . . . . .  24
   9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  25
     9.1.  Normative References  . . . . . . . . . . . . . . . . . .  25
     9.2.  Informative References  . . . . . . . . . . . . . . . . .  26
   Appendix A.  (Informative) Applicability of Features for Each
                Message  . . . . . . . . . . . . . . . . . . . . . .  27
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  27

1. Introduction ✨

okay so this document adds a few extensions to the current HTTP authentication framework 🦋. The goal is to give you stuff that's comparable to the form-based web auth that's everywhere right now. A majority of recent websites on the Internet use their own custom application-layer auth with web forms 💅. People have their reasons, but many people believe the current HTTP Basic and Digest methods don't have enough functionality (including good user interfaces) for most realistic web apps 🙈. The catch is that form-based web auth has some weaknesses against attacks like phishing, because the server-side app controls everything about how the auth behaves. That makes it really hard to add cryptographically strong auth mechanisms to web systems 😭. So we need to "modernize" the HTTP authentication framework, so that better client-controlled secure methods can work with web apps 🫶. The extensions in this document include:

  • optional authentication on HTTP (Section 3),
  • log out from both the server and client side (Section 4), and
  • finer control for redirection depending on the authentication status (Section 4)

1.1. Terminology 🧚

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

okay so the doc also splits up two words on purpose 💜. A "client" is an entity that understands and talks HTTP and the specified authentication protocol, and it's usually computer software. A "user" is a (usually natural) person who wants to get at data resources using "a client". Not the same thing, bestie! 🌈

2. Definitions 🌸

2.1. Terms for Describing Authentication Protocol Flow

okay so HTTP Authentication from [RFC7235] can involve a whole bunch of request/response pairs going back and forth 💬. so we're gonna give each message a label so we all know whose is whose ✨

For requests:

  1. Non-authenticating request: a request that's not trying to authenticate at all, aka a request with no Authorization header field 🙈
  2. Authenticating request: the total opposite, a request that does have an Authorization header field 💅

For responses:

  1. Non-authenticated response: a response that doesn't involve any HTTP authentication. it doesn't have a WWW-Authenticate ([RFC7235]) or Authentication-Info header field ([RFC7615]) in it. servers send this when the resource isn't guarded by an HTTP authentication mechanism. in this spec, negative responses that aren't about auth (like 403 and 404) count as non-authenticated responses too 🌸 (see the note on successfully authenticated responses below for some ambiguous cases)
  2. Authentication-initializing response: a response that requires or allows clients to start authentication attempts. servers send this when the resource IS protected by an HTTP authentication mechanism and the request hits one of these:
    • it's a non-authenticating request, or
    • it's an authentication trial aimed at a protection space (realm) that isn't the one the server expected

the server tells you which protection space to use for auth in this response 🎀

once the client gets this, things split into two possible vibes:

  • if the client has no prior knowledge of auth credentials (like a username and password) for that protection space, the protocol flow ends and the client asks the user for credentials 🙋‍♀️
  • if the client already has enough credentials for that protection space, it automatically sends an authenticating request. this happens a lot when the client doesn't know ahead of time that the current request-URL needs auth 🦋
  1. Successfully authenticated response: a response to an authenticating request that means the auth attempt was granted 👑 (note: if the auth scheme doesn't use an Authentication-Info header field, it can't be told apart from a non-authenticated response 💀)
  2. Intermediate authenticating response: a response to an authenticating request that needs the client software to react more without bringing users into it. this kind of response is required when a scheme needs two or more round-trip messages to authenticate, or when a scheme tries some speculative shortcut (like using cached shared secrets) and that fails ⚡
  3. Negatively authenticated response: a response to an authenticating request that means the auth attempt was declined, and it can't keep going without a different set of credentials 😤 clients usually wipe their memory of the active credentials and ask the user for other ones 🧹

these usually look the same as authentication-initializing responses. clients can tell negatively authenticated responses apart from authentication-initializing ones by comparing the protection spaces in the request and the response 🔍

Figure 1 shows a state diagram of generic HTTP authentication with the message categories above 🧚. heads up: lots of auth schemes only use a subset of the transitions in the diagram. the labels in the figure are the abbreviated names of response types.

   ===========                                -----------------
   NEW REQUEST                               ( UNAUTHENTICATED )
   ===========                                -----------------
        |                                            ^ non-auth.
        v                                            | response
+----------------------+ NO                         +-------------+
| The requested URI    |--------------------------->| send normal |
| known to be auth'ed? |           ---------------->|   request   |
+----------------------+          /                 +-------------+
       YES |                     /             initializing|
           v                    /                          |
  +------------------+ NO      /                           |
  | Can auth-req.(*1)|---------                            |
  | be constructed?  |                                     |
  +------------------+                                     |
       YES |            initializing                       |
           |      ---------------------------------------. |
           |     /                                       v v
           |    |            ----------------    NO  +-----------+
           |    |           ( AUTH-REQUESTED )<------| passwords |
           |    |            ----------------        |etc. known?|
           v    |                                    +-----------+
     +-----------+ negative   -------------   negative     |YES
     |   send    |---------->( AUTH-FAILED )<---------,    |
    /| auth-req  |            -------------           |    |
   / +-----------+\                                   |    v
  |             \  \  intermediate                   +-----------+
  |              \  -------------------------------->|   send    |
  |               \                                  | auth-req  |
  | non-auth.      \successful            successful +-----------+
  | response (*2)   \                               /     |    ^
  v                  \                             /      |    |
 -----------------    \       --------------      /       `----'
( UNAUTHENTICATED )    ----->( AUTH-SUCCEED )<----    intermediate
 -----------------            --------------

Figure 1: Generic State Diagram for HTTP Authentication

Notes on the diagram:

  • (*1) for example, the "Digest" scheme needs a server-provided nonce to build client-side challenges 🍓
  • (*2) in "Basic" and some others, this can't be told apart from a successfully authenticated response 💅

2.2. Syntax Notation

this spec uses an extended ABNF syntax defined in [RFC7230] and [RFC5234] 📐. the following syntax definitions are quoted from [RFC7230] and [RFC7235]: auth-scheme, quoted-string, auth-param, SP, BWS, header-field, and challenge. it also uses the convention of using header field names to specify the syntax of values for that header field ✨

then it adds these syntax definitions as a refinement of token and the right-hand side of auth-param in [RFC7235] 🎀

 bare-token           = bare-token-lead-char *bare-token-char
 bare-token-lead-char = %x30-39 / %x41-5A / %x61-7A
 bare-token-char      = %x30-39 / %x41-5A / %x61-7A / "-" / "_"
 extension-token      = "-" bare-token 1*("." bare-token)
 extensive-token      = bare-token / extension-token
 integer              = "0" / (%x31-39 *%x30-39)  ; no leading zeros

            Figure 2: The BNF Syntax for Common Notations

extensive-tokens are used in this protocol where the set of acceptable tokens includes private extensions 🧩. any extensions of this protocol MAY use either bare-tokens allocated by IANA (under the procedure described in Section 7), or extension-tokens in the format "-<token>.<domain-name>", where <domain-name> is a valid (sub-)domain name on the Internet owned by the party who defines the extension 🌈

3. Optional Authentication ✨

the Optional-WWW-Authenticate header lets you have a non-mandatory authentication, which isn't possible with the current HTTP authentication mechanism 🦋

in lots of web apps, users can get the same content as both a guest and an authenticated user 🙈. most of the time this is done with HTTP cookies [RFC6265] and custom form-based authentication. this new auth method using this message is meant to replace those systems 💖

servers MAY send HTTP non-interim responses containing the Optional-WWW-Authenticate header as a replacement for a 401 response when it's authentication-initializing. the Optional-WWW-Authenticate header MUST NOT be sent on 401 responses (so a regular WWW-Authenticate header MUST be used on 401 responses) 🚫

 Optional-WWW-Authenticate = 1#challenge

      Figure 3: BNF Syntax for Optional-WWW-Authenticate Header

Example:

HTTP/1.1 200 OK
Optional-WWW-Authenticate: Basic realm="xxxx"

the challenges in the Optional-WWW-Authenticate header are the same as the ones for a 401 response to the same request 🫶. for auth-related stuff, an optional authentication request means the same thing as a 401 message with a matching WWW-Authenticate header (as an authentication-initializing response) 💜. (the behavior for other stuff MAY be different between optional auth and 401 messages. for example, clients MAY choose to cache the 200 messages with the Optional-WWW-Authenticate header field but not the 401 messages by default 🍓)

a response with an Optional-WWW-Authenticate header SHOULD only come back from the server when the request is either non-authenticated or authenticating to a wrong protection space (not the one the server expects) 🎯. if a response is either an intermediate or a negative response to a client's auth attempt, the server MUST respond with a 401 status response with a WWW-Authenticate header instead 🔥. if you don't follow this rule, clients won't be able to tell auth successes and failures apart 😭

the server is NOT RECOMMENDED to include an Optional-WWW-Authenticate header in a positive response when a client's authentication attempt succeeds 💀

whenever an auth scheme supports servers sending a parameter that hints at the URL space for the corresponding protection space for the same realm (like "path" or "domain"), servers doing non-mandatory auth SHOULD send that parameter with the response 🗺️. clients that support non-mandatory auth MUST recognize the parameter and MUST send a request with an appropriate authentication credential in an Authorization header for any URI inside the specified paths 👑

implementations aren't required to support this header for all of their supported auth schemes (so they can choose to implement it for only a subset of them) 🌸. new auth schemes can require support of optional authentication as a prerequisite though ✨

3.1. Note on Optional-WWW-Authenticate and Use of WWW-Authenticate Header with Non-401 Status

okay bestie, so the current HTTP/1.1 spec makes it clear that the WWW-Authenticate header can show up on messages with status codes other than 401 (Authentication Required) 🎀. Like, a 200 response with WWW-Authenticate basically means something super similar to the Optional-WWW-Authenticate header we just defined ✨.

The whole point of Optional-WWW-Authenticate is that clients who don't know about this extension will just ignore it, and web devs can count on that to build a backup authentication method 🫶. A bunch of the behavior rules from the section above assume this too, and they're what make optional auth actually work reliably and consistently 💅.

BUT (lowkey the plot twist 😭) experiments and chats on the IETF mailing list showed that most (not all!) HTTP clients, at the time of writing, just ignore WWW-Authenticate headers on non-401 messages. So it kinda acts like Optional-WWW-Authenticate... except not every corner case was fully tested or well defined in the existing specs 💀.

So the authors went with a brand new header for this new "experiment" feature 🧪. That way this experimental doc doesn't have to define every single corner-case behavior for the existing WWW-Authenticate header, which some implementers might see as an incompatible change 🙅‍♀️. Not it, not doing that.

Experimentally, the authors propose that implementers of the standard HTTP/1.1 spec (especially implementers of this extension) handle the undefined, implementation-dependent details of WWW-Authenticate on non-401 messages in a similar way to what's defined for Optional-WWW-Authenticate 🔍. For example, they propose that servers return the 401 status for failed authentication attempts, even when the unauthenticated request to the same resource results in a 200 status. This can determine how (or whether) non-mandatory authentication can be built using the standard header fields and status codes. If the experiment is successful, a future revision of this experimental doc may "bless" and recommend the standard WWW-Authenticate header, with some stricter requirements on corner-case behavior 👑.

4. Authentication-Control Header ✨

Authentication-Control = 1#auth-control-entry
auth-control-entry     = auth-scheme 1*SP 1#auth-control-param
auth-control-param     = extensive-token BWS "=" BWS token
                       / extensive-token "*" BWS "=" BWS ext-value
ext-value              = <see RFC 5987, Section 3.2>

Figure 4: The BNF Syntax for the Authentication-Control Header

The Authentication-Control header gives you way more precise control over how clients behave in Web apps that use an HTTP authentication protocol 🎀. It's meant to be generated in the application layer, unlike the WWW-Authenticate headers, which usually come from the Web servers 🧚.

Clients MAY freely choose any subset of these parameters to be supported 🌸. They can also choose to support any of the parameters for only a subset of their supported authentication schemes. Just know that authentication schemes can require or recommend some of these parameters as a prerequisite 💅.

The Authentication-Control header holds one or more "authentication control entries," and each one corresponds to a single realm for a specific authentication scheme 🦋. If the auth-scheme for an entry supports the HTTP "realm" feature, that entry MUST contain the "realm" parameter. If not, the entry MUST NOT contain the "realm" parameter.

Among all the entries in the header, the relevant ones are the ones matching an auth-scheme and a realm (if any) for which "the authentication process is being performed or going to be performed." Here's how that breaks down 👀:

  1. If the response is an authentication-initializing response or a negatively authenticated response, the WWW-Authenticate header (or the Optional-WWW-Authenticate header defined in this extension) can have multiple challenges, each corresponding to a different scheme and realm. In this case, the client gets to choose which scheme and realm to authenticate with. Only the Authentication-Control entry for that scheme and realm is relevant 🫶.
  2. If the response is an intermediate authenticating response or a successfully authenticated response, the scheme and realm given in the Authorization header of the HTTP request decide which authentication process is currently ongoing. Only the entry for that scheme and realm is relevant 🔥.

The server MAY send an Authentication-Control header containing non-relevant entries. The client MUST ignore all non-relevant entries it received 🙈.

Every entry has one or more parameters, and each one is a name-value pair 💜. The name of each parameter MUST be an extensive-token. Clients MUST ignore any unknown parameters contained in this header. The entries for the same auth-scheme and realm MUST NOT contain duplicated parameters for the same name. Clients MAY either take any one of those duplicated entries or ignore all of them 🌈.

The type of a parameter's value depends on its name, as defined in the subsections below. No matter the type, though, recipients MUST accept both quoted and unquoted representations of values as defined in HTTP ✨. If the parameter is defined to have a string value, implementations MUST send any value outside of the "token" ABNF syntax either in a quoted form or in an ext-value form (see Section 4.1). If the parameter is defined as a token (or similar) or an integer, the value SHOULD follow the corresponding ABNF syntax after possible unquoting of the quoted-string value (as defined in HTTP), and it MUST be sent in a plain (not ext-value) form. (Note: the rest of this document will show all string-value parameters in quoted forms, and it will show others in unquoted forms.) 🍓

Any parameters contained in this header MAY be ignored by clients. Also, even when a client accepts this header, users are able to get around the semantics of this header 😬. So if this header is used for security purposes, its use MUST be limited to providing some non-fundamental additional security measures that are valuable for end-users (such as client-side logout for protection against console takeover). Server-side applications MUST NOT rely on this header to protect server-side resources. Not a vibe to skip, bestie 💀.

Note: The header syntax lets servers specify Authentication-Control for multiple authentication schemes, either as multiple occurrences of this header or as a single combined header (see Section 3.2.2 of [RFC7230] for the rationale). The same care needed for parsing multiple authentication challenges needs to be taken here too 🧠.

4.1. Non-ASCII Extended Header Parameters

Parameters in the Authentication-Control header MAY be extended to non-ASCII values using the framework described in [RFC5987] 🌍. All servers and clients MUST be capable of receiving and sending values encoded in [RFC5987] syntax.

If a value to be sent contains only ASCII characters, the field MUST be sent using plain RFC 7235 syntax. The syntax as extended by ext-value MUST NOT be used in this case 🔤.

If a value (except the "realm" header) contains one or more non-ASCII characters, the parameter SHOULD be sent using the ext-value syntax 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 omitted (have an empty value). The same parameter MUST NOT be sent more than once, regardless of the syntax used ✨.

For example, a parameter "username" with the value "Renee of France" 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-8''Ren%C3%89e%20of%20France > instead 🦋.

Interoperability note: [RFC7235], Section 2.2, defines the "realm" authentication parameter, and it cannot be replaced by the "realm*" extend parameter. This means that using non-ASCII values for an authentication realm is not the defined behavior in HTTP. Unfortunately, some people do use a non-ASCII realm parameter in reality, but even its encoding scheme isn't well defined 😭. Given this, this document does not specify how to handle a non-ASCII "realm" parameter in the extended header fields. If needed, the authors propose using a non-extended "realm" parameter form, with a wish for maximum interoperability 🫶.

4.2. Auth-Style Parameter

Example:

Authentication-Control: Digest realm="protected space",
auth-style=modal

The parameter "auth-style" specifies the server's preference for user interface behavior during user authentication 👑. This parameter can be included in any kind of response, but it's only meaningful for authentication-initializing or negatively authenticated responses. The value of this parameter MUST be one of the bare-tokens, "modal" or "non-modal". When the Optional-WWW-Authenticate header is used, the value of this parameter MUST be disregarded and the value "non-modal" is implied 🙅‍♀️.

The value "modal" means the server thinks the content of the response (body and other content-related headers) is only valuable to users who refuse the authentication request. Clients are expected to ask the user for a password before processing the content. This behavior is common in most current implementations of Basic and Digest authentication schemes 🔐.

The value "non-modal" means the server thinks the content of the response (body and other content-related headers) is valuable to users before they process an authentication request. Clients are expected to process the content first and then give users the opportunity to authenticate 🌸.

The default behavior for clients is implementation dependent, and it may also depend on the authentication scheme. The proposed default is "modal" for all authentication schemes unless otherwise specified 🤷‍♀️.

These two different methods of authentication can possibly introduce an observable difference in semantics when the response contains state-changing side effects. For example, they can affect how Cookie headers [RFC6265] in 401 responses are processed. However, server applications SHOULD NOT depend on the existence of such side effects 🍭.

4.3. Location-When-Unauthenticated Parameter 🧭

Example:

Authentication-Control: Mutual realm="auth-space-1",
location-when-unauthenticated="http://www.example.com/login.html"

okay so the location-when-unauthenticated parameter tells unauthenticated clients where to go 🗺️ It's giving central login page for the whole Web application, and the value is a string that holds a URL location. If a received URL is not absolute, clients SHOULD consider it a relative URL from the current location ✨

This parameter MAY be used with a 401 response for an authentication-initializing response 💅 It can also be contained, although this is NOT RECOMMENDED, in a positive response with an Optional-WWW-Authenticate header 🙈 The clients MUST ignore this parameter when a response is either successfully authenticated or intermediately authenticated 🫶

When a client gets an authentication-initiating response with this parameter, and it has to ask users for credentials, the client treats the whole response like a 303 "See Other" response. The Location header is the value of this parameter, so the client gets redirected there with a GET request 🦋 Unlike a normal 303 response, if the client can process authentication without the user's interaction, this parameter MUST be ignored ✨

4.4. No-Auth Parameter 🙈

Example:

Authentication-Control: Basic realm="entrance", no-auth=true

the no-auth parameter is basically a sibling of location-when-unauthenticated 💖 It says new authentication attempts are not to be performed on this location, which makes the user experience smoother, but it does NOT do any redirecting at the HTTP level. This is useful when there's a central login page for the whole Web application and you want an explicit user interaction with the Web content before authentication starts 🌸 The value of this parameter MUST be a token "true". If the value is incorrect, the client MAY ignore this parameter 🤷‍♀️

This parameter MAY be used with authentication-initiating responses. It can also be contained, although this is NOT RECOMMENDED, in a positive response with an Optional-WWW-Authenticate header. The clients MUST ignore this parameter when a response is either successfully authenticated or intermediately authenticated 🔥

When a client gets an authentication-initiating response with this parameter, and it has to ask users for credentials, the client ignores the WWW-Authenticate header in that response. It treats the whole thing as a normal negative 4xx-class response, so the user never gets the chance to start authentication 💀 If the client can process authentication without the user's interaction, this parameter MUST be ignored.

Using this parameter together with location-when-unauthenticated is meaningless 🙃 If both show up, clients SHOULD ignore the location-when-unauthenticated parameter.

This parameter SHOULD NOT be used as a security measure to stop authentication attempts, because users can easily get around it 🚨 It SHOULD be used solely for improving the user experience of Web applications 🎀

4.5. Location-When-Logout Parameter 🚪

Example:

Authentication-Control: Digest realm="protected space",
location-when-logout="http://www.example.com/byebye.html"

the location-when-logout parameter says where the client gets sent when the user explicitly requests a logout 👋 The value MUST be a string that contains a URL location. If a given URL is not absolute, the clients MUST consider it a relative URL from the current location 🗺️

This parameter MAY be used with successfully authenticated responses. If this parameter shows up in any other kind of response, the clients MUST ignore this parameter 🙅‍♀️

When the user tells the client to end the current authentication period, and the client is showing a page that came from a response with this parameter, the client automatically changes the current location to the one in this parameter. It does this with a new GET request, as if it had received a 303 response 🦋 Any logout operations (like erasing memories of the username, the authentication credential, and all related one-time credentials such as nonce or keys) SHOULD occur before the page transition happens 🧹

When the user asks the client to end an authentication period, the client supports this parameter, but the server response doesn't contain it, the client's RECOMMENDED behavior goes like this 💅 If the request for the current content was the GET method, the client reloads the page without the authentication credential. Otherwise, it keeps the current content as-is and just forgets the authentication status. The client SHOULD NOT replay a non-idempotent request without the user's explicit approval 🛑

Web applications are encouraged to send this parameter with an appropriate value for any responses (except those with redirection (3XX) statuses) for non-GET requests 🌈

See Section 5 for some examples of how this parameter can be deployed 🧚

4.6. Logout-Timeout Parameter ⏰

Example:

Authentication-Control: Basic realm="entrance", logout-timeout=300

the logout-timeout parameter shows up in a successfully authenticated response 🍓 It means any authentication credentials and state for the current protection space get discarded once the number of seconds in this header has passed since the header was received. The value MUST be an integer. The special case is 0, which means the server is logging the client out of the current authentication space right now, and the client goes back to the unauthenticated state 😭

This does not, however, mean that the long-term memories for passwords and password-related details (like password reminders and auto fill-ins) should be removed 🔐 If a new timeout value comes in for the same authentication space, it cancels the previous timeout and sets a new one ⭐

4.7. Username Parameter 👤

Example:

Authentication-Control: Basic realm="configuration", username="admin"

the username parameter basically says the only username the server will accept is the value given here 🫶

This one is super useful for routers and other network appliances with a Web configuration interface 🛜 A lot of those use HTTP Basic authentication with one predefined username, like "admin", "root", "user", and so on. Right now, users have almost no hint about the valid username when the authentication request pops up. Some sites show it in a "realm" string, and some put it on the 401-status response page, which users only see after they've given up and canceled the dialog 🙃 If this parameter is given, the client Web browser can auto-fill the username field in the authentication dialog before the user tries to authenticate 🧁

This parameter MAY be used with authentication-initiating responses or negatively authenticated responses that need another attempt at authentication. The clients MUST ignore this parameter when a response is either successfully authenticated or intermediately authenticated 💖

If the authentication scheme has a syntax limit on allowed usernames (for example, Basic and Digest don't allow colons in usernames), the specified value MUST follow that limit. Clients SHOULD ignore any values that don't conform to those limits 🚫

Also, if the authentication scheme needs a specific style of text preparation for the username (like PRECIS [RFC7564] string preparation or Unicode normalization), the server SHOULD send values that meet those requirements, so clients can use the username as is ✨

Clients MAY still send authentication requests with other usernames, possibly in vain 🤷‍♀️ Clients are not required (and also not forbidden) to give users a chance to type in a username different from the server-specified one. Servers are also not strictly required to reject usernames other than the specified one, but doing that will usually lead to bad user experiences and can confuse both users and clients 😵‍💫

Although this parameter is useful in a specific class of use cases, using it in a general use case has lots of security implications and possible pitfalls 🚨 Please consult Section 8.1 before you decide to use this parameter, bestie 🫶

5. Usage Examples 🎬

This section shows some examples of applying this extension to typical websites that use forms and cookies to manage authentication and authorization 🍪 The content of this section is not normative and is for illustrative purposes only, so don't treat it as the rulebook 📖

In these examples, we assume there are two kinds of clients (Web browsers). One kind implements all the features described in the previous sections. We also assume those browsers have a user interface that lets users deactivate (log out from) current authentication sessions. The other kind are the "existing" implementations, which don't support any of these features 🧐

When nothing is explicitly specified, all the settings described below are applied with Authentication-Control headers. These headers can be sent to clients regardless of the authentication status, and they're silently ignored whenever they aren't effective 🤫

5.1. Example 1: A Portal Site 🌐

This subsection gives an example for a site whose structure is kind of like a conventional portal site. Most Web pages are available to guest (unauthenticated) users, and if someone does authenticate, the content of those pages gets customized for them 💜 We assume the site currently has these kinds of pages:

  • Content pages
  • Pages/mechanism for performing authentication:
    • There is one page that asks for a username and a password using a HTML POST form 📝
    • After the authentication attempt, the user gets redirected either to the page they were on before, or to some specific page 🦋
  • A de-authentication (logout) page 👋

5.1.1. Case 1: A Simple Application 🧁

When a site like this doesn't need any special actions on login and logout, these simple settings do the trick ✨

  • Set up an optional authentication for all pages available to guests. Set up an Authentication-Control header with the auth-style=non-modal setting.
  • If there are pages only available to authenticated users, set up a mandatory authentication with the auth-style=non-modal setting.
  • No specific pages for authentication are needed. It gets performed automatically, directed by the setting above 🪄
  • A de-authentication page isn't needed either. If the site has one anyway, put logout-timeout=0 there 💅
  • For all pages that handle POST requests, it's advisable to have a location-when-logout=<some page> 🌸

5.1.2. Case 2: Specific Action Required on Logout 🚪✨

okay so if the site needs specific actions when someone logs out, these settings do the trick 💅

  • All settings in Case 1 are applied.
  • For all pages, set up the Authentication-Control header with location-when-logout=<de-authentication page>.
  • On the de-authentication page, no special setup is needed. If there are any direct links to that page, put logout-timeout=0 on them. 🦋

5.1.3. Case 3: Specific Page Displayed before Login 📣🌸

so say the site wants to show a special page before people log in (announcements, user notices, maybe even ads 👀), here's the setup:

  • Set up optional authentication on all pages that guests can see. Put no-auth=true in an Authentication-Control header, and add a link to a specific login page in the contents. 🎀
  • If there are pages that only authenticated users can see, set up mandatory authentication with location-when-unauthenticated=<the login page>.
  • For the specific login page, set up mandatory authentication.
  • For all pages that handle POST requests, it is advisable to have location-when-logout=<some page> too. 💜
  • De-authentication pages aren't needed. If the site has one anyway, put logout-timeout=0 on it.

5.2. Example 2: Authenticated User-Only Sites 🔐

if almost every page needs a login (think an internet banking site), or if there's no need to support both logged-out and logged-in users on the same resource, the setup gets way simpler 🙌. Here's what that looks like:

  • Set up mandatory authentication on all pages that authenticated users can see. Set up an Authentication-Control header with auth-style=non-modal. ⭐
  • Set up a handler for the 401 status that asks users to authenticate.
  • For all pages that handle POST requests, it is advisable to have location-when-logout=<some page> too.
  • De-authentication pages aren't needed. If the site will have one, put logout-timeout=0 there.

5.3. When to Use Cookies 🍪

in current websites that use form-based authentication, Cookies [RFC6265] manage both authorization and application sessions. With the extensions in this document, the authorization part can be handled by (extended) HTTP authentication/authorization mechanisms instead. Sometimes it's kinda unclear whether a feature is for authorization or session management, so these hints should help you pick 🧚

  • If you need to serve multiple sessions for one user using multiple browsers at the same time, use a Cookie to tell those sessions apart. (Side note: if you only need to distinguish sessions within the same browser, HTML5 Web Storage [W3C.REC-webstorage-20130730] can be used instead of Cookies. 💖)
  • If a website is currently deploying a session time-out feature, think about who benefits from it. Most of the time, the main goal is to protect users from having their consoles and browsers hijacked, so the benefit is on the users' side. In that case, the time-out features in this extension can be used. 🛡️ On the other hand, if the goal is to protect the server's privileges (for example, when regulations require limiting the time between a user's two-factor authentication and a financial transaction commitment, and the requirement is strictly on the server's side), that should be managed on the server side using Cookies or other session-management mechanisms. 🫶

during transition periods, sites may need to support both HTTP-layer and form-based authentication at once. Here's one way to make that work 💅

  • If Cookies are used even for HTTP-authenticated users, each session determined by Cookies SHOULD identify which authentication has been used for that session.
  • First, set up any of the above settings to enable HTTP-layer authentication.
  • For unauthenticated users, add the following to the Web pages, unless the client supports this extension and HTTP-level authentication:
    • For non-mandatory authenticated pages, add a link to the form-based authenticated pages.
    • For mandatory authenticated pages, either put a link to the form-based authenticated pages, or put an HTML-level redirection (using <META http-equiv="refresh" ...> element) to those pages.
  • On the form-based authenticated pages, if users are not authenticated, the page can redirect them for HTTP-level authentication using the location-when-unauthenticated setting.
  • Users are identified for authorization and content customization by the following logic:
    • First, check the result of the HTTP-level authentication. If there is a Cookie session tied to a specific user, both should match.
    • If the user is not authenticated on the HTTP level, use the conventional form-based method to determine the user.
    • If there is a Cookie tied to HTTP authentication but no corresponding HTTP authentication result, that session will be discarded (because it means authentication has been deactivated by the corresponding user). 🙈

6. Methods to Extend This Protocol 🧩

if you implement a private extension to this protocol, it MUST use the extension-param so it doesn't clash with this protocol or any other extensions 🫣. (Standardized extensions, or extensions that are being standardized, MAY use either bare-tokens or extension-tokens.)

When bare-tokens are used in this protocol, they MUST be allocated by IANA. Any tokens used for non-private, non-experimental parameters are RECOMMENDED to be registered with IANA, no matter what kind of token is used. 📝

Extension-tokens MAY be freely used for any non-standard, private, and/or experimental uses. An extension-token MUST use the format -<bare-token>.<domain-name>, where <domain-name> is a validly registered (sub-)domain name on the Internet owned by the party that defines the extensions. Any unknown parameter name is to be ignored, regardless of whether it is an extension-token or a bare-token. 🤷‍♀️

7. IANA Considerations 🏛️

this document defines two new entries for the "Permanent Message Header Field Names" registry 🎉

+-------------+---------------------------+-------------------------+
|             | Entry 1:                  | Entry 2:                |
+-------------+---------------------------+-------------------------+
| Header      | Optional-WWW-Authenticate | Authentication-Control  |
| Field Name  |                           |                         |
| Protocol    | http                      | http                    |
| Status      | experimental              | experimental            |
| Change      | IETF                      | IETF                    |
| Control     |                           |                         |
| Spec.       | Section 3 of this         | Section 4 of this       |
| Document    | document                  | document                |
+-------------+---------------------------+-------------------------+

This document also establishes the "HTTP Authentication Control Parameters" registry 📋. The registry manages case-insensitive ASCII strings. The string MUST follow the extensive-token syntax defined in Section 2.2.

To acquire registered tokens, a specification for the use of those tokens MUST be available as a publicly accessible document (see "Specification Required" in [RFC5226]).

Registrations for authentication control parameters are required to include a description of the control extension. New registrations are advised to provide the following information:

  • Token: A token used in HTTP headers for identifying the algorithm.
  • Specification: A reference for the specification defining the algorithm.

The initial content of this registry is as follows:

  +-------------------------------+------------------------------+
  | Token                         | Specification                |
  +-------------------------------+------------------------------+
  | auth-style                    | Section 4.2 of this document |
  | location-when-unauthenticated | Section 4.3 of this document |
  | no-auth                       | Section 4.4 of this document |
  | location-when-logout          | Section 4.5 of this document |
  | logout-timeout                | Section 4.6 of this document |
  | username                      | Section 4.7 of this document |
  +-------------------------------+------------------------------+

8. Security Considerations 🚨

Serious business time, bestie. Please read this part carefully 🫶

The purpose of the logout timeout feature in the Authentication-Control header is to protect users of clients from impersonation caused by an attacker who has access to the same console. Server application implementers SHOULD be aware that the directive may always be ignored by either malicious clients or clients that don't support this extension. If the purpose of introducing a timeout for an authentication period is to protect server-side resources, this protection MUST be implemented by other means, such as HTTP Cookies [RFC6265].

All parameters in the Authentication-Control header SHOULD NOT be used for any security-enforcement purposes. Server-side applications MUST NOT assume that the header will be honored by clients and users. 💀

8.1. Security Implication of the Username Parameter 👤

The "username" parameter sometimes reveals sensitive information about the HTTP server and its configurations, and that information can be useful for security attacks 😬. In general, common security practice says that any information about whether a specific username exists or doesn't exist shall not be disclosed before successful authentication. Obviously, the "username" parameter goes against this practice.

Given this background, the use of the "username" parameter SHOULD be strictly limited to cases where all of the following conditions are met:

(1) the valid username is pre-configured and not modifiable (such as root, admin, or similar ones);

(2) the valid username for such an appliance is publicly known (for example, written in a manual document); and

(3) either the valid username for the server is easily guessable by other means (for example, from the model number shown on an unauthenticated page), or the server is accessible only from limited networks.

Most importantly, the "username" parameter SHOULD NOT be used in any case where valid usernames can be changed or configured by users or administrators. 🔥

9. References 📚

9.1. Normative References 📚

okay bestie, this is the homework list 🎀 these are the docs the spec leans on, so you need them to read it properly. every entry is copied with all its details so you can look them up 🔍

9.2. Informative References 🦋

these ones are the background reading 🫶 helpful for context, but the spec doesn't lean on them the same way.

Appendix A. (Informative) Applicability of Features for Each Message 🧚

this is the cheat sheet 💅 it shows which features from this spec apply to each kind of response from Section 2.1. it's only here to help you read things at a glance, so it's informative, not binding.

        +-------------------+-------+----------+-----------+------+
        |                   | init. | success. | intermed. | neg. |
        +-------------------+-------+----------+-----------+------+
        | Optional auth.    | O     | n        | N         | N    |
        | auth-style        | O     | -        | -         | O    |
        | loc.-when-unauth. | O     | I        | I         | i    |
        | no-auth           | O     | I        | I         | i    |
        | loc.-when-logout  | -     | O        | -         | -    |
        | logout-timeout    | -     | O        | -         | -    |
        | username          | O     | -        | -         | O    |
        +-------------------+-------+----------+-----------+------+

Legends:

  • O = MAY contain; n = SHOULD NOT contain; N = MUST NOT contain
  • i = SHOULD be ignored; I = MUST be ignored;
  • - = meaningless (to be ignored)

Authors' Addresses 🌸

the people who wrote this 🙌 here are their addresses, copied exactly.

Yutaka Oiwa
National Institute of Advanced Industrial Science and Technology
Information Technology Research Institute
Tsukuba Central 1
1-1-1 Umezono
Tsukuba-shi, Ibaraki
Japan

Email: y.oiwa@aist.go.jp
Hajime Watanabe
National Institute of Advanced Industrial Science and Technology
Information Technology Research Institute
Tsukuba Central 1
1-1-1 Umezono
Tsukuba-shi, Ibaraki
Japan

Email: h-watanabe@aist.go.jp
Hiromitsu Takagi
National Institute of Advanced Industrial Science and Technology
Information Technology Research Institute
Tsukuba Central 1
1-1-1 Umezono
Tsukuba-shi, Ibaraki
Japan

Email: takagi.hiromitsu@aist.go.jp
Kaoru Maeda
Lepidum Co. Ltd.
Village Sasazuka 3, Suite #602
1-30-3 Sasazuka
Shibuya-ku, Tokyo
Japan

Email: maeda@lepidum.co.jp
Tatsuya Hayashi
Lepidum Co. Ltd.
Village Sasazuka 3, Suite #602
1-30-3 Sasazuka
Shibuya-ku, Tokyo
Japan

Email: hayashi@lepidum.co.jp
Yuichi Ioku
Individual Contributor

Email: mutual-work@ioku.org

that's the whole spec, bestie 🌈✨ you made it through every section 😭💖

📦 where this page comes from