[fetch] Provide more information in the spec on how withCredentials and Access-Control-Allow-Credentials interact (#264)

@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](https://lists.w3.org/Archives/Public/www-tag/2016Feb/0007.html) 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](https://www.w3.org/TR/cors/#resource-sharing-check), 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.

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/issues/264