Multiple techniques can be used to lock down MockServer deployments, as follows:

  • limit network access to MockServer, i.e. only available on localhost
  • launch MockServer on-demand, i.e. just before tests, and shutdown immediately after
  • disable or restrict cross-site requests using CORS
  • authenticate all TCP connections using mTLS
  • authenticate all REST API i.e. control plane requests using mTLS
  • authenticate all REST API i.e. control plane requests using JWT
 

Control Plane Authentication

Authentication can be enabled for all control plane requests (i.e. create expectations, clear, reset, verify, retrieve, stop, etc) using either mTLS, JWT or both.

If both mTLS and JWT are enabled mTLS will be validated first.

 

Control Plane mTLS Authentication

When mTLS authentication is enabled all control plane requests need to be received over a mTLS connection where the client's X509 certificates can be validated using the controlPlaneTLSMutualAuthenticationCAChain

Enable mTLS authentication for control plane interactions (i.e. create expectations, clear, reset, verify, retrieve, stop, etc)

If enabled then all control plane requests need to be received over a mTLS connection where the client's X509 certificates will be validated using the controlPlaneTLSMutualAuthenticationCAChain

It is possible to enable both controlPlaneJWTAuthenticationRequired and controlPlaneTLSMutualAuthenticationRequired but the mTLS will be checked first.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneTLSMutualAuthenticationRequired(boolean controlPlaneTLSMutualAuthenticationRequired)

System Property:

-Dmockserver.controlPlaneTLSMutualAuthenticationRequired=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.controlPlaneTLSMutualAuthenticationRequired=...

Example:

-Dmockserver.controlPlaneTLSMutualAuthenticationRequired="true"

File system path or classpath location of the CA (i.e. trust) chain to use to validate client X509 certificates if controlPlaneTLSMutualAuthenticationRequired is enabled

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneTLSMutualAuthenticationCAChain(String controlPlaneTLSMutualAuthenticationCAChain)

System Property:

-Dmockserver.controlPlaneTLSMutualAuthenticationCAChain=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...

Property File:

mockserver.controlPlaneTLSMutualAuthenticationCAChain=...

Example:

-Dmockserver.controlPlaneTLSMutualAuthenticationCAChain="/some/existing/path"

File system path or classpath location of the private key used by MockServerClient when controlPlaneTLSMutualAuthenticationRequired is enabled to ensure control plane request are correctly authorised

For control plane requests to be authorised the private key controlPlanePrivateKeyPath and certificate controlPlanePrivateKeyPath must:

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlanePrivateKeyPath(String controlPlanePrivateKeyPath)

System Property:

-Dmockserver.controlPlanePrivateKeyPath=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_PRIVATE_KEY_PATH=...

Property File:

mockserver.controlPlanePrivateKeyPath=...

Example:

-Dmockserver.controlPlanePrivateKeyPath="/some/existing/path"

File system path or classpath location of the certificate used by MockServerClient when controlPlaneTLSMutualAuthenticationRequired is enabled to ensure control plane request are correctly authorised

For control plane requests to be authorised the private key controlPlanePrivateKeyPath and certificate controlPlanePrivateKeyPath must:

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneX509CertificatePath(String controlPlaneX509CertificatePath)

System Property:

-Dmockserver.controlPlaneX509CertificatePath=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_TLS_X509_CERTIFICATE_PATH=...

Property File:

mockserver.controlPlaneX509CertificatePath=...

Example:

-Dmockserver.controlPlaneX509CertificatePath="/some/existing/path"
 

Control Plane JWT Authentication

When JWT authentication is enabled all control plane requests need and JWT via a authorization header which is validated using the controlPlaneJWTAuthenticationJWKSource

Enable JWT authentication for control plane interactions (i.e. create expectations, clear, reset, verify, retrieve, stop, etc)

If enabled then all control plane requests need and JWT via a authorization header which is validated using the controlPlaneJWTAuthenticationJWKSource

It is possible to enable both controlPlaneJWTAuthenticationRequired and controlPlaneTLSMutualAuthenticationRequired but the mTLS will be checked first.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationRequired(boolean controlPlaneJWTAuthenticationRequired)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationRequired=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.controlPlaneJWTAuthenticationRequired=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationRequired="true"

URL, file system path or classpath location of the JWK source when controlPlaneJWTAuthenticationRequired is enabled to validate JWT signatures

For control plane requests to be authorised:

  • they must include an authorization header, with a Bearer auth scheme, containing a JWT
  • the JWT should be validated by a key in the JWK source

For details of JWK see the JWK specification

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationJWKSource(String controlPlaneJWTAuthenticationJWKSource)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationJWKSource=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_JWK_SOURCE=...

Property File:

mockserver.controlPlaneJWTAuthenticationJWKSource=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationJWKSource="/some/existing/path"

Audience claim (i.e. aud) required when JWT authentication is enabled for control plane requests

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationExpectedAudience(String controlPlaneJWTAuthenticationExpectedAudience)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationExpectedAudience=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_EXPECTED_AUDIENCE=...

Property File:

mockserver.controlPlaneJWTAuthenticationExpectedAudience=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationExpectedAudience="/some/existing/path"

Matching claims expected when JWT authentication is enabled for control plane requests

Value should be string with comma separated key=value items, for example: scope=internal public,sub=some_subject

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationMatchingClaims(String controlPlaneJWTAuthenticationMatchingClaims)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationMatchingClaims=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_MATCHING_CLAIMS=...

Property File:

mockserver.controlPlaneJWTAuthenticationMatchingClaims=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationMatchingClaims="/some/existing/path"

Required claims that should exist (i.e. with any value) when JWT authentication is enabled for control plane requests

Value should be string with comma separated values, for example: scope,sub

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneJWTAuthenticationRequiredClaims(String controlPlaneJWTAuthenticationRequiredClaims)

System Property:

-Dmockserver.controlPlaneJWTAuthenticationRequiredClaims=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_JWT_AUTHENTICATION_REQUIRED_CLAIMS=...

Property File:

mockserver.controlPlaneJWTAuthenticationRequiredClaims=...

Example:

-Dmockserver.controlPlaneJWTAuthenticationRequiredClaims="/some/existing/path"