Document authentication discovery on top of JMAP

Issue

Authentication discovery is a major interoperability concern on top of JMAP, thus defeating the inter-operability goal of JMAP, turning this standard merely into the webMail industry best practice.

As a third-party client, I have no prior knowledge of the authentication schemes supported by the JMAP server. As a third-party client, I need a way to discover supported authentication scheme (to ease end user configuration options).

Standards that solves this issue

Luckily, RFC-2617 (https://tools.ietf.org/html/rfc2617#section-3.2.1) about HTTP authentication introduce such a mechanism through WWW-Authenticate header. A failed 401 authentication would result in this header being positioned, allowing discovery for the client of the supported authentication mechanisms. The client can then set up the authentication mechanism it supports and prefer, without requiring user input.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate further

RFC-7235 updates RFC-2617 (https://tools.ietf.org/html/rfc7235#section-4.1)

   A server generating a 401 (Unauthorized) response MUST send a
   WWW-Authenticate header field containing at least one challenge. 

So far JMAP implementation do not emntionWWW-Authenticate header field.

Here is an example of multi-challenge WWW-Authenticate header (RFC-7235):

WWW-Authenticate: Newauth realm="apps", type=1,  title="Login to \"apps\"", Basic realm="simple"

Please note that this header also can be used, if desired, to give hints toward why auth failed... Example (https://tools.ietf.org/html/rfc6750#section-3):

     HTTP/1.1 401 Unauthorized
     WWW-Authenticate: Bearer realm="example",
                       error="invalid_token",
                       error_description="The access token expired"

A full list of standard auth shemes is available here: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml

Sadly, RFC-8620 do not mention the existence of RFC-7235 nor the existence of WWW-Authenticate header.

Proposal

My true feeling is that the above mentioned best practices needs at least to be documented, at most mandated.

• Update jmap.io server guide to advise positionning WWW-Authenticate header.
• Update jmap.io client guide to mention the use of WWW-Authenticate header as an auto-discovery mechanism - and maybe also include also advises and step toward session discovery?
• Perform an errata of RFC8620 (JMAP core) to mention this mechanism (MUST)

Also, connecting James with LTT.RS I got lucky that we had an authentication mechanism in common... Maybe some common ground needs to be find here too?

• Advise a standard mechanism: Basic auth ? (I know it brings security concerns but is there something more generic?)

Related links

• Apache James project issue to support WWW-Authenticate: https://issues.apache.org/jira/browse/JAMES-3522
• https://tools.ietf.org/html/rfc7235 Hypertext Transfer Protocol (HTTP/1.1): Authentication
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/WWW-Authenticate WWW-Authenticate web doc
• http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml authentication scheme registry

Start with the JMAP server and client guides on jmap.io and the authentication sections of RFC 8620, then compare them with RFC 7235's WWW-Authenticate requirements. Document the client discovery guidance and determine whether the RFC errata or a normative requirement is in scope; done means the agreed guidance is reflected in the relevant documentation.