When your frontend application calls APIs hosted on a different origin, browsers block the request by default. Cross-origin resource sharing (CORS) lets you control which origins, methods, and headers are permitted in these cross-origin requests.
Cloud-native gateways in Microservices Engine (MSE) support route-level CORS policies. Attach a CORS policy to a route to define which cross-origin requests your backend accepts.
How CORS works
A cross-origin request occurs when a web page requests a resource from a different domain, subdomain, port, or protocol. For example, a page on https://app.example.com calling https://api.example.com is a cross-origin request.
When a browser sends a cross-origin request, it includes an Origin header that identifies the requesting domain. The gateway checks this header against your CORS policy and responds with the appropriate Access-Control-* headers.
For simple requests (basic GET or POST with standard headers), the browser sends the request directly and checks the CORS headers in the response. Non-simple requests --- such as those using PUT or DELETE, or those that include custom headers --- trigger a preflight OPTIONS request first. The browser only sends the actual request after the preflight confirms that the origin, method, and headers are allowed.
Allowed origin (request succeeds):
GET /api/items HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.comUnrecognized origin (browser blocks the response):
GET /api/items HTTP/1.1
Host: api.example.com
Origin: https://unknown-site.com
HTTP/1.1 200 OK
# No Access-Control-Allow-Origin header -- browser blocks this responsePrerequisites
Before you begin, make sure that you have:
An MSE cloud-native gateway with at least one route configured
An actual backend service bound to the route (CORS policies do not take effect on mock services)
Configure a CORS policy
Log on to the MSE console. In the top navigation bar, select a region.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. On the Gateways page, click the name of the gateway.
In the left-side navigation pane, click Routes, and then click the Routes tab.
Find the route that you want to configure and click Policies in the Actions column.
On the Policies tab, click CORS.
Configure the following parameters and click Save.
| Parameter | Maps to HTTP header | Description |
|---|---|---|
| Allowed Origins | Access-Control-Allow-Origin | Origins permitted to access your backend through a browser. Enter * to allow all origins. To match subdomains, use a wildcard pattern such as *.example.com. To specify multiple origins, enter each origin on a separate line. Each origin must start with http:// or https://. If the Origin header in a request matches an entry in this list, the gateway returns that origin in the Access-Control-Allow-Origin response header. |
| Allowed Methods | Access-Control-Allow-Methods | HTTP methods permitted in CORS requests. Valid values: GET, POST, PUT, DELETE, HEAD, OPTIONS, and PATCH. |
| Allowed Request Headers | Access-Control-Allow-Headers | Request headers permitted beyond the browser's built-in headers. Enter * to allow all headers. To specify multiple headers, enter each header on a separate line. |
| Allowed Response Headers | Access-Control-Expose-Headers | Response headers that browsers and JavaScript can access. Enter * to expose all headers. To specify multiple headers, enter each header on a separate line. |
| Allow to Carry Credentials | Access-Control-Allow-Credentials | Whether to include credentials (cookies, authorization headers, or TLS client certificates) in CORS requests. See the Wildcard origin with credentials section under Common issues for an important restriction. |
| Precheck Expiration Time | Access-Control-Max-Age | Maximum duration (in seconds) that the browser caches preflight OPTIONS responses. A longer cache period reduces the number of preflight requests. |
| Enable | N/A | Turn the CORS policy on or off. When enabled, cross-origin requests are evaluated against this policy. When disabled, all cross-origin requests to this route are rejected. |
Verify the CORS policy
After you save the policy, send a preflight OPTIONS request to your route endpoint and check the CORS headers in the response.
curl -I \
-H "Origin: http://example.com" \
-H "Host: www.test.com" \
-X OPTIONS \
http://<gateway-ip>/demo/item/listReplace <gateway-ip> with the IP address of your cloud-native gateway.
A successful response includes CORS headers that match your policy configuration:
HTTP/1.1 200 OK
access-control-allow-origin: http://example.com
access-control-allow-credentials: true
access-control-expose-headers: *
server: istio-envoyIf the access-control-allow-origin header is missing or does not match the Origin value in your request, review your Allowed Origins configuration.
Common issues
Wildcard origin with credentials
Do not set Allowed Origins to * and enable Allow to Carry Credentials at the same time. The CORS specification prohibits using a wildcard origin with credentials. Browsers reject responses that include both Access-Control-Allow-Origin: * and Access-Control-Allow-Credentials: true.
To allow credentials from multiple origins, list each origin individually instead of using a wildcard.
CORS policy does not take effect
The CORS policy does not take effect on mock services. Make sure an actual backend service is bound to the route.
If the policy still does not take effect after binding a backend service, verify the following:
The Enable toggle is turned on for the CORS policy.
The origin in the request matches one of the entries in Allowed Origins.
The HTTP method matches one of the entries in Allowed Methods.
Preflight request fails
If the browser sends a preflight OPTIONS request and receives an error, check the following:
The Allowed Methods list includes OPTIONS.
The Allowed Request Headers list includes all custom headers that the client sends.