CORS Support | MockServer

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.

When CORS support is enabled, and the corsAllowMethods / corsAllowHeaders / corsAllowOrigin 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:

Access-Control-Allow-Origin: <request Origin>   # 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"

NOTE: by default the requesting Origin is reflected, so cross-site requests are allowed out of the box. Set an explicit corsAllowOrigin (for example an allow-list) to restrict which origins are permitted.

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 configuration properties, as below.

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

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"

For example to enable a more permission approach for cross-site requests use ConfigurationProperties class as follows:

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);

CORS Configuration:

Enable CORS for MockServer REST API so that the API can be used for javascript running in browsers, such as selenium

Type: boolean Default: false

Java Code:

ConfigurationProperties.enableCORSForAPI(boolean enableCORSForAPI)

System Property:

-Dmockserver.enableCORSForAPI=...

Environment Variable:

MOCKSERVER_ENABLE_CORS_FOR_API=...

Property File:

mockserver.enableCORSForAPI=...

Example:

-Dmockserver.enableCORSForAPI="true"

Enable CORS for all responses from MockServer, including the REST API and expectation responses

Type: boolean Default: false

Java Code:

ConfigurationProperties.enableCORSForAllResponses(boolean enableCORSForAllResponses)

System Property:

-Dmockserver.enableCORSForAllResponses=...

Environment Variable:

MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES=...

Property File:

mockserver.enableCORSForAllResponses=...

Example:

-Dmockserver.enableCORSForAllResponses="true"

The value used for CORS in the access-control-allow-origin header.

Note: To ensure access-control-allow-credentials works correctly, when corsAllowCredentials is true the CORS header access-control-allow-origin will set its value using the origin header on requests instead of corsAllowOrigin property.

Type: string Default: ""

Java Code:

ConfigurationProperties.corsAllowOrigin(String corsAllowOrigin)

System Property:

-Dmockserver.corsAllowOrigin=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_ORIGIN=...

Property File:

mockserver.corsAllowOrigin=...

Example:

-Dmockserver.corsAllowOrigin="*"

The value used for CORS in the access-control-allow-methods header.

Type: string Default: ""

Java Code:

ConfigurationProperties.corsAllowMethods(String corsAllowMethods)

System Property:

-Dmockserver.corsAllowMethods=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_METHODS=...

Property File:

mockserver.corsAllowMethods=...

Example:

-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"

Default value used for CORS in the access-control-allow-headers and access-control-expose-headers headers.

In addition to this default value any headers specified in the request header access-control-request-headers also get added to access-control-allow-headers and access-control-expose-headers headers in a CORS response.

Type: string Default: ""

Java Code:

ConfigurationProperties.corsAllowHeaders(String corsAllowHeaders)

System Property:

-Dmockserver.corsAllowHeaders=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_HEADERS=...

Property File:

mockserver.corsAllowHeaders=...

Example:

-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"

The value used for CORS in the access-control-allow-credentials header.

Type: boolean Default: false

Java Code:

ConfigurationProperties.corsAllowCredentials(boolean allow)

System Property:

-Dmockserver.corsAllowCredentials=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_CREDENTIALS=...

Property File:

mockserver.corsAllowCredentials=...

Example:

-Dmockserver.corsAllowCredentials="true"

The value used for CORS in the access-control-max-age header.

Type: int Default: 0

Java Code:

ConfigurationProperties.corsMaxAgeInSeconds(int maxAgeInSeconds)

System Property:

-Dmockserver.corsMaxAgeInSeconds=...

Environment Variable:

MOCKSERVER_CORS_MAX_AGE_IN_SECONDS=...

Property File:

mockserver.corsMaxAgeInSeconds=...

Example:

-Dmockserver.corsMaxAgeInSeconds=300

Examples:

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);

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-7.0.0-no-dependencies.jar" -serverPort 1080

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\""
});

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);

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-7.0.0-no-dependencies.jar" -serverPort 1080

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\""
});

CORS Configuration:

Examples:

See Also