CORS explained: why your browser blocks API calls, and what not to do about it
Understand why browsers block some cross-origin API calls and why CORS is not a substitute for authentication or authorization.
"Blocked by CORS policy" is a common error when a web front end calls an API on another domain. MDN's CORS guide (https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) explains the mechanism.
What it is
CORS (Cross-Origin Resource Sharing) is, per MDN, an HTTP-header based mechanism that lets a server say which origins other than its own a browser may load resources from. An origin is the combination of domain, scheme and port. For security reasons, browsers restrict cross-origin requests started by scripts: with fetch() or XMLHttpRequest, a page can only read responses from its own origin unless the other server's response includes the right CORS headers.
Example from MDN: JavaScript on https://domain-a.com calls fetch() for https://domain-b.com/data.json. The browser only exposes the response if domain-b allows it.
Two kinds of request
- Simple requests need no preflight. MDN explains that these are requests an old HTML form could already send to any origin, so servers must already guard against cross-site request forgery. The server still must opt in with Access-Control-Allow-Origin before the script can read the response.
- Preflighted requests: requests outside the safelisted method/header/content-type conditions trigger an OPTIONS preflight before the actual request. GET can also require preflight, for example with a non-safelisted request header. Preflight is not classified by whether the application changes data; simple POST requests can change data without one.
Cookies and credentials
By default, cross-origin fetch() calls do not send credentials such as cookies. To include them you set credentials to "include" (or withCredentials for XMLHttpRequest). MDN says the browser then rejects any response that lacks Access-Control-Allow-Credentials: true, and that for credentialed requests the server must name a specific origin in Access-Control-Allow-Origin instead of the * wildcard.
What this means in practice
- CORS is enforced by browsers. It is a rule about whether scripts in a browser may read a response; we did not research its relation to other types of clients, so do not treat it as an API access-control system. Your API still needs its own authentication.
- Allow the specific origins you trust. Our reading of MDN's credentialed-request rule is that a wildcard is not accepted when cookies are involved.
- A missing header is usually a server configuration issue, not a front-end bug: ask who controls the API's response headers.
Checklist for your developer
- Which origins call our API, and are they listed explicitly?
- Do we use cookies cross-origin? If so, are credentials and the allowed origin configured correctly?
- Do we handle the OPTIONS preflight for methods like PUT and DELETE?
- Do authentication and authorization checks happen on the server regardless of CORS?
The checklist is ours, based on the guide.
Limits
We did not read the sections on individual response headers (Max-Age, Expose-Headers) in detail.
By Omnistu.