Authoritative guide to CORS (Cross-Origin Resource Sharing) for REST APIs
An in-depth guide to Cross-Origin Resource Sharing (CORS) for REST APIs, on how CORS works, and common pitfalls especially around security.
What is CORS?
CORS is a security mechanism that allows a web page from one domain or Origin to access a resource with a different domain (a cross-domain request). CORS is a relaxation of the same-origin policy implemented in modern browsers. Without features like CORS, websites are restricted to accessing resources from the same origin through what is known as same-origin policy.
Monitor and Analyze API Traffic with Moesif
14 day free trial. No credit card required.
Try for Free
Why does same-origin exist?
You, like many websites, may use cookies to keep track of authentication or session info. Those cookies are bounded to a certain domain when they are created. On every HTTP call to that domain, the browser will attach the cookies that were created for that domain. This is on every HTTP call, which could be for static images, HTML pages, or even AJAX calls.
This means when you log into https://examplebank.com, a cookie is stored for https://examplebank.com. If that bank is a single-page React app, they may have created a REST API at https://examplebank.com/api for the SPA to communicate via AJAX.
The cross-domain vulnerability
Let’s say you browse to a malicious website https://evilunicorns.com while logged into https://examplebank.com. Without same-origin policy, that hacker website could make authenticated malicious AJAX calls to https://examplebank.com/api to POST /withdraw even though the hacker website doesn’t have direct access to the bank’s cookies.
This is due to the browser behavior of automatically attaching any cookies bounded to https://examplebank.com for any HTTP calls to that domain, including AJAX calls from https://evilunicorns.com to https://examplebank.com. By restricting HTTP calls to only ones to the same origin (i.e. the browser tab’s domain), same-origin policy closes some hacker backdoors such as around Cross-Site Request Forgery (CSRF) (Although not all. Mechanisms like CSRF tokens are still necessary).
How is Origin defined?
Origin includes the combination of protocol, domain, and port. This means https://api.mydomain.com and https://mydomain.com are actually different origins and thus impacted by same-origin policy. In a similar way, http://localhost:9000 and http://localhost:8080 are also different origins. The path or query parameters are ignored when considering the origin.
Origin refers to the content who initiated the request which is usually the open browser tab, but could also be the origin of an iFrame window.
Why was CORS created?
There are legitimate reasons for a website to make cross-origin HTTP requests. Maybe a single-page app at https://mydomain.com needs to make AJAX calls to https://api.mydomain.com; or maybe https://mydomain.com incorporates some 3rd party fonts or analytics providers like Google Analytics or MixPanel.
Cross-Origin Resource Sharing (CORS) enables these cross-domain requests.
How CORS works?
There are two types of CORS requests, simple requests and preflighted requests. The rules on whether a request is preflighted are discussed later.
I. Simple requests
A simple request is a CORS request that doesn’t require a preflight request (preliminary checks) before being initiated.
-
A browser tab open to
https://www.mydomain.cominitiates AJAX requestGET https://api.mydomain.com/widgets -
Along with adding headers like
Host, the browser automatically adds theOriginRequest Header for cross-origin requests:
GET /widgets/ HTTP/1.1
Host: api.mydomain.com
Origin: https://www.mydomain.com
[Rest of request...]
- The server checks the
Originrequest header. If the Origin value is allowed, it sets theAccess-Control-Allow-Originto the value in the request headerOrigin.
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://www.mydomain.com
Content-Type: application/json
[Rest of response...]
- When the browser receives the response, the browser checks the
Access-Control-Allow-Originheader to see if it matches the origin of the tab. If not, the response is blocked. The check passes such as in this example if either theAccess-Control-Allow-Originmatches the single origin exactly or contains the wildcard * operator.
A server that responds Access-Control-Allow-Origin: * allows all origins which can be a large security risk.
Only use * if your application absolutely requires it such as creating an open/public API.
Intention
As you can see, the server has control over whether to allow the request or not depending on the origin of the request. The browser guarantees that the Origin request header is set reliably and accurately.
II. Preflighted requests
A preflighted request is the other type of CORS request. A preflighted request is a CORS request where the browser is required to send a preflight request (i.e. a preliminary probe) before sending the request being preflighted to ask the server permission if the original CORS request can proceed. This preflight request itself is an OPTIONS request to the same URL.
Since the original CORS request has a preflight request before it, we call the original CORS request preflighted.
Any CORS request has to be preflighted if:
- It uses methods other than GET, HEAD or POST. Also, if POST is used to send request data with a Content-Type other than application/x-www-form-urlencoded, multipart/form-data, or text/plain, e.g. if the POST request sends an XML payload to the server using application/xml or text/xml, then the request is preflighted.
- It sets custom headers in the request (e.g. the request uses a header such as X-PINGOTHER)
Source: Mozilla
Typical cases requiring preflighted requests:
-
A website makes an AJAX call to POST JSON data to a REST API meaning the
Content-Typeheader isapplication/json -
A website makes an AJAX call to an API which uses a token to authenticate the API in a request header such
Authorization
This means it can be common for a REST API powering a single-page app to have the majority of AJAX requests preflighted.
Example flow
- A browser tab open to
https://www.mydomain.cominitiates an authenticated AJAX requestPOST https://api.mydomain.com/widgetswith a JSON payload. The browser sends theOPTIONSrequest first (aka the preflight request) with the proposed Requested Method and Requested Headers of the main request:
OPTIONS /widgets/ HTTP/1.1
Host: api.mydomain.com
Origin: https://www.mydomain.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type
[Rest of request...]
- The server respond back specifying the allowed HTTP methods and headers. If the original CORS request intended to send a header or HTTP method not in the list, the browser will fail without attempting the CORS request.
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://www.mydomain.com
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Content-Type: application/json
[Rest of response...]
- Since the headers and method pass the check, the browser sends the original CORS request. Note the
Originheader is on this request also.
POST /widgets/ HTTP/1.1
Host: api.mydomain.com
Authorization: 1234567
Content-Type: application/json
Origin: https://www.mydomain.com
[Rest of request...]
- The response has the correct origin in
Access-Control-Allow-Originheader so checks pass and control is handed back to the browser tab.
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://www.mydomain.com
Content-Type: application/json
[Rest of response...]
Advanced Configuration
You already saw a few headers in the previous examples that are used for CORS such as Access-Control-Allow-Origin and Access-Control-Allow-Methods, but there are more headers for finer control. Below is the full list of headers that control CORS.
Request Headers
| Header Name | Example Value | Description | Used in preflight requests | Used in CORS requests |
|---|---|---|---|---|
| Origin | https://www.mydomain.com | Combination of protocol, domain, and port of the browser tab opened | YES | YES |
| Access-Control-Request-Method | POST | For the preflight request, specifies what method the original CORS request will use | YES | no |
| Access-Control-Request-Headers | Authorization, X-PING | For the preflight request, a comma separated list specifying what headers the original CORS request will send | YES | no |
Response Headers
| Header Name | Example Value | Description | Used in preflight requests | Used in CORS requests |
|---|---|---|---|---|
| Access-Control-Allow-Origin | https://www.mydomain.com | The allowed origins for this request as specified by the server. If it doesn’t match the Origin header and is not a *, browser will reject the request. If domain is specified, protocol component is required and can only be a single domain |
YES | YES |
| Access-Control-Allow-Credentials | true | CORS requests normally don’t include cookies to prevent CSRF attacks. When set to true, the request can be made with/will include credentials such as Cookies. The header should be omitted to imply false which means the CORS request will not be returned to the open tab. Cannot be used with wildcard |
YES | YES |
| Access-Control-Expose-Headers | Date, X-Device-Id | A whitelist of additional response headers to be exposed to the browser tab beyond the default headers | no | YES |
| Access-Control-Max-Age | 600 | Value in seconds to cache preflight request results (i.e the data in Access-Control-Allow-Headers and Access-Control-Allow-Methods headers). Firefox maximum is 24 hrs and Chromium maximum is 10 minutes. Higher will have no effect. |
YES | no |
| Access-Control-Allow-Methods | GET, POST, PUT, DELETE | Can be * to allow all methods. A comma separated whitelist of allowed methods that can be used for the CORS request. | YES | no |
| Access-Control-Allow-Headers | Authorization, X-PING | Can be * to allow any header. A comma-separated whitelist of allowed headers that can be used for the CORS request. | YES | no |
Wildcard (*) on Access-Control-Allowed-Headers, Access-Control-Allow-Methods, and Access-Control-Expose-Headers is not fully implemented in current browsers.
It is better to list out the headers or methods. See Chromium Bug
What is Moesif? Moesif is the most advanced API analytics and debugging platform used by Thousands of platformsto debug CORS issues quickly and understand how you’re customers are accessing your APIs. Moesif has open-sourced middleware and SDKs for the languages you love.
Common Pitfalls
1. Using * operator for Access-Control-Allow-Origin.
CORS is a relaxation of same-origin policy while attempting to remain secure. Using * disables most security rules of CORS. There are use cases where wildcard is OK such as an open API that integrates into many 3rd party websites.
You may improve security by having the API on a different domain.
For example, your open API https://api.mydomain.com could respond with Access-Control-Allow-Origin: * , but your main website’s API https://www.mydomain.com/api still responds with Access-Control-Allow-Origin: https://www.mydomain.com
2. Returning multiple domains for Access-Control-Allow-Origin.
Unfortunately, the spec does not allow Access-Control-Allow-Origin: https://mydomain.com, https://www.mydomain.com. The server can only respond with one domain or *, but you can leverage the Origin request header.
3. Using wildcard selection like *.mydomain.com.
This is not part of the CORS spec, wildcard can only be used to imply all domains are allowed.
4. Not including protocol or non-standard ports.
Access-Control-Allow-Origin: mydomain.com is not valid since the protocol is not included.
In a similar way, you will have trouble with Access-Control-Allow-Origin: http://localhost unless the server is actually running on a standard HTTP port like :80.
5. Not including Origin in the Vary response header
Most CORS frameworks do this automatically, you must specify to clients that server responses will differ based on the request origin.
6. Not specifying the Access-Control-Expose-Headers
If a required header is not included, the CORS request will still pass, but response headers not whitelisted will be hidden from the browser tab. The default response headers always exposed for CORS requests are:
- Cache-Control
- Content-Language
- Content-Type
- Expires
- Last-Modified
- Pragma
7. Using wildcard when Access-Control-Allow-Credentials is set to true
This is a tricky case that catches many people. If response has Access-Control-Allow-Credentials: true,
then the wildcard operator cannot be used on any of the response headers like
Access-Control-Allow-Origin.
Performance
An article on mitigating the performance penalties of CORS will be posted shortly.
Monitor and Analyze API Traffic with Moesif
14 day free trial. No credit card required.
Try for Free
Related Articles
API Development
Step-by-Step Blueprint to Create RESTful APIs for Efficient Web Services
Learn from server setup to securing data, ensuring your APIs are scalable and efficient.Dive into the details for a comprehensive understanding of designing,...
API Development
The AI API Gold Rush: How to Turn Your Models into Revenue With Moesif
Monetize your AI model by transforming it into an AI API, creating new revenue streams by integrating your AI capabilities into other applications. This guid...
API Development
Securing Access: A Guide to Implementing API Keys in AWS API Gateway
Discover how to generate, apply, and manage API keys in AWS API Gateway, ensuring effective authentication and robust access control for your services. Gain ...
API Development
Mastering API Gateway Auth: Proven Methods for Secure Connectivity
Secure your API gateway and protect your digital assets. Let’s cover essential authentication methods, challenges, and best practices for API gateway security.
