---
title: CORS Support
description: Enable and configure CORS headers in MockServer for control-plane and mocked responses, with examples for permissive and restrictive policies.
layout: page
pageOrder: 3
section: 'Security'
subsection: true
sitemap:
  priority: 0.7
  changefreq: 'monthly'
  lastmod: 2019-11-10T08:00:00+01:00
---

<p>MockServer and the proxy has support for CORS.  By default, CORS support is not enabled for the Control Plane API and or for mocked response, such as, when expectations are matched, or proxied requests.</p>

<p>When CORS support is enabled, and the <code class="inline code">corsAllowMethods</code> / <code class="inline code">corsAllowHeaders</code> / <code class="inline code">corsAllowOrigin</code> properties are left at their defaults (blank), MockServer emits sensible defaults so the Control Plane API and dashboard are usable cross-origin out of the box:</p>

<pre class="prettyprint code"><code class="code">Access-Control-Allow-Origin: &lt;request Origin&gt;   # the requesting Origin is reflected; "*" when there is no Origin
Access-Control-Allow-Methods: "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"
Access-Control-Allow-Headers: "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"
Access-Control-Expose-Headers: "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"
Access-Control-Allow-Credentials: "false"
Access-Control-Max-Age: "0"</code></pre>

<p style="color: darkred"><strong>NOTE:</strong> by default the requesting <code class="inline code">Origin</code> is reflected, so cross-site requests are allowed out of the box. Set an explicit <code class="inline code">corsAllowOrigin</code> (for example an allow-list) to restrict which origins are permitted.</p>

<p>To reduce the security risk from cross-site requests, CORS headers should be configured to the minimum required values for your use case, using the CORS <a href="#cors_configuration">configuration properties</a>, as below.</p>

<p>A more permission approach that enables most use cases would configure the CORS headers, as follows:</p>

<pre class="prettyprint code"><code class="code">Access-Control-Allow-Origin: "*"
Access-Control-Allow-Methods: "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"
Access-Control-Allow-Headers: "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"
Access-Control-Expose-Headers: "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"
Access-Control-Max-Age: "300"</code></pre>

<p>For example to enable a more permission approach for cross-site requests use <strong>ConfigurationProperties</strong> class as follows:</p>

<pre class="prettyprint code"><code class="code">ConfigurationProperties.enableCORSForAllResponses(true);
ConfigurationProperties.corsAllowOrigin("*");
ConfigurationProperties.corsAllowMethods("CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
ConfigurationProperties.corsAllowHeaders("Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
ConfigurationProperties.corsMaxAgeInSeconds(300);</code></pre>

{% include_subpage _includes/cors_configuration.html %}

<a id="cors_examples" class="anchor" href="#cors_examples">&nbsp;</a>

<h2>Examples:</h2>

<p>CORS is a server-startup configuration, so it is applied when MockServer starts rather than per-expectation. The examples below launch (or configure) the server with the same CORS settings in each language. The detailed <code class="inline code">corsAllow*</code> / <code class="inline code">corsMaxAgeInSeconds</code> values are read once at startup, so set them when the server is launched (the <a href="#cors_examples">REST API</a> tab can toggle the enable flag at runtime, but does not re-apply the detailed values).</p>
<button id="button_enabled_permissive_cors_for_all_response" class="accordion">enabled permissive CORS for all responses</button>
<div class="panel">
    <button class="accordion inner">Java</button>
    <div class="panel">
        <pre class="prettyprint lang-java code"><code class="code">ConfigurationProperties.enableCORSForAllResponses(true);
ConfigurationProperties.corsAllowMethods("CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
ConfigurationProperties.corsAllowHeaders("Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
ConfigurationProperties.corsAllowCredentials(true);
ConfigurationProperties.corsMaxAgeInSeconds(300);</code></pre>
    </div>
    <button class="accordion inner">JavaScript: mockserver-node</button>
    <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">var mockserver = require('mockserver-node');
mockserver.start_mockserver({
    serverPort: 1080,
    systemProperties: "-Dmockserver.enableCORSForAllResponses=true " +
        "-Dmockserver.corsAllowMethods=\"CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE\" " +
        "-Dmockserver.corsAllowHeaders=\"Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization\" " +
        "-Dmockserver.corsAllowCredentials=\"true\" " +
        "-Dmockserver.corsMaxAgeInSeconds=\"300\""
});</code></pre>
    </div>
    <button class="accordion inner">Python</button>
    <div class="panel">
        <pre class="prettyprint lang-python code"><code class="code">from mockserver import start_server

# the launcher passes these JVM system properties straight through to the server
server = start_server(port=1080, extra_args=[
    "-Dmockserver.enableCORSForAllResponses=true",
    "-Dmockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE",
    "-Dmockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization",
    "-Dmockserver.corsAllowCredentials=true",
    "-Dmockserver.corsMaxAgeInSeconds=300",
])</code></pre>
    </div>
    <button class="accordion inner">Ruby</button>
    <div class="panel">
        <pre class="prettyprint lang-ruby code"><code class="code">require 'mockserver-client'

# the launcher passes these JVM system properties straight through to the server
server = MockServer::BinaryLauncher.start(port: 1080, extra_args: [
    '-Dmockserver.enableCORSForAllResponses=true',
    '-Dmockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE',
    '-Dmockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization',
    '-Dmockserver.corsAllowCredentials=true',
    '-Dmockserver.corsMaxAgeInSeconds=300'
])</code></pre>
    </div>
    <button class="accordion inner">Go</button>
    <div class="panel">
        <pre class="prettyprint lang-go code"><code class="code">import (
    "os"

    mockserver "github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7"
)

// the launched server inherits these environment variables
os.Setenv("MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES", "true")
os.Setenv("MOCKSERVER_CORS_ALLOW_METHODS", "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE")
os.Setenv("MOCKSERVER_CORS_ALLOW_HEADERS", "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization")
os.Setenv("MOCKSERVER_CORS_ALLOW_CREDENTIALS", "true")
os.Setenv("MOCKSERVER_CORS_MAX_AGE_IN_SECONDS", "300")

server, _ := mockserver.StartServer(1080, "", nil)</code></pre>
    </div>
    <button class="accordion inner">.NET</button>
    <div class="panel">
        <pre class="prettyprint lang-csharp code"><code class="code">using System;
using MockServer.Client;

// the launched server inherits these environment variables
Environment.SetEnvironmentVariable("MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES", "true");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_ALLOW_METHODS", "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_ALLOW_HEADERS", "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_ALLOW_CREDENTIALS", "true");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_MAX_AGE_IN_SECONDS", "300");

var server = MockServerBinaryLauncher.Start(port: 1080);</code></pre>
    </div>
    <button class="accordion inner">Rust</button>
    <div class="panel">
        <pre class="prettyprint lang-rust code"><code class="code">use mockserver_client::launcher;

// the launched server inherits these environment variables
std::env::set_var("MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES", "true");
std::env::set_var("MOCKSERVER_CORS_ALLOW_METHODS", "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
std::env::set_var("MOCKSERVER_CORS_ALLOW_HEADERS", "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
std::env::set_var("MOCKSERVER_CORS_ALLOW_CREDENTIALS", "true");
std::env::set_var("MOCKSERVER_CORS_MAX_AGE_IN_SECONDS", "300");

let server = launcher::start(1080).unwrap();</code></pre>
    </div>
    <button class="accordion inner">PHP</button>
    <div class="panel">
        <pre class="prettyprint lang-php code"><code class="code">use MockServer\BinaryLauncher;

// the launcher passes these JVM system properties straight through to the server
$server = (new BinaryLauncher())-&gt;start(1080, [
    '-Dmockserver.enableCORSForAllResponses=true',
    '-Dmockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE',
    '-Dmockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization',
    '-Dmockserver.corsAllowCredentials=true',
    '-Dmockserver.corsMaxAgeInSeconds=300',
]);</code></pre>
    </div>
    <button class="accordion inner">REST API</button>
    <div class="panel">
        <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/configuration" -d '{
    "enableCORSForAllResponses": true,
    "corsAllowMethods": "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE",
    "corsAllowHeaders": "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization",
    "corsAllowCredentials": true,
    "corsMaxAgeInSeconds": 300
}'</code></pre>
        <p>The <code class="inline code">enableCORSForAllResponses</code> flag takes effect at runtime; the detailed <code class="inline code">corsAllow*</code> / <code class="inline code">corsMaxAgeInSeconds</code> values are only applied when the server starts, so set those at launch (see the other tabs).</p>
    </div>
    <button class="accordion inner">Command Line</button>
    <div class="panel">
        <pre class="prettyprint lang-bash code"><code class="code">java -Dmockserver.enableCORSForAllResponses=true \
-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE" \
-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization" \
-Dmockserver.corsAllowCredentials="true" \
-Dmockserver.corsMaxAgeInSeconds="300" \
-jar "~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar" -serverPort 1080</code></pre>
    </div>
</div>
<button id="button_enabled_permissive_cors_for_control_plane_api" class="accordion">enabled permissive CORS for control plane API</button>
<div class="panel">
    <button class="accordion inner">Java</button>
    <div class="panel">
        <pre class="prettyprint lang-java code"><code class="code">ConfigurationProperties.enableCORSForAPI(true);
ConfigurationProperties.corsAllowMethods("CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
ConfigurationProperties.corsAllowHeaders("Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
ConfigurationProperties.corsAllowCredentials(true);
ConfigurationProperties.corsMaxAgeInSeconds(300);</code></pre>
    </div>
    <button class="accordion inner">JavaScript: mockserver-node</button>
    <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">var mockserver = require('mockserver-node');
mockserver.start_mockserver({
    serverPort: 1080,
    systemProperties: "-Dmockserver.enableCORSForAPI=true " +
        "-Dmockserver.corsAllowMethods=\"CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE\" " +
        "-Dmockserver.corsAllowHeaders=\"Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization\" " +
        "-Dmockserver.corsAllowCredentials=\"true\" " +
        "-Dmockserver.corsMaxAgeInSeconds=\"300\""
});</code></pre>
    </div>
    <button class="accordion inner">Python</button>
    <div class="panel">
        <pre class="prettyprint lang-python code"><code class="code">from mockserver import start_server

# the launcher passes these JVM system properties straight through to the server
server = start_server(port=1080, extra_args=[
    "-Dmockserver.enableCORSForAPI=true",
    "-Dmockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE",
    "-Dmockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization",
    "-Dmockserver.corsAllowCredentials=true",
    "-Dmockserver.corsMaxAgeInSeconds=300",
])</code></pre>
    </div>
    <button class="accordion inner">Ruby</button>
    <div class="panel">
        <pre class="prettyprint lang-ruby code"><code class="code">require 'mockserver-client'

# the launcher passes these JVM system properties straight through to the server
server = MockServer::BinaryLauncher.start(port: 1080, extra_args: [
    '-Dmockserver.enableCORSForAPI=true',
    '-Dmockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE',
    '-Dmockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization',
    '-Dmockserver.corsAllowCredentials=true',
    '-Dmockserver.corsMaxAgeInSeconds=300'
])</code></pre>
    </div>
    <button class="accordion inner">Go</button>
    <div class="panel">
        <pre class="prettyprint lang-go code"><code class="code">import (
    "os"

    mockserver "github.com/mock-server/mockserver-monorepo/mockserver-client-go/v7"
)

// the launched server inherits these environment variables
os.Setenv("MOCKSERVER_ENABLE_CORS_FOR_API", "true")
os.Setenv("MOCKSERVER_CORS_ALLOW_METHODS", "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE")
os.Setenv("MOCKSERVER_CORS_ALLOW_HEADERS", "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization")
os.Setenv("MOCKSERVER_CORS_ALLOW_CREDENTIALS", "true")
os.Setenv("MOCKSERVER_CORS_MAX_AGE_IN_SECONDS", "300")

server, _ := mockserver.StartServer(1080, "", nil)</code></pre>
    </div>
    <button class="accordion inner">.NET</button>
    <div class="panel">
        <pre class="prettyprint lang-csharp code"><code class="code">using System;
using MockServer.Client;

// the launched server inherits these environment variables
Environment.SetEnvironmentVariable("MOCKSERVER_ENABLE_CORS_FOR_API", "true");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_ALLOW_METHODS", "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_ALLOW_HEADERS", "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_ALLOW_CREDENTIALS", "true");
Environment.SetEnvironmentVariable("MOCKSERVER_CORS_MAX_AGE_IN_SECONDS", "300");

var server = MockServerBinaryLauncher.Start(port: 1080);</code></pre>
    </div>
    <button class="accordion inner">Rust</button>
    <div class="panel">
        <pre class="prettyprint lang-rust code"><code class="code">use mockserver_client::launcher;

// the launched server inherits these environment variables
std::env::set_var("MOCKSERVER_ENABLE_CORS_FOR_API", "true");
std::env::set_var("MOCKSERVER_CORS_ALLOW_METHODS", "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE");
std::env::set_var("MOCKSERVER_CORS_ALLOW_HEADERS", "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization");
std::env::set_var("MOCKSERVER_CORS_ALLOW_CREDENTIALS", "true");
std::env::set_var("MOCKSERVER_CORS_MAX_AGE_IN_SECONDS", "300");

let server = launcher::start(1080).unwrap();</code></pre>
    </div>
    <button class="accordion inner">PHP</button>
    <div class="panel">
        <pre class="prettyprint lang-php code"><code class="code">use MockServer\BinaryLauncher;

// the launcher passes these JVM system properties straight through to the server
$server = (new BinaryLauncher())-&gt;start(1080, [
    '-Dmockserver.enableCORSForAPI=true',
    '-Dmockserver.corsAllowMethods=CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE',
    '-Dmockserver.corsAllowHeaders=Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization',
    '-Dmockserver.corsAllowCredentials=true',
    '-Dmockserver.corsMaxAgeInSeconds=300',
]);</code></pre>
    </div>
    <button class="accordion inner">REST API</button>
    <div class="panel">
        <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/configuration" -d '{
    "enableCORSForAPI": true,
    "corsAllowMethods": "CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE",
    "corsAllowHeaders": "Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization",
    "corsAllowCredentials": true,
    "corsMaxAgeInSeconds": 300
}'</code></pre>
        <p>The <code class="inline code">enableCORSForAPI</code> flag takes effect at runtime; the detailed <code class="inline code">corsAllow*</code> / <code class="inline code">corsMaxAgeInSeconds</code> values are only applied when the server starts, so set those at launch (see the other tabs).</p>
    </div>
    <button class="accordion inner">Command Line</button>
    <div class="panel">
        <pre class="prettyprint lang-bash code"><code class="code">java -Dmockserver.enableCORSForAPI=true \
-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE" \
-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization" \
-Dmockserver.corsAllowCredentials="true" \
-Dmockserver.corsMaxAgeInSeconds="300" \
-jar "~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar" -serverPort 1080</code></pre>
    </div>
</div>

<h2>See Also</h2>

<ul>
    <li><a href="/mock_server/configuration_properties.html#cors_configuration"><strong>CORS Configuration Properties</strong></a> &mdash; all CORS-related configuration properties and their defaults</li>
    <li><a href="/mock_server/control_plane_authorisation.html#hardening_control_plane_cors"><strong>Hardening Control Plane CORS</strong></a> &mdash; restrict cross-origin access to MockServer's control plane in shared or exposed environments</li>
    <li><a href="/mock_server/HTTPS_TLS.html"><strong>HTTPS &amp; TLS</strong></a> &mdash; serve cross-origin requests securely over HTTPS</li>
    <li><a href="/mock_server/mocking_oauth2.html"><strong>Mocking OAuth2 Flows</strong></a> &mdash; mock OAuth2 endpoints for browser-based clients that rely on CORS</li>
</ul>