Core Concepts

​Custom CORS policies

There are two built-in CORS policies called none and anything-goes. The former disallows any cross-origin access while the latter allows any cross-origin access (and is discouraged for production use cases). To correctly support CORS we recommend creating and using a custom CORS policy.

​CORS Policy

Custom CORS policies are created in the policies.json file alongside regular policies:

{
  "policies": [], //...
  "corsPolicies": [] // custom CORS policies go here
}
json

A CORS policy consists of a name and set of CORS headers to be returned for cross-origin requests (both the simple type and pre-flight request).

{
  //... rest of policies.json file
  "corsPolicies": [
    {
      "name": "custom-cors",
      "allowedOrigins": "https://domain1.com, https://domain2.com",
      "allowedHeaders": "origin, my-special-incoming-header",
      "allowedMethods": ["GET", "POST"],
      "exposeHeaders": "my-special-response-header",
      "maxAge": 600,
      "allowCredentials": true
    }
  ]
}
json

You can then reference your custom CORS policy in your route by specifying the name of your CORS policy on your route, (or choosing it in the route designer UI).

"paths": {
  "/redirect-test": {
    "get": {
      "x-zuplo-route": {
        "corsPolicy": "custom-cors",
        "handler": {
          "module": "$import(@zuplo/runtime)",
          "export": "redirectHandler",
          "options": {
            "location": "/docs"
          }
        }
      },
      ...
    }
  }
}
json

For more information on CORS, check out the MDN documentation: Cross-Origin Resource Sharing (CORS)

​Using environment variables

If you need to support different origins, headers, etc. in different environments, you can use environment variables

{
  //... rest of policies.json file
  "corsPolicies": [
    {
      "name": "custom-cors",
      "allowedOrigins": "$env(ALLOWED_ORIGINS)", // "https://domain1.com, https://domain2.com",
      "allowedHeaders": "$env(ALLOWED_HEADERS)", // "origin, my-special-incoming-header",
      "allowedMethods": ["GET", "POST"],
      "exposeHeaders": "my-special-response-header",
      "maxAge": 600,
      "allowCredentials": true
    }
  ]
}
json

---