|
| 1 | +--- |
| 2 | +title: "Configuring CORS in the Mendix Runtime" |
| 3 | +linktitle: "Configuring CORS" |
| 4 | +url: /refguide/configure-cors/ |
| 5 | +description: "Describes how to enable Cross-Origin Resource Sharing (CORS) in the Mendix Runtime, allowing browser-based clients on other domains to access the runtime." |
| 6 | +--- |
| 7 | + |
| 8 | +## Introduction |
| 9 | + |
| 10 | +Cross-Origin Resource Sharing (CORS) is a mechanism that allows a web application running on one domain to make requests to a server on a different domain. By default, browsers block such cross-origin requests for security reasons. If your Mendix front end is hosted on a different domain than the Mendix Runtime (for example, when using a separate single-page application or a microfrontend architecture), you need to configure CORS so the browser permits these requests. |
| 11 | + |
| 12 | +This document describes the custom runtime settings required to enable CORS in the Mendix Runtime. |
| 13 | + |
| 14 | +## Settings to Configure {#settings} |
| 15 | + |
| 16 | +To enable CORS, configure the following custom runtime settings: |
| 17 | + |
| 18 | +### Runtime Settings |
| 19 | + |
| 20 | +| Name | Value | Description | |
| 21 | +| --- | --- | --- | |
| 22 | +| `com.mendix.core.SameSiteCookies` | `None` | Allows cookie sharing between the runtime origin and the client origin. This is required for cross-origin authentication to work correctly. | |
| 23 | +| `Client.EnableCors` | `true` | When enabled, the runtime responds to CORS preflight (`OPTIONS`) requests from the browser. | |
| 24 | + |
| 25 | +### Custom HTTP Response Headers |
| 26 | + |
| 27 | +In addition to the runtime settings above, you need to set the following custom HTTP response headers via the `Headers` setting: |
| 28 | + |
| 29 | +| Header | Value | Description | |
| 30 | +| --- | --- | --- | |
| 31 | +| `Access-Control-Allow-Credentials` | `true` | Indicates that the server allows credentials (cookies, authorization headers) to be included in cross-origin requests. | |
| 32 | +| `Access-Control-Allow-Headers` | `Content-Type, x-csrf-token` | Specifies which HTTP headers can be used in the actual request. Expand this list if your application uses additional custom headers. | |
| 33 | +| `Access-Control-Allow-Methods` | `POST, GET, OPTIONS` | Specifies the HTTP methods allowed when accessing the resource. Expand this list if your application uses additional methods (for example, `PUT` or `DELETE`). | |
| 34 | +| `Access-Control-Allow-Origin` | Your client domain (for example, `https://my-app.example.com`) | The origin from which the client application is served. This must match the exact domain, including the scheme and port. | |
| 35 | +| `Access-Control-Request-Method` | `*` | Indicates which methods are supported by the resource in response to a preflight request. | |
| 36 | + |
| 37 | +{{% alert color="info" %}} |
| 38 | +If you change these settings, you need to restart your app to apply the changes. |
| 39 | +{{% /alert %}} |
| 40 | + |
| 41 | +## Example `m2ee.yaml` Configuration {#example} |
| 42 | + |
| 43 | +The following example shows how to configure CORS in an `m2ee.yaml` file. Replace `YOUR_ORIGIN` with the actual domain of your client application (for example, `https://my-app.example.com`): |
| 44 | + |
| 45 | +```yaml |
| 46 | +mxruntime: |
| 47 | + com.mendix.core.SameSiteCookies: None |
| 48 | + Client.EnableCors: true |
| 49 | + Headers: |
| 50 | + "Access-Control-Allow-Credentials": "true" |
| 51 | + "Access-Control-Allow-Headers": "Content-Type, x-csrf-token" |
| 52 | + "Access-Control-Allow-Methods": "POST, GET, OPTIONS" |
| 53 | + "Access-Control-Allow-Origin": YOUR_ORIGIN |
| 54 | + "Access-Control-Request-Method": "*" |
| 55 | +``` |
| 56 | +
|
| 57 | +## Troubleshooting |
| 58 | +
|
| 59 | +If CORS is not working as expected, check the following: |
| 60 | +
|
| 61 | +* **Browser console errors** — Look for CORS-related error messages in the browser developer tools console. These typically indicate which header is missing or misconfigured. |
| 62 | +* **Origin mismatch** — Ensure the value of `Access-Control-Allow-Origin` exactly matches the origin shown in the browser error, including the scheme (`https://`) and port number (if applicable). |
| 63 | +* **Missing `SameSiteCookies` setting** — Without `com.mendix.core.SameSiteCookies` set to `None`, cookies will not be sent on cross-origin requests, which can cause authentication failures. |
| 64 | +* **HTTPS requirement** — When `SameSiteCookies` is set to `None`, the `Secure` attribute is automatically added to cookies, meaning both the runtime and the client must be served over HTTPS. |
0 commit comments