MCPExternalAuthConfig (toolhive.stacklok.dev/v1alpha1)

SubjectProviderName is the name of the upstream provider whose access token
is used as the web identity token for STS AssumeRoleWithWebIdentity.
This field is used exclusively by VirtualMCPServer, where there is no
upstream swap middleware to replace the bearer token before the strategy runs.
When left empty and an embedded authorization server is configured on the
VirtualMCPServer, the controller automatically populates this field with
the first configured upstream provider name. Set it explicitly to override
that default or to select a specific provider when multiple upstreams are
configured.
When no embedded auth server is present, the bearer token from the incoming
request's Authorization header is used instead.

AuthorizationEndpointBaseURL overrides the base URL used for the authorization_endpoint
in the OAuth discovery document. When set, the discovery document will advertise
{authorizationEndpointBaseUrl}/oauth/authorize instead of {issuer}/oauth/authorize.
All other endpoints (token, registration, JWKS) remain derived from the issuer.
This is useful when the browser-facing authorization endpoint needs to be on a
different host than the issuer used for backend-to-backend calls.
Must be a valid HTTPS URL (or HTTP for localhost, or HTTP for trusted in-cluster hosts
when insecureAllowHTTP is true) without query, fragment, or trailing slash.

BaselineClientScopes is a baseline set of OAuth 2.0 scopes guaranteed to be
included in every client registration. The embedded auth server unions these
scopes into the registered set returned by RFC 7591 Dynamic Client
Registration, so a client that narrows the scope field at /oauth/register
can still request the baseline scopes at /oauth/authorize. All values must
be present in the upstream-derived scopesSupported set; the auth server
fails to start if any value is missing.

Security: every client registered via /oauth/register will gain the
ability to request these scopes at /oauth/authorize, regardless of what
the client itself requested. Keep the baseline narrow (typically
"openid" and "offline_access"). Adding a privileged scope here — e.g.
"admin:read" — would grant it to every DCR-registered client, including
public clients like Claude Code, Cursor, and VS Code.
When cimd.enabled is true, every dynamically resolved CIMD client will
also gain the ability to request these scopes, including third-party
clients resolved from arbitrary HTTPS URLs.

DisableUpstreamTokenInjection prevents the embedded auth server from injecting
upstream IdP tokens into requests forwarded to the backend MCP server.
When true, the embedded auth server still handles OAuth flows for clients,
but instead of swapping ToolHive JWTs for upstream tokens the proxy STRIPS
the client's credential headers (Authorization, Cookie, Proxy-Authorization)
after validating the JWT — the backend receives an unauthenticated request.
Use headerForward to attach static credentials (e.g. an API key) if the
backend needs them. Cannot be combined with token exchange or AWS STS,
which would re-add credentials after the strip.
This is useful when the backend MCP server does not require authentication
(e.g., public documentation servers) but you still want client authentication.

HMACSecretRefs references Kubernetes Secrets containing symmetric secrets for signing
authorization codes and refresh tokens (opaque tokens).
Current secret must be at least 32 bytes and cryptographically random.
Supports secret rotation via multiple entries (first is current, rest are for verification).
If not specified, an ephemeral secret will be auto-generated (development only -
auth codes and refresh tokens will be invalid after restart).

InsecureAllowHTTP permits an http:// issuer URL for non-localhost hosts.
Only set this for in-cluster Kubernetes deployments where traffic between
pods traverses a trusted network (e.g. the in-cluster service mesh).
Production deployments reachable outside the cluster MUST use https://.

On VirtualMCPServer: when false (the default), http:// issuers for non-localhost
hosts are rejected at reconcile time with an AuthServerConfigValidated=False condition.

On MCPServer and MCPRemoteProxy (via MCPExternalAuthConfig): this field is
structurally present but enforcement is deferred to pod startup via Config.Validate();
a misconfigured issuer will cause the pod to crash at startup rather than surface
as an operator condition.

Issuer is the issuer identifier for this authorization server.
This will be included in the "iss" claim of issued tokens.
Must be a valid HTTPS URL (or HTTP for localhost, or HTTP for trusted in-cluster hosts when
insecureAllowHTTP is true) without query, fragment, or trailing slash (per RFC 8414).

PrimaryUpstreamProvider names the upstream IDP whose access token Cedar
should read claims from when authorising a request. Must match the name
of one of the entries in UpstreamProviders. When empty, the controller
auto-selects the first entry of UpstreamProviders.

Only meaningful on VirtualMCPServer, where multiple upstream providers
can be configured and Cedar needs to pick which token's claims to
evaluate. The VirtualMCPServer controller validates this field against
UpstreamProviders at admission and rejects unresolvable values.

On MCPServer and MCPRemoteProxy this field is structurally present (the
EmbeddedAuthServerConfig struct is shared) but has no runtime effect:
those CRDs are restricted to a single upstream so there is no choice to
make. Setting it on those CRDs is silently ignored.

SigningKeySecretRefs references Kubernetes Secrets containing signing keys for JWT operations.
Supports key rotation by allowing multiple keys (oldest keys are used for verification only).
If not specified, an ephemeral signing key will be auto-generated (development only -
JWTs will be invalid after restart).

Authority overrides the default Entra login host
(https://login.microsoftonline.com) for sovereign or national clouds, e.g.
https://login.microsoftonline.us (US Gov) or
https://login.partner.microsoftonline.cn (China). When set, the operator
builds the token endpoint by joining <authority>, <tenantId>, and the
v2.0 token path. Must be an HTTPS URL with no userinfo, query, fragment,
or trailing slash; a path IS permitted and is prefixed before the tenant
segment, as some sovereign / B2C / CIAM endpoints require. The OBO exchange
POSTs the client secret and the end-user assertion to this host, so it is a
credential trust boundary: HTTPS is required and userinfo (user@host) is
rejected to prevent host confusion (per RFC 3986 the real host follows the
"@", so https://login.microsoftonline.com@attacker.example targets
attacker.example). This is intentionally stricter than the downstream
exchanger's validateHTTPSURL, which also accepts http for loopback hosts
and tolerates a trailing slash — rejecting those at admission is the safe
direction.

CacheSkew overrides the OBO token cache's default expiry skew (the margin
by which a cached token is treated as expired before its real expiry),
e.g. "30s". The operator converts it to the runtime contract's
integer-seconds cacheSkewSeconds. Should not be negative, but the schema
does not enforce that — metav1.Duration carries no numeric minimum — and
upstream builds do not reject it. A negative value is rejected only by an
enterprise build's OBO handler once that handler validates the converted
parameters; it is not enforced at admission or in upstream-only builds.
When omitted, the cache default applies.

ClientID is the confidential client's application (client) ID registered
in Entra. Emitted verbatim as the runtime contract's clientId.
Optional at the CRD level so future client-authentication methods (e.g.
certificate or workload-identity credentials, planned fast-follows) can be
added without a breaking schema change. The operator enforces that clientId
and clientSecretRef are both present for the v1 shared-secret flow.

ClientSecretRef references a Kubernetes Secret containing the confidential
client's secret. v1 supports a shared client secret only. The operator
injects the resolved value into the proxyrunner pod as an environment
variable and emits only that variable's name in the runtime contract, as
clientSecretEnvVar — the secret value never travels in the contract.
Optional at the CRD level for the same forward-compatibility reason as
clientId (a certificate/workload-identity flow needs no client secret);
the operator enforces presence for the v1 shared-secret flow.

Scopes are the delegated scopes to request for the exchanged token, e.g.
["api://<backend>/.default"]. When non-empty they take precedence over
Audience. At least one of audience or scopes must be set; the operator
enforces that at reconcile. The MaxItems and per-item length caps are
defensive bounds on an otherwise unbounded list.

SubjectTokenProviderName selects the source of the OBO subject (assertion)
token from the request's authenticated Identity:
- Omitted: use the inbound end-user token the client presented
(Identity.Token) — the deployment with no embedded auth server, where
the client holds an Entra token directly.
- Set: use the named upstream provider's token
(Identity.UpstreamTokens[<name>]) — the embedded-auth-server
deployment, where the inbound token is the proxy's own session token.
The value must match a configured upstream provider name.
The subject is always sourced from the authenticated Identity, never from
an inbound request header, so the upstream auth middleware must run first.

TenantID is the Microsoft Entra (Azure AD) directory (tenant) identifier.
Optional at the CRD level (see the type doc); the operator enforces its
presence, since an OBO confidential-client exchange must target a specific
tenant. When set, it must be one of the two forms the Entra v2.0 token
endpoint addresses: a directory GUID, or a verified domain name (e.g.
contoso.onmicrosoft.com). Well-known aliases such as "common",
"organizations", and "consumers" are NOT accepted. The operator
interpolates it into the token endpoint
(<authority>/<tenantId>/oauth2/v2.0/token), so the value is constrained to
the GUID/domain shape (no path metacharacters); the pattern and 253-char
cap mirror the enterprise exchanger's validateTenant, so any tenantId
admitted here is one the runtime can consume.

SubjectProviderName is the name of the upstream provider whose token is used as the
RFC 8693 subject token instead of identity.Token when performing token exchange.
When left empty and an embedded authorization server is configured on the VirtualMCPServer,
the controller automatically populates this field with the first configured upstream
provider name. Set it explicitly to override that default or to select a specific
provider when multiple upstreams are configured.

SubjectTokenType is the type of the incoming subject token.
Accepts short forms: "accesstoken" (default), "idtoken", "jwt"
Or full URNs: "urn:ietf:params:oauth:token-type:accesstoken",
"urn:ietf:params:oauth:token-type:idtoken",
"urn:ietf:params:oauth:token-type:jwt"
For Google Workload Identity Federation with OIDC providers (like Okta), use "id_token"

TargetResource is the RFC 8707 resource indicator sent as the resource
parameter in IdP exchange (RFC 8693, draft §4.3, OPTIONAL). It
identifies the target resource server — not the access-token audience, which
is governed by TargetAudience. For MCP backends, set to the MCP server URL.
Some authorization servers (e.g. Okta's early ID-JAG implementation) require
this parameter in practice despite the draft marking it optional — set it
when your IdP needs it.