MCPExternalAuthConfig
toolhive.stacklok.dev / v1beta1
apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPExternalAuthConfig
metadata:
name: example
apiVersion
string
APIVersion defines the versioned schema of this representation of an object.
Servers should convert recognized schemas to the latest internal value, and
may reject unrecognized values.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind
string
Kind is a string value representing the REST resource this object represents.
Servers may infer this from the endpoint the client submits requests to.
Cannot be updated.
In CamelCase.
More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
metadata
object
spec object
MCPExternalAuthConfigSpec defines the desired state of MCPExternalAuthConfig.
MCPExternalAuthConfig resources are namespace-scoped and can only be referenced by
MCPServer resources in the same namespace.
awsSts object
AWSSts configures AWS STS authentication with SigV4 request signing
Only used when Type is "awsSts"
fallbackRoleArn
string
FallbackRoleArn is the IAM role ARN to assume when no role mappings match
Used as the default role when RoleMappings is empty or no mapping matches
At least one of FallbackRoleArn or RoleMappings must be configured (enforced by webhook)
pattern:
^arn:(aws|aws-cn|aws-us-gov):iam::\d{12}:role/[\w+=,.@\-_/]+$
region
string required
Region is the AWS region for the STS endpoint and service (e.g., "us-east-1", "eu-west-1")
pattern:
^[a-z]{2}(-[a-z]+)+-\d+$minLength:
1
roleClaim
string
RoleClaim is the JWT claim to use for role mapping evaluation
Defaults to "groups" to match common OIDC group claims
roleMappings []object
RoleMappings defines claim-based role selection rules
Allows mapping JWT claims (e.g., groups, roles) to specific IAM roles
Lower priority values are evaluated first (higher priority)
claim
string
Claim is a simple claim value to match against
The claim type is specified by AWSStsConfig.RoleClaim
For example, if RoleClaim is "groups", this would be a group name
Internally compiled to a CEL expression: "<claim_value>" in claims["<role_claim>"]
Mutually exclusive with Matcher
minLength:
1
matcher
string
Matcher is a CEL expression for complex matching against JWT claims
The expression has access to a "claims" variable containing all JWT claims as map[string]any
Examples:
- "admins" in claims["groups"]
- claims["sub"] == "user123" && !("act" in claims)
Mutually exclusive with Claim
minLength:
1
priority
integer
Priority determines evaluation order (lower values = higher priority)
Allows fine-grained control over role selection precedence
When omitted, this mapping has the lowest possible priority and
configuration order acts as tie-breaker via stable sort
format:
int32minimum:
0
roleArn
string required
RoleArn is the IAM role ARN to assume when this mapping matches
pattern:
^arn:(aws|aws-cn|aws-us-gov):iam::\d{12}:role/[\w+=,.@\-_/]+$
service
string
Service is the AWS service name for SigV4 signing
Defaults to "aws-mcp" for AWS MCP Server endpoints
sessionDuration
integer
SessionDuration is the duration in seconds for the STS session
Must be between 900 (15 minutes) and 43200 (12 hours)
Defaults to 3600 (1 hour) if not specified
format:
int32minimum:
900maximum:
43200
sessionNameClaim
string
SessionNameClaim is the JWT claim to use for role session name
Defaults to "sub" to use the subject claim
subjectProviderName
string
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.
bearerToken object
BearerToken configures bearer token authentication
Only used when Type is "bearerToken"
tokenSecretRef object required
TokenSecretRef references a Kubernetes Secret containing the bearer token
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
embeddedAuthServer object
EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server
Only used when Type is "embeddedAuthServer"
authorizationEndpointBaseUrl
string
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) without query, fragment, or trailing slash.
pattern:
^https?://[^\s?#]+[^/\s?#]$
baselineClientScopes
[]string
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.
maxItems:
10cimd object
CIMD configures Client ID Metadata Document support. When omitted, CIMD is disabled.
cacheFallbackTtl
string
CacheFallbackTTL is the fixed TTL applied to every cached CIMD document.
Cache-Control header parsing is not yet implemented; all entries use this value.
Format: Go duration string (e.g. "5m", "10m", "1h").
Defaults to 5 minutes when Enabled is true and this field is omitted.
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
cacheMaxSize
integer
CacheMaxSize is the maximum number of CIMD documents held in the LRU cache.
Defaults to 256 when Enabled is true and this field is omitted.
minimum:
1
enabled
boolean required
Enabled activates CIMD client lookup. When false (the default), the AS only
accepts client_id values that were registered via DCR.
hmacSecretRefs []object
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).
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
issuer
string required
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) without query, fragment, or trailing slash (per RFC 8414).
pattern:
^https?://[^\s?#]+[^/\s?#]$
primaryUpstreamProvider
string
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.
pattern:
^[a-z0-9]([a-z0-9-]*[a-z0-9])?$minLength:
1maxLength:
63signingKeySecretRefs []object
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).
maxItems:
5
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
storage object
Storage configures the storage backend for the embedded auth server.
If not specified, defaults to in-memory storage.
redis object
Redis configures the Redis storage backend.
Required when type is "redis".
aclUserConfig object required
ACLUserConfig configures Redis ACL user authentication.
passwordSecretRef object required
PasswordSecretRef references a Secret containing the Redis ACL password.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
usernameSecretRef object
UsernameSecretRef references a Secret containing the Redis ACL username.
When omitted, connections use legacy password-only AUTH. Omit for managed
Redis tiers that do not support ACL users (e.g. GCP Memorystore Basic/Standard
HA, Azure Cache for Redis). Set for services that support ACL users (e.g. AWS
ElastiCache non-cluster with Redis 6+ RBAC).
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
addr
string
Addr is the Redis server address (host:port). Required for standalone and cluster modes.
Use for managed Redis services that expose a single endpoint (GCP Memorystore basic tier,
AWS ElastiCache without cluster mode, or cluster-mode services when clusterMode is true).
Mutually exclusive with sentinelConfig.
clusterMode
boolean
ClusterMode enables the Redis Cluster protocol. Set to true when addr points to a
Redis Cluster discovery endpoint (e.g., GCP Memorystore Cluster, AWS ElastiCache
cluster mode enabled). Requires addr to be set.
dialTimeout
string
DialTimeout is the timeout for establishing connections.
Format: Go duration string (e.g., "5s", "1m").
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
readTimeout
string
ReadTimeout is the timeout for socket reads.
Format: Go duration string (e.g., "3s", "1m").
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$sentinelConfig object
SentinelConfig holds Redis Sentinel configuration.
Use for self-managed Redis with Sentinel-based HA. Mutually exclusive with addr.
db
integer
DB is the Redis database number.
format:
int32
masterName
string required
MasterName is the name of the Redis master monitored by Sentinel.
sentinelAddrs
[]string
SentinelAddrs is a list of Sentinel host:port addresses.
Mutually exclusive with SentinelService.
sentinelService object
SentinelService enables automatic discovery from a Kubernetes Service.
Mutually exclusive with SentinelAddrs.
name
string required
Name of the Sentinel Service.
namespace
string
Namespace of the Sentinel Service (defaults to same namespace).
port
integer
Port of the Sentinel service.
format:
int32sentinelTls object
SentinelTLS configures TLS for connections to Sentinel instances.
Only applies when sentinelConfig is set. Presence of this field enables TLS.
caCertSecretRef object
CACertSecretRef references a Secret containing a PEM-encoded CA certificate
for verifying the server. When not specified, system root CAs are used.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
insecureSkipVerify
boolean
InsecureSkipVerify skips TLS certificate verification.
Use when connecting to services with self-signed certificates.
tls object
TLS configures TLS for connections to the Redis/Valkey master or cluster nodes.
Presence of this field enables TLS. Omit to use plaintext.
caCertSecretRef object
CACertSecretRef references a Secret containing a PEM-encoded CA certificate
for verifying the server. When not specified, system root CAs are used.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
insecureSkipVerify
boolean
InsecureSkipVerify skips TLS certificate verification.
Use when connecting to services with self-signed certificates.
writeTimeout
string
WriteTimeout is the timeout for socket writes.
Format: Go duration string (e.g., "3s", "1m").
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
type
string
Type specifies the storage backend type.
Valid values: "memory" (default), "redis".
enum:
memory, redistokenLifespans object
TokenLifespans configures the duration that various tokens are valid.
If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).
accessTokenLifespan
string
AccessTokenLifespan is the duration that access tokens are valid.
Format: Go duration string (e.g., "1h", "30m", "24h").
If empty, defaults to 1 hour.
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
authCodeLifespan
string
AuthCodeLifespan is the duration that authorization codes are valid.
Format: Go duration string (e.g., "10m", "5m").
If empty, defaults to 10 minutes.
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
refreshTokenLifespan
string
RefreshTokenLifespan is the duration that refresh tokens are valid.
Format: Go duration string (e.g., "168h", "7d" as "168h").
If empty, defaults to 7 days (168h).
pattern:
^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$upstreamProviders []object required
UpstreamProviders configures connections to upstream Identity Providers.
The embedded auth server delegates authentication to these providers.
MCPServer and MCPRemoteProxy support a single upstream; VirtualMCPServer supports multiple.
minItems:
1
name
string required
Name uniquely identifies this upstream provider.
Used for routing decisions and session binding in multi-upstream scenarios.
Must be lowercase alphanumeric with hyphens (DNS-label-like).
pattern:
^[a-z0-9]([a-z0-9-]*[a-z0-9])?$minLength:
1maxLength:
63oauth2Config object
OAuth2Config contains OAuth 2.0-specific configuration.
Required when Type is "oauth2", must be nil when Type is "oidc".
additionalAuthorizationParams
object
AdditionalAuthorizationParams are extra query parameters to include in
authorization requests sent to the upstream provider.
This is useful for providers that require custom parameters, such as
Google's access_type=offline for obtaining refresh tokens.
Framework-managed parameters (response_type, client_id, redirect_uri,
scope, state, code_challenge, code_challenge_method, nonce) are not allowed.
authorizationEndpoint
string required
AuthorizationEndpoint is the URL for the OAuth authorization endpoint.
pattern:
^https?://.*$
clientId
string
ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
Mutually exclusive with DCRConfig: when DCRConfig is set, ClientID is obtained
at runtime via RFC 7591 Dynamic Client Registration and must be left empty.
clientSecretRef object
ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret.
Optional for public clients using PKCE instead of client secret.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
dcrConfig object
DCRConfig enables RFC 7591 Dynamic Client Registration against the upstream
authorization server. When set, the client credentials are obtained at
runtime rather than being pre-provisioned, and ClientID must be left empty.
Mutually exclusive with ClientID.
discoveryUrl
string
DiscoveryURL is the RFC 8414 / OIDC Discovery document URL. The resolver
issues a single GET against this URL (no well-known-path fallback) and
reads registration_endpoint, authorization_endpoint, token_endpoint,
token_endpoint_auth_methods_supported, and scopes_supported from the
response.
Mutually exclusive with RegistrationEndpoint.
HTTPS is required because the registration endpoint resolved from this
document carries the initial access token and the issued client_secret
(RFC 7591 §3, RFC 8414 §3). MaxLength is a defensive size cap (etcd
object budget, regex evaluation cost) and matches the conventional URL
length cap.
pattern:
^https://[^\s?#]+[^/\s?#]$maxLength:
2048initialAccessTokenRef object
InitialAccessTokenRef is an optional reference to a Kubernetes Secret
carrying an RFC 7591 §3 initial access token. When set, the resolver
presents the token value as a Bearer credential on the registration
request. Mirrors the ClientSecretRef pattern.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
registrationEndpoint
string
RegistrationEndpoint is the RFC 7591 registration endpoint URL used
directly, bypassing discovery. When using this field, the caller is
expected to also supply AuthorizationEndpoint, TokenEndpoint, and an
explicit Scopes list on the parent OAuth2UpstreamConfig.
Mutually exclusive with DiscoveryURL.
HTTPS is required because the registration endpoint carries the initial
access token and the issued client_secret (RFC 7591 §3, RFC 8414 §3).
MaxLength is a defensive size cap (etcd object budget, regex evaluation
cost) and matches the conventional URL length cap.
pattern:
^https://[^\s?#]+[^/\s?#]$maxLength:
2048
softwareId
string
SoftwareID is the RFC 7591 "software_id" registration metadata value,
identifying the client software independent of any particular
registration instance. Typically a UUID or short identifier.
maxLength:
255
softwareStatement
string
SoftwareStatement is the RFC 7591 "software_statement" JWT asserting
metadata about the client software, signed by a party the authorization
server trusts.
Stored inline on the CR. The JWT is signed but not encrypted, so its
contents are visible to anyone with get/list/watch on this resource and
appear in etcd backups in plaintext. Treat the value as non-confidential
(signed attestation, not a secret). Operators that rotate software
statements like bearer credentials should keep them at the authorization
server side and rely on the registration endpoint's initial access
token (see InitialAccessTokenRef) instead of placing them on the CR.
Bounded to 16384 characters as a defensive size cap (etcd object
budget, regex evaluation cost). Real-world signed statements with
embedded x5c certificate chains, JWKS keys, or OIDC-Federation
trust-framework metadata routinely exceed 4 KB.
maxLength:
16384identityFromToken object
IdentityFromToken extracts user identity (subject, name, email) directly
from the OAuth2 token-endpoint response body using gjson dot-notation paths.
When set, the embedded auth server skips the userinfo HTTP call entirely
and resolves identity from the token response. See IdentityFromTokenConfig
for trust-model and uniqueness considerations.
emailPath
string
EmailPath is the dot-notation path to the email address field in the token response.
If not specified or if the path does not resolve to a string, the email is omitted.
Omit the field entirely rather than setting it to an empty string.
minLength:
1maxLength:
256
namePath
string
NamePath is the dot-notation path to the display name field in the token response.
If not specified or if the path does not resolve to a string, the display name is omitted.
Omit the field entirely rather than setting it to an empty string.
minLength:
1maxLength:
256
subjectPath
string required
SubjectPath is the dot-notation path to the subject (user ID) field in the token response.
Warning: claims read from the token response are trusted only via TLS, not
cryptographically verified; prefer OIDC ID tokens when verifiable claims are required.
Example: "authed_user.id" for Slack (top-level token-response field). For providers
whose token response embeds the access token as a JWT (e.g. Snowflake), use the
"@upstreamjwt" modifier to decode the payload, e.g. "access_token|@upstreamjwt|sub".
The "@upstreamjwt" modifier performs no signature verification either.
minLength:
1maxLength:
256
redirectUri
string
RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
When not specified, defaults to `{resourceUrl}/oauth/callback` where `resourceUrl` is the
URL associated with the resource (e.g., MCPServer or vMCP) using this config.
scopes
[]string
Scopes are the OAuth scopes to request from the upstream IDP.
tokenEndpoint
string required
TokenEndpoint is the URL for the OAuth token endpoint.
pattern:
^https?://.*$tokenResponseMapping object
TokenResponseMapping configures custom field extraction from non-standard token responses.
Some OAuth providers (e.g., GovSlack) nest token fields under non-standard paths
instead of returning them at the top level. When set, ToolHive performs the token
exchange HTTP call directly and extracts fields using the configured dot-notation paths.
If nil, standard OAuth 2.0 token response parsing is used.
For extracting user identity from the token response, see IdentityFromToken.
accessTokenPath
string required
AccessTokenPath is the dot-notation path to the access token in the response.
Example: "authed_user.access_token"
minLength:
1
expiresInPath
string
ExpiresInPath is the dot-notation path to the expires_in value (in seconds).
If not specified, defaults to "expires_in".
refreshTokenPath
string
RefreshTokenPath is the dot-notation path to the refresh token in the response.
If not specified, defaults to "refresh_token".
scopePath
string
ScopePath is the dot-notation path to the scope string in the response.
If not specified, defaults to "scope".
userInfo object
UserInfo contains configuration for fetching user information from the upstream provider.
When omitted and IdentityFromToken is also unset, the embedded auth server runs in
synthesis mode for this upstream: a non-PII subject derived from the access token, no
Name/Email. Use this shape for upstreams with no userinfo surface and no identity in
the token response (e.g., MCP authorization servers per the MCP spec). When
IdentityFromToken is set instead, identity is resolved from the token response body
(e.g., Snowflake's "username" field, Slack's "authed_user.id"); the userinfo HTTP call
is skipped entirely.
additionalHeaders
object
AdditionalHeaders contains extra headers to include in the userinfo request.
Useful for providers that require specific headers (e.g., GitHub's Accept header).
endpointUrl
string required
EndpointURL is the URL of the userinfo endpoint.
pattern:
^https?://.*$fieldMapping object
FieldMapping contains custom field mapping configuration for non-standard providers.
If nil, standard OIDC field names are used ("sub", "name", "email").
emailFields
[]string
EmailFields is an ordered list of field names to try for the email address.
The first non-empty value found will be used.
Default: ["email"]
nameFields
[]string
NameFields is an ordered list of field names to try for the display name.
The first non-empty value found will be used.
Default: ["name"]
subjectFields
[]string
SubjectFields is an ordered list of field names to try for the user ID.
The first non-empty value found will be used.
Default: ["sub"]
httpMethod
string
HTTPMethod is the HTTP method to use for the userinfo request.
If not specified, defaults to GET.
enum:
GET, POSToidcConfig object
OIDCConfig contains OIDC-specific configuration.
Required when Type is "oidc", must be nil when Type is "oauth2".
additionalAuthorizationParams
object
AdditionalAuthorizationParams are extra query parameters to include in
authorization requests sent to the upstream provider.
This is useful for providers that require custom parameters, such as
Google's access_type=offline for obtaining refresh tokens.
Note: when using access_type=offline, also set explicit scopes to avoid
the default offline_access scope being sent alongside it.
Framework-managed parameters (response_type, client_id, redirect_uri,
scope, state, code_challenge, code_challenge_method, nonce) are not allowed.
clientId
string required
ClientID is the OAuth 2.0 client identifier registered with the upstream IDP.
clientSecretRef object
ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret.
Optional for public clients using PKCE instead of client secret.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
issuerUrl
string required
IssuerURL is the OIDC issuer URL for automatic endpoint discovery.
Must be a valid HTTPS URL.
pattern:
^https://.*$
redirectUri
string
RedirectURI is the callback URL where the upstream IDP will redirect after authentication.
When not specified, defaults to `{resourceUrl}/oauth/callback` where `resourceUrl` is the
URL associated with the resource (e.g., MCPServer or vMCP) using this config.
scopes
[]string
Scopes are the OAuth scopes to request from the upstream IDP.
If not specified, defaults to ["openid", "offline_access"].
When using additionalAuthorizationParams with provider-specific refresh token
mechanisms (e.g., Google's access_type=offline), set explicit scopes to avoid
sending both offline_access and the provider-specific parameter.
userInfoOverride object
UserInfoOverride allows customizing UserInfo fetching behavior for OIDC providers.
By default, the UserInfo endpoint is discovered automatically via OIDC discovery.
Use this to override the endpoint URL, HTTP method, or field mappings for providers
that return non-standard claim names in their UserInfo response.
additionalHeaders
object
AdditionalHeaders contains extra headers to include in the userinfo request.
Useful for providers that require specific headers (e.g., GitHub's Accept header).
endpointUrl
string required
EndpointURL is the URL of the userinfo endpoint.
pattern:
^https?://.*$fieldMapping object
FieldMapping contains custom field mapping configuration for non-standard providers.
If nil, standard OIDC field names are used ("sub", "name", "email").
emailFields
[]string
EmailFields is an ordered list of field names to try for the email address.
The first non-empty value found will be used.
Default: ["email"]
nameFields
[]string
NameFields is an ordered list of field names to try for the display name.
The first non-empty value found will be used.
Default: ["name"]
subjectFields
[]string
SubjectFields is an ordered list of field names to try for the user ID.
The first non-empty value found will be used.
Default: ["sub"]
httpMethod
string
HTTPMethod is the HTTP method to use for the userinfo request.
If not specified, defaults to GET.
enum:
GET, POST
type
string required
Type specifies the provider type: "oidc" or "oauth2"
enum:
oidc, oauth2headerInjection object
HeaderInjection configures custom HTTP header injection
Only used when Type is "headerInjection"
headerName
string required
HeaderName is the name of the HTTP header to inject
minLength:
1valueSecretRef object required
ValueSecretRef references a Kubernetes Secret containing the header value
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
obo
object
OBO configures On-Behalf-Of (OBO) authentication.
Only used when Type is "obo". The inner schema is intentionally empty in
this revision; sub-fields land in a follow-up. Setting this field on an
upstream-only build will cause the MCPExternalAuthConfig to transition to
status.conditions[Valid] = False with Reason: EnterpriseRequired.
tokenExchange object
TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange
Only used when Type is "tokenExchange"
audience
string required
Audience is the target audience for the exchanged token
clientId
string
ClientID is the OAuth 2.0 client identifier
Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)
clientSecretRef object
ClientSecretRef is a reference to a secret containing the OAuth 2.0 client secret
Optional for some token exchange flows (e.g., Google Cloud Workforce Identity)
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
externalTokenHeaderName
string
ExternalTokenHeaderName is the name of the custom header to use for the exchanged token.
If set, the exchanged token will be added to this custom header (e.g., "X-Upstream-Token").
If empty or not set, the exchanged token will replace the Authorization header (default behavior).
scopes
[]string
Scopes is a list of OAuth 2.0 scopes to request for the exchanged token
subjectProviderName
string
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
string
SubjectTokenType is the type of the incoming subject token.
Accepts short forms: "access_token" (default), "id_token", "jwt"
Or full URNs: "urn:ietf:params:oauth:token-type:access_token",
"urn:ietf:params:oauth:token-type:id_token",
"urn:ietf:params:oauth:token-type:jwt"
For Google Workload Identity Federation with OIDC providers (like Okta), use "id_token"
pattern:
^(access_token|id_token|jwt|urn:ietf:params:oauth:token-type:(access_token|id_token|jwt))?$
tokenUrl
string required
TokenURL is the OAuth 2.0 token endpoint URL for token exchange
type
string required
Type is the type of external authentication to configure.
When set to "obo", the cluster must run a build that has registered an
OBO handler via controllerutil.RegisterOBOHandler; upstream-only builds
surface status.conditions[Valid] = False with Reason: EnterpriseRequired
for obo-typed configs.
enum:
tokenExchange, headerInjection, bearerToken, unauthenticated, embeddedAuthServer, awsSts, upstreamInject, oboupstreamInject object
UpstreamInject configures upstream token injection for backend requests.
Only used when Type is "upstreamInject".
providerName
string required
ProviderName is the name of the upstream IDP provider whose access token
should be injected as the Authorization: Bearer header.
minLength:
1status object
MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig
conditions []object
Conditions represent the latest available observations of the MCPExternalAuthConfig's state
lastTransitionTime
string required
lastTransitionTime is the last time the condition transitioned from one status to another.
This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
format:
date-time
message
string required
message is a human readable message indicating details about the transition.
This may be an empty string.
maxLength:
32768
observedGeneration
integer
observedGeneration represents the .metadata.generation that the condition was set based upon.
For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
with respect to the current state of the instance.
format:
int64minimum:
0
reason
string required
reason contains a programmatic identifier indicating the reason for the condition's last transition.
Producers of specific condition types may define expected values and meanings for this field,
and whether the values are considered a guaranteed API.
The value should be a CamelCase string.
This field may not be empty.
pattern:
^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$minLength:
1maxLength:
1024
status
string required
status of the condition, one of True, False, Unknown.
enum:
True, False, Unknown
type
string required
type of condition in CamelCase or in foo.example.com/CamelCase.
pattern:
^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$maxLength:
316
configHash
string
ConfigHash is a hash of the current configuration for change detection
observedGeneration
integer
ObservedGeneration is the most recent generation observed for this MCPExternalAuthConfig.
It corresponds to the MCPExternalAuthConfig's generation, which is updated on mutation by the API Server.
format:
int64
referenceCount
integer
ReferenceCount is the number of workloads referencing this config.
format:
int32referencingWorkloads []object
ReferencingWorkloads is a list of workload resources that reference this MCPExternalAuthConfig.
Each entry identifies the workload by kind and name.
kind
string required
Kind is the type of workload resource
enum:
MCPServer, VirtualMCPServer, MCPRemoteProxy
name
string required
Name is the name of the workload resource
minLength:
1No matches. Try .spec.awsSts for an exact path