Enable verified OIDC authentication for control plane interactions (i.e. create expectations, clear, reset, verify, retrieve, stop, etc) using access tokens issued by an external OpenID Connect identity provider

If enabled then all control plane requests must include a Bearer access token via an authorization header. The token signature is verified against the provider's JWK set, and its issuer, audience, expiry and required scopes are checked. The verified subject (sub) is recorded as the principal in the control plane audit log.

For security, the OIDC handler enforces the following secure-by-default requirements (MockServer will refuse to start the OIDC handler, and fail every control plane request closed with a 401, if any are not met):

• At least one of controlPlaneOidcIssuer or controlPlaneOidcAudience must be set — without either, any validly-signed token from the JWK set would be accepted regardless of who it was issued for.
• A remote controlPlaneOidcJwksUri (or issuer used for discovery) must use https://. Plaintext http:// is allowed only for localhost/loopback (local testing).
• Tokens must carry an exp (expiry) claim, and are verified only against asymmetric signing algorithms (RS*, PS*, ES*, EdDSA) — HMAC and unsigned (alg=none) tokens are always rejected.

When a control plane request fails OIDC authentication the client receives a generic Unauthorized for control plane response; the detailed reason (e.g. expected issuer/audience/scopes) is written only to the MockServer server log.

It is possible to enable controlPlaneOidcAuthenticationRequired alongside controlPlaneTLSMutualAuthenticationRequired and/or controlPlaneJWTAuthenticationRequired, in which case every enabled handler must pass.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneOidcAuthenticationRequired(boolean controlPlaneOidcAuthenticationRequired)

System Property:

-Dmockserver.controlPlaneOidcAuthenticationRequired=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.controlPlaneOidcAuthenticationRequired=...

Example:

-Dmockserver.controlPlaneOidcAuthenticationRequired="true"

Issuer (i.e. iss) required on control plane OIDC tokens. When controlPlaneOidcJwksUri is not set, the JWKS URI is discovered from this issuer's OIDC discovery document at {issuer}/.well-known/openid-configuration.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcIssuer(String controlPlaneOidcIssuer)

System Property:

-Dmockserver.controlPlaneOidcIssuer=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_ISSUER=...

Property File:

mockserver.controlPlaneOidcIssuer=...

Example:

-Dmockserver.controlPlaneOidcIssuer="https://idp.example.com"

JWKS URI used to verify control plane OIDC token signatures. If not set, it is discovered from the issuer's OIDC discovery document. A remote URI must use https:// (plaintext http:// is permitted only to localhost/loopback); a file or classpath path may also be used.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcJwksUri(String controlPlaneOidcJwksUri)

System Property:

-Dmockserver.controlPlaneOidcJwksUri=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_JWKS_URI=...

Property File:

mockserver.controlPlaneOidcJwksUri=...

Example:

-Dmockserver.controlPlaneOidcJwksUri="https://idp.example.com/.well-known/jwks.json"

Audience claim (i.e. aud) required on control plane OIDC tokens.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcAudience(String controlPlaneOidcAudience)

System Property:

-Dmockserver.controlPlaneOidcAudience=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_AUDIENCE=...

Property File:

mockserver.controlPlaneOidcAudience=...

Example:

-Dmockserver.controlPlaneOidcAudience="mockserver-control-plane"

Scopes that must all be present in a control plane OIDC token before it is accepted.

Value should be a string with comma separated values, for example: mockserver.read,mockserver.write

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneOidcRequiredScopes(Set<String> controlPlaneOidcRequiredScopes)

System Property:

-Dmockserver.controlPlaneOidcRequiredScopes=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_REQUIRED_SCOPES=...

Property File:

mockserver.controlPlaneOidcRequiredScopes=...

Example:

-Dmockserver.controlPlaneOidcRequiredScopes="mockserver.read,mockserver.write"

Name of the claim holding granted scopes on a control plane OIDC token. Default scope is read as a space-delimited string; array claims such as scp, roles or groups are also supported.

Type: string Default: scope

Java Code:

ConfigurationProperties.controlPlaneOidcScopeClaim(String controlPlaneOidcScopeClaim)

System Property:

-Dmockserver.controlPlaneOidcScopeClaim=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_OIDC_SCOPE_CLAIM=...

Property File:

mockserver.controlPlaneOidcScopeClaim=...

Example:

-Dmockserver.controlPlaneOidcScopeClaim="scp"

Enable coarse role-based authorization of control plane requests. Once a request is authenticated, the verified principal's scopes/groups are mapped (via Control Plane Scope Mapping) to one of three hierarchical roles — read, mutate or admin (admin satisfies mutate satisfies read). Reads (retrieve/verify/diff and all GETs) require read; every other operation (creating expectations, clear, reset, etc.) requires mutate. A principal without a sufficient role is rejected with 403 Forbidden and the denial is audited with outcome FORBIDDEN.

Authorization requires a verified principal with mapped scopes, so it should be used together with control plane OIDC authentication. It is off by default; when disabled, an authenticated request is never additionally authorized.

Type: boolean Default: false

Java Code:

ConfigurationProperties.controlPlaneAuthorizationEnabled(boolean enable)

System Property:

-Dmockserver.controlPlaneAuthorizationEnabled=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_AUTHORIZATION_ENABLED=...

Property File:

mockserver.controlPlaneAuthorizationEnabled=...

Example:

-Dmockserver.controlPlaneAuthorizationEnabled="true"

Mapping from a verified scope/group value to a coarse control plane role (read, mutate or admin), used when Control Plane Authorization Enabled is true.

Value should be a comma separated list of value=role pairs, for example: platform-admins=admin,qa-team=mutate,viewers=read. Unrecognised roles and malformed pairs are ignored.

Type: string Default: null

Java Code:

ConfigurationProperties.controlPlaneScopeMapping(Map<String, ControlPlaneRole> controlPlaneScopeMapping)

System Property:

-Dmockserver.controlPlaneScopeMapping=...

Environment Variable:

MOCKSERVER_CONTROL_PLANE_SCOPE_MAPPING=...

Property File:

mockserver.controlPlaneScopeMapping=...

Example:

-Dmockserver.controlPlaneScopeMapping="platform-admins=admin,qa-team=mutate,viewers=read"