Document authentication discovery on top of JMAP

[chibenwa]

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

[chibenwa]

https://jmap.io/server.html#401-unauthorized

As per the HTTP spec, the response MUST have a WWW-Authenticate header listing the available authentication schemes.

I still believe this deserves more visibility...

By the way the scope of this best practice is not limited to Binary upload error response codes... How about promoting it to a brand new HTTP best practices?

[judemille]

I'm not sure this is the best place to bring this up, but a way to discover an OAuth server (IIRC there are already specifications for dynamic registration for client-based software) to authenticate to the server could also be really useful.

[neilj]

While more discussion of this in the client and server guides is worthwhile, I do not think there is anything we need or really can do with specs here. JMAP uses HTTP, therefore uses HTTP authentication. Earlier versions of the draft tried to introduce an authentication protocol as well, but this was too contentious to get through the IETF standardisation process so was dropped. In practice, Basic and OAuth are the two authentication mechanisms that are likely to be commonly implemented. We can't mandate one or the other (for example Google would be unlikely to allow Basic auth, as they are generally moving to OAuth only, while others are unlikely to want to add that complexity). It's not an ideal situation, but it's no different to the current IMAP/SMTP situation, where we have exactly the same situation

OAuth itself has many different extensions, including dynamic client registration; again it's unfortunately out of scope of the JMAP spec to require particular extensions to be implemented.

[chibenwa]

I am fine with detailing this in the client / server guides.