Provide more information in the spec on how withCredentials and Access-Control-Allow-Credentials interact

[roryhewitt]

@annevk following on from our discussion at #251 I think it would make sense to include some more information in the spec on how withCredentials and Access-Control-Allow-Credentials interact. Based also, perhaps on this thread from @mnot and @sicking.

Basically, I think there should be two separate sections - one for client-side developers discussing why they should (or should not) specify withCredentials= true and exactly what it will affect (cookies, Authorization header, in-URL credentials etc.) and a separate section for back-end developers, indicating the circumstances under which they should return the Access-Control-Allow-Credentials header.

As an example of why I think we need separate sections, one of the first websites found via Google when I search for CORS is http://www.html5rocks.com/en/tutorials/cors/. This site (which is generally excellent as a CORS tutorial) includes the following erroneous information:

The Access-Control-Allow-Credentials header works in conjunction with the withCredentials property on the XMLHttpRequest 2 object. Both these properties must be set to true in order for the CORS request to succeed. If .withCredentials is true, but there is no Access-Control-Allow-Credentials header, the request will fail (and vice versa).

In this case, the vice-versa case mentioned is incorrect - if Access-Control-Allow-Credentials: true is returned, the request will succeed, whether or not .withCredentials is specified (ignoring any ACAO issues, obviously).

For my part, this was one of the first sites I looked at back in 2012 to gain more information about CORS, and this statement caused me to include all sorts of server-side code to check for the existence of cookies, Authorization header etc. in order to determine whether to return Access-Control-Allow-Credentials: true, since my fear was that if I returned it in every case, the request would fail.

Sure, you could say that I should have looked at the the actual W3C spec, which correctly doesn't say that, but nor does it say exactly what counts as credentials (beyond a somewhat vague "cookies, HTTP authentication, and client-side SSL certificates"). And a newbie to CORS (from either server-side or client-side) is likely to refer to 'user-friendly' websites as they are to the actual spec. More likely, actually. Finalkly, of course, that site refers (as do most 'CORS tutorials'!) to the W3C spec...

I'm thinking that we could provide some scenarios discussing the following:

• exactly what count as credentials (and will therefore be affected by withCredentials and Access-Control-Allow-Credentials)
• how the different 'combinations' play out
• best practices - should I always return Access-Control-Allow-Credentials: true when I'm returning Access-Control-Allow-Origin: <value-of-Origin-header> just in case the request may include credentials? What risks does that open me up to?

Thoughts? I can help put together some better examples, if that helps.

[annevk]

That probably makes sense. We should do it in terms of "response's credentials mode" (which withCredentials maps to).

[tyoshino]

Agreed. It's not so easy to infer CORS principles and howtos from the spec text.

We have exhaustive tests for Chromium at e.g. https://code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/LayoutTests/http/tests/fetch/script-tests/thorough/cors-preflight.js which might be useful for writing examples.

IIRC, there was an open bug to draft a text to explain what "credentials" are. I couldn't find it now.

[annevk]

@tyoshino I think you might be thinking about a bug that wanted to explain how HTTP authentication interacted with it, which I recently resolved since that got sorted out and defined. But there's no good introductory explanation and I agree we should have one. Now most bits are in place on the implementation side I guess there's nothing much stopping this other than bandwidth.

[tyoshino]

I think you might be thinking about a bug that wanted to explain how HTTP authentication interacted with it, ...

I just remembered. It's https://www.w3.org/Bugs/Public/show_bug.cgi?id=26556.