API Security
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:
- be a valid key pair
- be signed by one of the certificates in the CA chain controlPlaneTLSMutualAuthenticationCAChain for control plane requests to be authorised
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:
- be a valid key pair
- be signed by one of the certificates in the CA chain controlPlaneTLSMutualAuthenticationCAChain for control plane requests to be authorised
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"