MCPExternalAuthConfig
MCPExternalAuthConfig configures how an MCP server or proxy authenticates to external services via token exchange or an embedded authorization server. It is referenced by MCPServer, MCPRemoteProxy, MCPServerEntry, and VirtualMCPServer.
API: toolhive.stacklok.dev/v1beta1
· Scope: Namespaced · Short names: extauth, mcpextauth
Example
apiVersion: toolhive.stacklok.dev/v1beta1
kind: MCPExternalAuthConfig
metadata:
name: my-mcpexternalauthconfig
namespace: default
spec:
type: tokenExchange
Schema
spec
MCPExternalAuthConfigSpec defines the desired state of MCPExternalAuthConfig. MCPExternalAuthConfig resources are namespace-scoped and can only be referenced by MCPServer resources in the same namespace.
| Field | Type | Description |
|---|---|---|
awsSts | object | AWSSts configures AWS STS authentication with SigV4 request signing Only used when Type is "awsSts" |
bearerToken | object | BearerToken configures bearer token authentication Only used when Type is "bearerToken" |
embeddedAuthServer | object | EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server Only used when Type is "embeddedAuthServer" |
headerInjection | object | HeaderInjection configures custom HTTP header injection Only used when Type is "headerInjection" |
tokenExchange | object | TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange Only used when Type is "tokenExchange" |
typerequired | string | Type is the type of external authentication to configure enum: tokenExchange | headerInjection | bearerToken | unauthenticated | embeddedAuthServer | awsSts | upstreamInject |
upstreamInject | object | UpstreamInject configures upstream token injection for backend requests. Only used when Type is "upstreamInject". |
spec.awsSts
AWSSts configures AWS STS authentication with SigV4 request signing Only used when Type is "awsSts"
| Field | Type | Description |
|---|---|---|
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+=,.@\-_/]+$ |
regionrequired | string | 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 default "groups" |
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) |
service | string | Service is the AWS service name for SigV4 signing Defaults to "aws-mcp" for AWS MCP Server endpoints default "aws-mcp" |
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 default 3600 · format int32 · min 900 · max 43200 |
sessionNameClaim | string | SessionNameClaim is the JWT claim to use for role session name Defaults to "sub" to use the subject claim default "sub" |
spec.awsSts.roleMappings[]
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)
| Field | Type | Description |
|---|---|---|
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 int32 · min 0 |
roleArnrequired | string | 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+=,.@\-_/]+$ |
spec.bearerToken
BearerToken configures bearer token authentication Only used when Type is "bearerToken"
| Field | Type | Description |
|---|---|---|
tokenSecretRefrequired | object | TokenSecretRef references a Kubernetes Secret containing the bearer token |
spec.bearerToken.tokenSecretRef
TokenSecretRef references a Kubernetes Secret containing the bearer token
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer
EmbeddedAuthServer configures an embedded OAuth2/OIDC authorization server Only used when Type is "embeddedAuthServer"
| Field | Type | Description |
|---|---|---|
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?#]$ |
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). |
issuerrequired | string | 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?#]$ |
signingKeySecretRefs | 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). |
storage | object | Storage configures the storage backend for the embedded auth server. If not specified, defaults to in-memory storage. |
tokenLifespans | object | TokenLifespans configures the duration that various tokens are valid. If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m). |
upstreamProvidersrequired | object[] | 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. |
spec.embeddedAuthServer.hmacSecretRefs[]
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).
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.signingKeySecretRefs[]
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).
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.storage
Storage configures the storage backend for the embedded auth server. If not specified, defaults to in-memory storage.
| Field | Type | Description |
|---|---|---|
redis | object | Redis configures the Redis storage backend. Required when type is "redis". |
type | string | Type specifies the storage backend type. Valid values: "memory" (default), "redis". default "memory" · enum: memory | redis |
spec.embeddedAuthServer.storage.redis
Redis configures the Redis storage backend. Required when type is "redis".
| Field | Type | Description |
|---|---|---|
aclUserConfigrequired | object | ACLUserConfig configures Redis ACL user authentication. |
dialTimeout | string | DialTimeout is the timeout for establishing connections. Format: Go duration string (e.g., "5s", "1m"). default "5s" · 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"). default "3s" · pattern ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ |
sentinelConfigrequired | object | SentinelConfig holds Redis Sentinel configuration. |
sentinelTls | object | SentinelTLS configures TLS for connections to Sentinel instances. Presence of this field enables TLS. Omit to use plaintext. When omitted, sentinel connections use plaintext (no fallback to TLS config). |
tls | object | TLS configures TLS for connections to the Redis/Valkey master. Presence of this field enables TLS. Omit to use plaintext. |
writeTimeout | string | WriteTimeout is the timeout for socket writes. Format: Go duration string (e.g., "3s", "1m"). default "3s" · pattern ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$ |
spec.embeddedAuthServer.storage.redis.aclUserConfig
ACLUserConfig configures Redis ACL user authentication.
| Field | Type | Description |
|---|---|---|
passwordSecretRefrequired | object | PasswordSecretRef references a Secret containing the Redis ACL password. |
usernameSecretRefrequired | object | UsernameSecretRef references a Secret containing the Redis ACL username. |
spec.embeddedAuthServer.storage.redis.aclUserConfig.passwordSecretRef
PasswordSecretRef references a Secret containing the Redis ACL password.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.storage.redis.aclUserConfig.usernameSecretRef
UsernameSecretRef references a Secret containing the Redis ACL username.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.storage.redis.sentinelConfig
SentinelConfig holds Redis Sentinel configuration.
| Field | Type | Description |
|---|---|---|
db | integer | DB is the Redis database number. default 0 · format int32 |
masterNamerequired | string | 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. |
spec.embeddedAuthServer.storage.redis.sentinelConfig.sentinelService
SentinelService enables automatic discovery from a Kubernetes Service. Mutually exclusive with SentinelAddrs.
| Field | Type | Description |
|---|---|---|
namerequired | string | Name of the Sentinel Service. |
namespace | string | Namespace of the Sentinel Service (defaults to same namespace). |
port | integer | Port of the Sentinel service. default 26379 · format int32 |
spec.embeddedAuthServer.storage.redis.sentinelTls
SentinelTLS configures TLS for connections to Sentinel instances. Presence of this field enables TLS. Omit to use plaintext. When omitted, sentinel connections use plaintext (no fallback to TLS config).
| Field | Type | Description |
|---|---|---|
caCertSecretRef | object | CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used. |
insecureSkipVerify | boolean | InsecureSkipVerify skips TLS certificate verification. Use when connecting to services with self-signed certificates. |
spec.embeddedAuthServer.storage.redis.sentinelTls.caCertSecretRef
CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.storage.redis.tls
TLS configures TLS for connections to the Redis/Valkey master. Presence of this field enables TLS. Omit to use plaintext.
| Field | Type | Description |
|---|---|---|
caCertSecretRef | object | CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used. |
insecureSkipVerify | boolean | InsecureSkipVerify skips TLS certificate verification. Use when connecting to services with self-signed certificates. |
spec.embeddedAuthServer.storage.redis.tls.caCertSecretRef
CACertSecretRef references a Secret containing a PEM-encoded CA certificate for verifying the server. When not specified, system root CAs are used.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.tokenLifespans
TokenLifespans configures the duration that various tokens are valid. If not specified, defaults are applied (access: 1h, refresh: 7d, authCode: 10m).
| Field | Type | Description |
|---|---|---|
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))+$ |
spec.embeddedAuthServer.upstreamProviders[]
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.
| Field | Type | Description |
|---|---|---|
namerequired | string | 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 1 · maxLength 63 |
oauth2Config | object | OAuth2Config contains OAuth 2.0-specific configuration. Required when Type is "oauth2", must be nil when Type is "oidc". |
oidcConfig | object | OIDCConfig contains OIDC-specific configuration. Required when Type is "oidc", must be nil when Type is "oauth2". |
typerequired | string | Type specifies the provider type: "oidc" or "oauth2" enum: oidc | oauth2 |
spec.embeddedAuthServer.upstreamProviders.oauth2Config
OAuth2Config contains OAuth 2.0-specific configuration. Required when Type is "oauth2", must be nil when Type is "oidc".
| Field | Type | Description |
|---|---|---|
additionalAuthorizationParams | map<string, string> | 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. |
authorizationEndpointrequired | string | AuthorizationEndpoint is the URL for the OAuth authorization endpoint. pattern ^https?://.*$ |
clientIdrequired | string | 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. |
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. |
tokenEndpointrequired | string | 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. |
userInforequired | object | UserInfo contains configuration for fetching user information from the upstream provider. Required for OAuth2 providers to resolve user identity. |
spec.embeddedAuthServer.upstreamProviders.oauth2Config.clientSecretRef
ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret. Optional for public clients using PKCE instead of client secret.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.upstreamProviders.oauth2Config.tokenResponseMapping
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.
| Field | Type | Description |
|---|---|---|
accessTokenPathrequired | string | 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". |
spec.embeddedAuthServer.upstreamProviders.oauth2Config.userInfo
UserInfo contains configuration for fetching user information from the upstream provider. Required for OAuth2 providers to resolve user identity.
| Field | Type | Description |
|---|---|---|
additionalHeaders | map<string, string> | AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header). |
endpointUrlrequired | string | 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"). |
httpMethod | string | HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET. enum: GET | POST |
spec.embeddedAuthServer.upstreamProviders.oauth2Config.userInfo.fieldMapping
FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").
| Field | Type | Description |
|---|---|---|
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"] |
spec.embeddedAuthServer.upstreamProviders.oidcConfig
OIDCConfig contains OIDC-specific configuration. Required when Type is "oidc", must be nil when Type is "oauth2".
| Field | Type | Description |
|---|---|---|
additionalAuthorizationParams | map<string, string> | 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. |
clientIdrequired | string | 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. |
issuerUrlrequired | string | 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. |
spec.embeddedAuthServer.upstreamProviders.oidcConfig.clientSecretRef
ClientSecretRef references a Kubernetes Secret containing the OAuth 2.0 client secret. Optional for public clients using PKCE instead of client secret.
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.embeddedAuthServer.upstreamProviders.oidcConfig.userInfoOverride
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.
| Field | Type | Description |
|---|---|---|
additionalHeaders | map<string, string> | AdditionalHeaders contains extra headers to include in the userinfo request. Useful for providers that require specific headers (e.g., GitHub's Accept header). |
endpointUrlrequired | string | 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"). |
httpMethod | string | HTTPMethod is the HTTP method to use for the userinfo request. If not specified, defaults to GET. enum: GET | POST |
spec.embeddedAuthServer.upstreamProviders.oidcConfig.userInfoOverride.fieldMapping
FieldMapping contains custom field mapping configuration for non-standard providers. If nil, standard OIDC field names are used ("sub", "name", "email").
| Field | Type | Description |
|---|---|---|
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"] |
spec.headerInjection
HeaderInjection configures custom HTTP header injection Only used when Type is "headerInjection"
| Field | Type | Description |
|---|---|---|
headerNamerequired | string | HeaderName is the name of the HTTP header to inject minLength 1 |
valueSecretRefrequired | object | ValueSecretRef references a Kubernetes Secret containing the header value |
spec.headerInjection.valueSecretRef
ValueSecretRef references a Kubernetes Secret containing the header value
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.tokenExchange
TokenExchange configures RFC-8693 OAuth 2.0 Token Exchange Only used when Type is "tokenExchange"
| Field | Type | Description |
|---|---|---|
audiencerequired | string | 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) |
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))?$ |
tokenUrlrequired | string | TokenURL is the OAuth 2.0 token endpoint URL for token exchange |
spec.tokenExchange.clientSecretRef
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)
| Field | Type | Description |
|---|---|---|
keyrequired | string | Key is the key within the secret |
namerequired | string | Name is the name of the secret |
spec.upstreamInject
UpstreamInject configures upstream token injection for backend requests. Only used when Type is "upstreamInject".
| Field | Type | Description |
|---|---|---|
providerNamerequired | string | ProviderName is the name of the upstream IDP provider whose access token should be injected as the Authorization: Bearer header. minLength 1 |
status
MCPExternalAuthConfigStatus defines the observed state of MCPExternalAuthConfig
| Field | Type | Description |
|---|---|---|
conditions | object[] | Conditions represent the latest available observations of the MCPExternalAuthConfig's state |
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 |
referencingWorkloads | object[] | ReferencingWorkloads is a list of workload resources that reference this MCPExternalAuthConfig. Each entry identifies the workload by kind and name. |
status.conditions[]
Conditions represent the latest available observations of the MCPExternalAuthConfig's state
| Field | Type | Description |
|---|---|---|
lastTransitionTimerequired | string | 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 |
messagerequired | string | 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 int64 · min 0 |
reasonrequired | string | 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 1 · maxLength 1024 |
statusrequired | string | status of the condition, one of True, False, Unknown. enum: True | False | Unknown |
typerequired | string | 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 |
status.referencingWorkloads[]
ReferencingWorkloads is a list of workload resources that reference this MCPExternalAuthConfig. Each entry identifies the workload by kind and name.
| Field | Type | Description |
|---|---|---|
kindrequired | string | Kind is the type of workload resource enum: MCPServer | VirtualMCPServer | MCPRemoteProxy |
namerequired | string | Name is the name of the workload resource minLength 1 |
Related resources
Referenced by:
- MCPRemoteProxy - via
spec.authServerRef,spec.externalAuthConfigRef - MCPServer - via
spec.authServerRef,spec.externalAuthConfigRef - MCPServerEntry - via
spec.externalAuthConfigRef - VirtualMCPServer - via
spec.outgoingAuth.default.externalAuthConfigRef,status.discoveredBackends[].authConfigRef