AuthServerConfig configures an embedded OAuth authorization server.
When set, the vMCP server acts as an OIDC issuer, drives users through
upstream IDPs, and issues ToolHive JWTs. The embedded AS becomes the
IncomingAuth OIDC provider — its issuer must match IncomingAuth.OIDCConfigRef
so that tokens it issues are accepted by the vMCP's incoming auth middleware.
When nil, IncomingAuth uses an external IDP and behavior is unchanged.
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).
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?#]$
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).
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 required
UsernameSecretRef references a Secret containing the Redis ACL username.
key
string required
Key is the key within the secret
name
string required
Name is the name of the secret
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 required
SentinelConfig holds Redis Sentinel configuration.
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: int32
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).
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.
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, redis
tokenLifespans
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: 1
maxLength: 63
oauth2Config
object
OAuth2Config contains OAuth 2.0-specific configuration.
Required when Type is "oauth2", must be nil when Type is "oidc".
authorizationEndpoint
string required
AuthorizationEndpoint is the URL for the OAuth authorization endpoint.
pattern: ^https?://.*$
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
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.
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 required
UserInfo contains configuration for fetching user information from the upstream provider.
Required for OAuth2 providers to resolve user identity.
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
oidcConfig
object
OIDCConfig contains OIDC-specific configuration.
Required when Type is "oidc", must be nil when Type is "oauth2".
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"].
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, oauth2