---
schema_version: "1"
id: 88372047498191adf6414d4cf33dddbaa1a70b7edd100e2470913bca43546eb8
title: Cross-Origin Resource Sharing (CORS) Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-cors.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-cors
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 68bf7fa1c41b22977ada6d17963ab69f6edb59729bf1d6cbe56af1362c1dd9dc
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: cross origin resource sharing, cors, api gateway, flex gateway, gateway, policy
---

# Cross-Origin Resource Sharing (CORS) Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Cross-Origin Resource Sharing (CORS)</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Enables access to resources residing in external domains</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Compliance</p></div></div></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><div><div><p>v1.0.0</p></div></div></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><div><div><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/cors-release-notes">Cross-Origin Resource Sharing (CORS)</a></p></div></div></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><div><div><p>No return codes exist for this policy</p></div></div></td></tr></tbody></table>

## Summary

CORS is a mechanism by which a web application can access resources that are defined in another
domain. Browsers implement this standard by default. The CORS policy complies with the
[CORS W3C recommendation](https://fetch.spec.whatwg.org/) standards.

## Configuring Policy Parameters

### Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy
definition and table of parameters:

\- policyRef: name: cors-flex config: originGroups: <array> // OPTIONAL, default: \[\] - origins:
accessControlMaxAge: allowedMethods: methodName: - isAllowed: headers: <array> // OPTIONAL, default:
\[\] exposedHeaders: <array> // OPTIONAL, default: \[\] publicResource: <bool> // OPTIONAL, default:
true supportCredentials: <bool> // OPTIONAL, default: false

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>originGroups</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List containing groups of origins</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>List of origins to be included in the group. For example, <code>http://www.the-origin-of-time.com</code></p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.accessControlMaxAge</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>30</p></div></div></td><td><div><div><p>Duration in seconds that a preflight response can be cached without sending another preflight request</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>CONNECT, DELETE, GET, OPTIONS, PATCH, POST, PUT, TRACE</p></div></div></td><td><div><div><p>Allowed HTTP methods</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Method name</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.allowedMethods.methodName.isAllowed</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>A boolean indicating if a method is allowed</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.headers</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>HTTP headers used for preflight requests</p></div></div></td></tr><tr><td><div><div><p><code>originGroups.origins.exposedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>Empty array</p></div></div></td><td><div><div><p>Headers that browser JavaScript is allowed to access</p></div></div></td></tr><tr><td><div><div><p><code>publicResource</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>true</code></p></div></div></td><td><div><div><p>A boolean indicating if the CORS configuration is to be applied as a public resource</p></div></div></td></tr><tr><td><div><div><p><code>supportCredentials</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>A boolean indicating if the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td></tr></tbody></table>

#### Resource Configuration Example

\- policyRef: name: cors-flex config: publicResource: false supportCredentials: true originGroups: -
origins: - http://www.the-origin-of-time.com accessControlMaxAge: 30 allowedMethods: - isAllowed:
true methodName: POST - isAllowed: true methodName: PUT - isAllowed: true methodName: GET -
isAllowed: false methodName: CONNECT - isAllowed: false methodName: DELETE - isAllowed: false
methodName: OPTIONS - isAllowed: false methodName: PATCH - isAllowed: false methodName: TRACE
headers: - x-allow-origin - x-yet-another-valid-header exposedHeaders: - x-forwarded-for

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><div><div><p>Public resource</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied as a public resource (default)</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Default group</p></div></div></td><td><div><div><p>Whether the CORS configuration is to be applied only to specific resources (requires unselecting <strong>Public resource</strong>)</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Support credentials</p></div></div></td><td><div><div><p>Whether the policy supports credentials, such as cookies, authorization headers, and TLS client certificates</p></div></div></td><td><div><div><p>No</p></div></div></td></tr></tbody></table>

## Why CORS

CORS enables you to achieve web page security and web integrity in your environment. To know why you
might need to apply the CORS policy to your backend, you must first understand _origins_, _cookies_,
and how they can be manipulated to violate web page integrity.

### Introduction to the Web Origin Concept

Origin is a header that specifies the request that initiated the fetch. The origin header includes
only the server name (no path information). At a very basic level, an origin consists of:

- URI scheme: `http://`

- Host name: `www.example.com`

- Port number: `8080`

For requests between any two [origin](#origins) to be approved, the origins must be equal. Origins
are considered equal only if all these three parameters match. For more information, see
[RFC 6454 - The Web Origin Concept](https://tools.ietf.org/html/rfc6454).

### HTTP Cookies

Websites use HTTP cookies to retain stateful information. Most commonly, web servers use
authentication cookies to know whether a user is logged in, and to know which account users are
logged in to. For more information, see [RFC 6265](https://www.ietf.org/rfc/rfc6265.txt).

SOP (same-origin policy) deters malicious attackers from exploiting cookies when one web page
invokes another. For example, you might log in to your bank’s web page using a cookie that an
attacker might be able to obtain and exploit to query the bank’s API on your behalf.

With the SOP, scripts can access data from a target web page only if it has the same origin as the
caller web page. For more information about origins, see
[Wikipedia](https://en.wikipedia.org/wiki/Same-origin_policy#Origin_determination_rules).

Because the SOP is highly restrictive, access from one suborigin to another or to external
hyperlinks do not work on web pages. For example, if an origin `www.testapply.com` has two
suborigins, `www.eng.testapply.com` and `www.docs.testapply.com`, communication between the two
suborigins is denied. Additionally, any hyperlinks to external websites from any of the suborigins
is also denied.

To circumvent this problem, web browsers implemented the CORS standard, which validates the web
server and accepts the request if the validation is successful.

For example, if your bank implements the CORS server-side protocol on its login server, you can
query data only directly from the bank’s web page. Any attempt to query the login API from an
external (non-bank) domain is denied.

## How CORS Works

When your web pages request data, the browser detects whether the request is from within same origin
and determines whether to apply the CORS algorithm. If you query data from a web page that is not in
your origin, then the CORS policy is applied.

The CORS algorithm works on the web server and on the client-side for the web page that requested
the information. The client-side algorithm in the CORS policy is implemented by:

- Determining whether the request is complex (and potentially dangerous) and sending a preliminary
  _preflight_ request to verify whether the server accepts the origin.

- Executing the actual request and validating that the server responds correctly and accepts the
  origin.

A _preflight_ is a preliminary request (using OPTIONS as the HTTP method) from the web browser to
the backend server to test the identity (origin and a few other headers) of the web page that is
trying to perform the request.

If the backend does not accept the origin, the backend server responds to the request without a
specific header (Access-Control-Allow-Origin). The client then understands that the page’s origin is
not allowed in that server and does not execute the actual request.

The following diagram shows the XMLHttpRequest (XHR) in a JavaScript flow for determining whether to
execute the actual request:

![A flowchart illustrating the process of standard latency and added latency for Javascript cross-domain XHR calls](/mulesoft/current/en-us/gateway/1.13/_images/cors-policy-xhr-diagram.png)

As illustrated in the diagram, the request is validated based on the communication between the
browser and the server:

- If the request is considered to be complex (see the previous client-side diagram for XHR), then a
  preflight request is executed.

  If the server does not return the proper CORS response headers for the preflight, the client
  library (XHR in the previous example) is not allowed to perform the actual request.

- If the preflight response is correct and complete, then the client library executes the actual
  request, which includes certain CORS headers.

  The client library then validates the CORS headers of the response. If some of the required
  headers are missing, then again the client library is obliged to block the response from reaching
  the client, which is usually a web page.

## CORS Components

You can configure various components of the CORS policy, such as request headers, response headers,
public resources and groups, ordering, and wildcards.

### CORS Request Headers

- Origin: The origin making the cross origin request.

- Access-Control-Request-Method: The method that is invoked in the actual request.

  This header is sent in the preflight request.

- Access-Control-Request-Headers: Custom headers that are sent in the actual request.

  This header is sent in the preflight request. For the GET or HEAD methods, the standard defines a
  specific list of headers that are considered simple enough to not require a preflight. For custom
  headers, a preflight is executed for GET and HEAD requests (see the previous XHR example to
  validate the path in which the client does not have to perform a preflight).

### CORS Response Headers

The headers included in a response depend on whether the request is a preflight or an actual
request:

- `Access-Control-Allow-Origin`: Obligatory in every response.

  If this header is not present in the response, the browser or client library blocks the response
  from reaching the web page. The wildcard “\*” can be used to represent any origin.

- `Access-Control-Allow-Methods`: Allowed methods that can be executed.

  This header is returned in the OPTIONS request (preflight). The server might respond with a list
  of allowed methods, delegating the validation task to the client.

- `Access-Control-Allow-Headers`: Allowed headers in the actual request.

  This header works in a manner similar to how Access-Control-Allow-Methods works .

- `Access-Control-Allow-Credentials`: Notifies the client whether the actual request can be made
  with a cookie.

  The `Access-Control-Allow-Credentials` returns a Boolean value.

- `Access-Control-Expose-Headers`: Provides the browser or client library with a list of headers
  that can be accessed by the web page that executed the request.

  The HTTP library performing the CORS request exposes only the headers to the web page, providing
  further privacy and security.

- `Access-Control-Max-Age`: Specifies the duration (in seconds) in which the browser can avoid
  performing a second preflight on a request.

### Public Resources and Groups

If you need to bypass the browser SOP, Mulesoft provides you an option to configure a public
resource that enables the API gateway policy to mirror the preflight data in the response. This
ensures that the actual request is correctly updated with all the CORS headers so that the browser
accepts the response.

If the public resource option is not secure enough for your environment, define multiple groups for
the different origins that query your API. Each group applies to a list of origins and can specify
different methods, headers, preflight caching time, and expose headers.

### Ordering

The CORS policy is always applied first by the API gateway, before any other policies can be
applied. If a protected request using OPTIONS is sent to an application that has the CORS policy
applied, the request does not reach the protected resource. According to the
[CORS specification](https://fetch.spec.whatwg.org/#resource-preflight-requests), all OPTIONS
requests are considered preflight.

### Configuration Wildcards

Wildcards (`*`) are accepted in the Origins and Headers sections of a group configuration. Use
wildcards when you need a public resource, but must restrict the accepted HTTP methods.

If you have configured multiple groups and one of the groups uses a wildcard origin, the
non-wildcard settings override the wildcard configurations.

## FAQs

**The CORS policy does not seem to be applied.**

If you use tools such as curl or Postman to test the CORS policy for a complex request, the CORS
request headers are not added and the preflight does not occur.

If no CORS headers are sent or improper headers are used in the request, the API gateway CORS policy
does not add any CORS response headers, giving the impression that the policy is not applied. Ensure
that you use the libraries that implement the CORS protocol specific to your environment, or review
the specification to ensure that you are configuring the correct headers.