What WWW-Authenticate header should a http server return in a 401 response when using form-based authentication?

Question

I have a web application with a Javascript part running on the browser. That frontend uses several HTTP endpoints (more or less REST). The frontend must be able to distinguish between 401 and 403 responses and must not receive the 3xx redirects usually used for human users.

Authorization is done with a plain form login (no Javascript involved there), then a session cookie is used (for both "REST" and normal requests).

What would be a correct value for the WWW-Authenticate header value?

• From RFC 7235: "A server generating a 401 (Unauthorized) response MUST send a WWW-Authenticate header field containing at least one challenge."

• The Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry does not list any scheme for form-based authentication.

See also:

• HTTP 401 Unauthorized when not using HTTP basic auth?
• Authorization in RESTful HTTP API, 401 WWW-Authenticate

Answer 1

In theory you should respond

HTTP/1.x 401 Unauthorized
WWW-Authenticate: cookie; cookie-name=my-session-cookie-name

However, real world internet browsers (user agents) do not really support this and in my experience the least bad option is to use HTTP status 403 for all of "Access Denied", "Unauthorized" or "Not allowed". If you have a REST service that's accessed with non-browser user-agents only, you could just follow the spec and return the above headers.

Also note that as described in RFC 7231 section 6.5.4 (https://www.rfc-editor.org/rfc/rfc7231#section-6.5.4) the server can respond with 404 for both "Access Denied" and "Not Found" so following should be okay for all user agents (browsers and standalone clients):

403 Unauthorized or Not allowed

404 Access Denied or Not Found

Or, you can just use 400 for any case because that should cause browser do fallback to generic error handling case. The HTTP status code 401 is especially problematic because it historically meant (at least in practice) that Basic Realm authentication is in use and the submitted HTTP header Authorization was not accepted. Because you cannot submit the session cookie via that header with commonly available browsers, those browsers have trouble handling 401 correctly when you use cookies for authentication. (According to the spec, HTTP 401 MUST include header WWW-Authenticate which should be used to figure out correct handling by the user agent but this doesn't seem to happen in reality with browsers.)

Answer 2

What would be a correct value for the WWW-Authenticate header value?

There's no point in returning 401 and WWW-Authenticate when you are not using HTTP Authentication as described in the RFC 7235. In HTTP Authentication, the client is expected to send the credentials in the Authorization header of the request with an authentication scheme token.

If you want to send the credentials in the request payload using POST, the 403 status code you be more suitable to indicate that the server has refused the request.

Answer 3

Since there is no standard challenge for this type of authentication, you are (as you predicted yourself) inventing your own.

I don't think there is a standard mechanism for specifying vendor tokens here, so I think the best thing you can do is use a token that's unlikely to clash with anything else.

Amazon has done this with AWS, and there's many others. My recommendation would be to use something like productname-schemename, for example acme-webauth.

Answer 4

There is no HTTP authentication scheme for form based authentication. Browsers implement basic, digest, etc. by showing a pop up where you can enter credentials.