286

I'm trying to understand how to use CORS and am confused about what the Access-Control-Allow-Credentials header does.

The documentation says

Indicates whether or not the response to the request can be exposed when the credentials flag is true.

But I don't understand what the response being "exposed" means.

Can anyone explain what this header being set to true (in conjunction with the credentials flag being set to true) actually does?

Improve this question
2
  • xhr.withCredential doc on client side developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/…
    – Weishi Z
    Commented May 27, 2016 at 21:04
  • That doesn't talk about headers, but about xhr. If you use anything else, like Blazor WebAssembly, you gain nothing from that description. I still don't know if Access-Control-Allow-Credentials is identical to credentials: include or how to set it in Blazor wasm.
    – Jens Mander
    Commented Jul 20, 2021 at 19:32

1 Answer 1

Reset to default
436

By default, CORS does not include cookies on cross-origin requests. This is different from other cross-origin techniques such as JSON-P. JSON-P always includes cookies with the request, and this behavior can lead to a class of vulnerabilities called cross-site request forgery, or CSRF.

In order to reduce the chance of CSRF vulnerabilities in CORS, CORS requires both the server and the client to acknowledge that it is ok to include cookies on requests. Doing this makes cookies an active decision, rather than something that happens passively without any control.

The client code must set the withCredentials property on the XMLHttpRequest to true in order to give permission.

However, this header alone is not enough. The server must respond with the Access-Control-Allow-Credentials header. Responding with this header to true means that the server allows cookies (or other user credentials) to be included on cross-origin requests.

You also need to make sure your browser isn't blocking third-party cookies if you want cross-origin credentialed requests to work.

Note that regardless of whether you are making same-origin or cross-origin requests, you need to protect your site from CSRF (especially if your request includes cookies).

Improve this answer
23
  • 54
    Just want to add to this a little bit to comment on the meaning of "exposed." The spec doesn't require a pre-flight (additional roundtrip to check if the server will allow credentials) for GET requests. Instead of preflighting, the browser will just always make the request, sending cookies if withCredentials is set, but then when it receives the response, if withCredentials was set, it will only deliver/expose the result to the calling javascript if the response has the Access-Control-Allow-Credentials header set. If no header, it doesn't expose the response, effectively black-holing it.
    – heavi5ide
    Commented May 13, 2015 at 20:25
  • 6
    @heavi5ide, Yea, even if the browser doesn't expose the response to the client code, the request-with-cookie was still sent (for non-preflighted requests). So CSRF would still be done.
    – Pacerier
    Commented Jan 26, 2016 at 6:36
  • 11
    Since this is such a popular answer, I'm going to add one more important piece of information: in addition to configuring your request and response headers correctly, you also need to make sure your browser isn't blocking third-party cookies if you want cross-origin credentialed requests to work. See stackoverflow.com/a/16634887/2970321
    – alexw
    Commented Feb 18, 2016 at 15:49
  • 14
    This is such a clear answer that anyone reading it the first time can understand and fix their code that doesn't seem to be working well with cookies. Thanks!
    – asgs
    Commented Jun 21, 2016 at 18:06
  • 3
    Applies this to Authorization headers?
    – alvaropgl
    Commented Feb 11, 2021 at 8:18

Not the answer you're looking for? Browse other questions tagged or ask your own question.