configuration.md

Configuration Reference

Authplane reads its configuration from a single YAML file (typically /etc/authserver/config.yaml). Every leaf key documented below can be overridden by an AUTHPLANE_* environment variable — see the environment variables reference for the complete mapping and precedence rules. Defaults shown in the tables come straight from DefaultConfig() in internal/config/loader.go; a — means the field has no built-in default and must be supplied by YAML, env var, or (for secrets) the referenced env-var helper. Required-when conditions come from Validate() in internal/config/validate.go.

Sections

• server
• storage
• signing
• dcr
• cimd
• session
• rate_limit
• admin
• oauth
• oidc
• observability
• resources
• broker_providers
• data_encryption
• client_credentials
• dpop
• token_exchange
• agents
• connect
• xaa
• client_secret_pepper

server

ServerConfig contains the main HTTP server settings.

Key	Type	Default	Env var	Notes
server.address	string	:9000	AUTHPLANE_SERVER_ADDRESS	—
server.allowed_origins	[]string	—	AUTHPLANE_SERVER_ALLOWED_ORIGINS	CORS allowed origins (empty = no CORS)
server.idle_timeout	duration	120s	AUTHPLANE_SERVER_IDLE_TIMEOUT	—
server.issuer	string	http://localhost:9000	AUTHPLANE_SERVER_ISSUER	—
server.read_timeout	duration	30s	AUTHPLANE_SERVER_READ_TIMEOUT	—
server.shutdown_wait	duration	10s	AUTHPLANE_SERVER_SHUTDOWN_WAIT	—
server.write_timeout	duration	30s	AUTHPLANE_SERVER_WRITE_TIMEOUT	—

storage

StorageConfig selects and configures the storage backend.

Key	Type	Default	Env var	Notes
storage.driver	string	sqlite	AUTHPLANE_STORAGE_DRIVER	"sqlite" or "postgres"
storage.postgres.dsn	string	—	AUTHPLANE_STORAGE_POSTGRES_DSN	Required when driver is postgres.
storage.postgres.max_conn_idle_time	duration	30m	AUTHPLANE_STORAGE_POSTGRES_MAX_CONN_IDLE_TIME	—
storage.postgres.max_conn_lifetime	duration	1h	AUTHPLANE_STORAGE_POSTGRES_MAX_CONN_LIFETIME	—
storage.postgres.max_conns	int	25	AUTHPLANE_STORAGE_POSTGRES_MAX_CONNS	—
storage.postgres.min_conns	int	5	AUTHPLANE_STORAGE_POSTGRES_MIN_CONNS	—
storage.sqlite.path	string	data/authserver.db	AUTHPLANE_STORAGE_SQLITE_PATH	Required when driver is sqlite.
storage.sqlite.wal	bool	true	AUTHPLANE_STORAGE_SQLITE_WAL	—

signing

SigningConfig controls JWT signing key generation and storage.

Key	Type	Default	Env var	Notes
signing.algorithm	string	ES256	AUTHPLANE_SIGNING_ALGORITHM	"ES256" or "RS256"
signing.key_path	string	data/keys	AUTHPLANE_SIGNING_KEY_PATH	path for keyfile store Required when key_store is keyfile.
signing.key_store	string	keyfile	AUTHPLANE_SIGNING_KEY_STORE	"keyfile" (default), "vault_transit", or "postgres_key"
signing.postgres_key.encryption_key_env	string	—	AUTHPLANE_SIGNING_PG_ENCRYPTION_KEY_ENV	EncryptionKeyEnv is the env var name for the key encryption key. Only relevant when data_encryption.driver is aes_master. The actual encryption uses the DataEncryptor port configured at the top level.
signing.vault_transit.address	string	—	AUTHPLANE_VAULT_ADDR	Vault server address, e.g. "https://vault:8200" Required when key_store is vault_transit.
signing.vault_transit.approle.mount	string	—	AUTHPLANE_VAULT_APPROLE_MOUNT	auth mount, default "approle"
signing.vault_transit.approle.role_id	string	—	AUTHPLANE_VAULT_APPROLE_ROLE_ID	—
signing.vault_transit.approle.secret_id	string	—	AUTHPLANE_VAULT_APPROLE_SECRET_ID	Required when role_id is set.
signing.vault_transit.key_name	string	authserver-signing	AUTHPLANE_VAULT_TRANSIT_KEY_NAME	transit key name, default "authserver-signing"
signing.vault_transit.mount	string	transit	AUTHPLANE_VAULT_TRANSIT_MOUNT	transit engine mount path, default "transit"
signing.vault_transit.timeout	duration	10s	AUTHPLANE_VAULT_TIMEOUT	HTTP request timeout, default 10s
signing.vault_transit.token	string	—	AUTHPLANE_VAULT_TOKEN	static Vault token (mutually exclusive with AppRole)

dcr

DCRConfig controls Dynamic Client Registration behavior.

Key	Type	Default	Env var	Notes
dcr.approved_redirects	[]string	—	AUTHPLANE_DCR_APPROVED_REDIRECTS	—
dcr.default_refresh_expiry	duration	168h	AUTHPLANE_DCR_DEFAULT_REFRESH_EXPIRY	—
dcr.default_token_expiry	duration	15m	AUTHPLANE_DCR_DEFAULT_TOKEN_EXPIRY	—
dcr.mode	string	open	AUTHPLANE_DCR_MODE	"open", "approved_redirects", "admin_only"
dcr.rate_limit	float64	10	AUTHPLANE_DCR_RATE_LIMIT	—
dcr.rate_limit_burst	int	20	AUTHPLANE_DCR_RATE_LIMIT_BURST	—

cimd

CIMDConfig controls Client ID Metadata Document handling.

Key	Type	Default	Env var	Notes
cimd.allow_private_addresses	bool	false	AUTHPLANE_CIMD_ALLOW_PRIVATE_ADDRESSES	AllowPrivateAddresses turns off SSRF address filtering for CIMD document fetches, at both the URL check and the dial. Local development only: with it set, a document URL may resolve to loopback, RFC 1918 space or the cloud metadata endpoint. Validate refuses it unless server.issuer is localhost, so it cannot be left on in a deployment.
cimd.cache_ttl	duration	1h	AUTHPLANE_CIMD_CACHE_TTL	—
cimd.enabled	bool	true	AUTHPLANE_CIMD_ENABLED	—
cimd.fetch_timeout	duration	10s	AUTHPLANE_CIMD_FETCH_TIMEOUT	—
cimd.require_https	bool	true	AUTHPLANE_CIMD_REQUIRE_HTTPS	—

session

SessionConfig controls user session cookies.

Key	Type	Default	Env var	Notes
session.cookie_name	string	authserver_session	AUTHPLANE_SESSION_COOKIE_NAME	—
session.fail_closed	bool	true	AUTHPLANE_SESSION_FAIL_CLOSED	FailClosed controls the session middleware's behavior on transient user-store lookup errors. When true (default since the 2026-05-18 follow-up audit), any lookup error rejects the cookie — disabled accounts cannot ride a transient DB outage. Set to false to restore the pre-2026-05 behavior where DB blips keep sessions valid; do this only when availability concerns outweigh revocation freshness.
session.max_age	duration	24h	AUTHPLANE_SESSION_MAX_AGE	—
session.same_site	string	lax	AUTHPLANE_SESSION_SAME_SITE	"lax", "strict", "none"
session.secret	string	—	AUTHPLANE_SESSION_SECRET	Required when server.issuer is not localhost.
session.secure	bool	false	AUTHPLANE_SESSION_SECURE	—

rate_limit

RateLimitConfig controls global rate limiting.

Key	Type	Default	Env var	Notes
rate_limit.auth_fail_max	int	10	AUTHPLANE_RATE_LIMIT_AUTH_FAIL_MAX	—
rate_limit.auth_fail_window	duration	10m	AUTHPLANE_RATE_LIMIT_AUTH_FAIL_WINDOW	—
rate_limit.auth_lockout	duration	15m	AUTHPLANE_RATE_LIMIT_AUTH_LOCKOUT	—
rate_limit.burst	int	200	AUTHPLANE_RATE_LIMIT_BURST	—
rate_limit.enabled	bool	true	AUTHPLANE_RATE_LIMIT_ENABLED	—
rate_limit.max_tracked_identities	int	250000	AUTHPLANE_RATE_LIMIT_MAX_TRACKED_IDENTITIES	MaxTrackedIdentities bounds how many identities the auth-failure lockout holds at once. Its key space is caller-chosen — anyone posting the login form can mint entries with made-up addresses — so at the bound the lockout evicts an entry that is not currently locked rather than refusing the newcomer, so a flood of invented addresses cannot leave an untouched account unprotected; lockouts already in force are never evicted. Only when every tracked identity is locked is a newcomer refused. Raise it alongside auth_fail_window, which scales the live set linearly. This bounds the NUMBER of entries. Each one is bounded separately, by the 254-byte cap on the identity — without that, a count-only bound would say 41 MB and admit 16 GB.
rate_limit.requests_per_second	float64	100	AUTHPLANE_RATE_LIMIT_RPS	RequestsPerSecond is the per-source-address token-refill rate. It must be greater than zero: x/time/rate reads Limit(0) as "never refill", so a zero here does not disable the limiter — it lets each address spend Burst and then denies it for the process lifetime. Validate rejects it. Turn throughput limiting off with Enabled: false.

admin

AdminConfig controls the admin API server.

Key	Type	Default	Env var	Notes
admin.address	string	:9001	AUTHPLANE_ADMIN_ADDRESS	—
admin.api_key	string	—	AUTHPLANE_ADMIN_API_KEY	Required when admin is enabled and server.issuer is not localhost.
admin.audit_default_lookback	duration	24h	AUTHPLANE_ADMIN_AUDIT_DEFAULT_LOOKBACK	AuditDefaultLookback is how far back GET /admin/audit reaches when the caller omits since. AuditMaxLookback is the furthest back a caller may ask; a request beyond it is rejected rather than silently narrowed, so a client is never handed a short answer to a long question. audit_events is the highest-volume table in the schema, and the feed pages on offset, so both bounds exist to stop one request walking all of it. They are here, and not constants, because only the deployment knows its compliance window: an operator retaining a year of audit for an exporter raises audit_max_lookback rather than losing reach over its own data.
admin.audit_max_lookback	duration	720h	AUTHPLANE_ADMIN_AUDIT_MAX_LOOKBACK	—
admin.burst	int	—	—	Burst size for rate limiter
admin.enabled	bool	true	AUTHPLANE_ADMIN_ENABLED	—
admin.requests_per_second	float64	—	—	Per-IP rate limit (0 = no limit)

oauth

OAuthConfig controls OAuth authorization server behavior.

Key	Type	Default	Env var	Notes
oauth.default_client_scope	string	—	AUTHPLANE_OAUTH_DEFAULT_CLIENT_SCOPE	DefaultClientScope is the space-separated scope ceiling assigned to clients created through dynamic registration (DCR) and CIMD, and only to those whose grants all keep a user in the loop. Neither door lets a client state its own ceiling — the registration request and the metadata document have no scope field — so the server supplies one; RFC 7591 §2 permits registering a client with a default scope set. Leaving it empty keeps the pre-v0.2.0 behavior: those clients are created without a ceiling, and /oauth/authorize bounds their requests by the resource catalog alone rather than refusing them. That is a deprecation window, not the end state — from v0.3.0 a client with no ceiling is refused with invalid_scope. The server warns at startup, and the admin UI carries a notice, while the value is empty and dcr.mode leaves registration open.
oauth.require_scope	bool	true	AUTHPLANE_OAUTH_REQUIRE_SCOPE	RequireScope rejects authorize requests missing the scope parameter with invalid_scope. When false, missing scope is processed using a pre-defined default value: all scopes registered for the resource. RFC 6749 §3.3 requires the server to do one or the other — "either process the request using a pre-defined default value or fail the request indicating an invalid scope" — so both settings are conformant and this flag picks between them. Defaults to true.
oauth.state_max_age	duration	10m	AUTHPLANE_OAUTH_STATE_MAX_AGE	StateMaxAge bounds the OIDC state cookie's lifetime: both the cookie's Max-Age attribute and the server-side freshness window checked at callback. Default 10m. A shorter value tightens the state replay window (regulatory or UX driven, per deployment).

oidc

OIDCConfig controls upstream OIDC federation (single provider, OSS).

Key	Type	Default	Env var	Notes
oidc.client_id	string	—	AUTHPLANE_OIDC_CLIENT_ID	client_id registered with upstream IdP Required when oidc is enabled.
oidc.client_secret	string	—	AUTHPLANE_OIDC_CLIENT_SECRET	client_secret registered with upstream IdP
oidc.client_secret_env	string	—	—	DEPRECATED: pre-v0.1.2 name for client_secret_ref; normalized into ClientSecretRef at load time. Also marks the ref as legacy-sourced, which exempts it from the CONNECTOR_/AUTHPLANE_VAULT_ naming rule. Remove in a future release.
oidc.client_secret_ref	string	—	—	env var name for client_secret (mutually exclusive with client_secret; set only one)
oidc.connector_id	string	—	AUTHPLANE_OIDC_CONNECTOR_ID	Dex connector_id parameter (optional)
oidc.display_name	string	—	AUTHPLANE_OIDC_DISPLAY_NAME	button text, e.g. "Okta", "Google"
oidc.enabled	bool	—	AUTHPLANE_OIDC_ENABLED	—
oidc.include_groups_scope	bool	true	AUTHPLANE_OIDC_INCLUDE_GROUPS_SCOPE	auto-include "groups" scope if upstream supports it (default true)
oidc.issuer	string	—	AUTHPLANE_OIDC_ISSUER	upstream issuer URL (e.g., https://accounts.google.com) Required when oidc is enabled.
oidc.redirect_uri	string	—	AUTHPLANE_OIDC_REDIRECT_URI	explicit redirect_uri for OIDC callback Required when oidc is enabled.
oidc.scopes	[]string	—	AUTHPLANE_OIDC_SCOPES	OIDC scopes; defaults to ["openid","email","profile"]
oidc.show_local_login	bool	true	AUTHPLANE_OIDC_SHOW_LOCAL_LOGIN	local password login: false hides the form and POST /login answers 404 (default true)

observability

ObservabilityConfig controls logging, tracing, and metrics.

Key	Type	Default	Env var	Notes
observability.logging.add_source	bool	—	AUTHPLANE_LOG_ADD_SOURCE	—
observability.logging.format	string	json	AUTHPLANE_LOG_FORMAT	"json", "text"
observability.logging.level	string	info	AUTHPLANE_LOG_LEVEL	"debug", "info", "warn", "error"
observability.logging.outputs.insecure	bool	—	AUTHPLANE_LOG_OTEL_INSECURE	Allow insecure gRPC for OTel logs
observability.logging.outputs.otel	bool	—	AUTHPLANE_LOG_OTEL	Export logs via OTLP to OTel collector
observability.logging.outputs.otel_endpoint	string	—	AUTHPLANE_LOG_OTEL_ENDPOINT	OTLP gRPC endpoint for log export Required when logging outputs otel is enabled.
observability.logging.outputs.stdout	bool	true	AUTHPLANE_LOG_STDOUT	Structured logs to stdout (default true)
observability.metrics.insecure	bool	—	AUTHPLANE_METRICS_INSECURE	Allow insecure gRPC for OTel metrics
observability.metrics.otel_endpoint	string	—	AUTHPLANE_METRICS_OTEL_ENDPOINT	OTLP endpoint when provider=otel Required when metrics provider is otel or both.
observability.metrics.path	string	/metrics	AUTHPLANE_METRICS_PATH	Prometheus scrape endpoint path
observability.metrics.provider	string	prometheus	AUTHPLANE_METRICS_PROVIDER	"prometheus", "otel", "none"
observability.tracing.enabled	bool	false	AUTHPLANE_TRACING_ENABLED	—
observability.tracing.endpoint	string	—	AUTHPLANE_TRACING_ENDPOINT	Required when tracing is enabled.
observability.tracing.insecure	bool	—	AUTHPLANE_TRACING_INSECURE	—
observability.tracing.sample_rate	float64	1.0	AUTHPLANE_TRACING_SAMPLE_RATE	—

resources

ResourceConfigUnified describes a Mint or Broker resource for the seed loop. Mirrors the admin API's POST /admin/resources DTO with one operator-friendly addition: BrokerProviderSlug is a YAML-only alias for BrokerProviderID, resolved at seed-time so operators don't have to copy UUIDs across the broker_providers: and resources: YAML sections.

Key	Type	Default	Env var	Notes
resources	[]ResourceConfigUnified	—	—	—

broker_providers

BrokerProviderConfig describes an upstream OAuth (or other protocol) provider that Broker Resources reference. Mirrors the admin API's POST /admin/broker-providers DTO. ConfigData is adapter-shaped JSON; the brokerproto adapter validates the schema lazily at first vend.

Key	Type	Default	Env var	Notes
broker_providers	[]BrokerProviderConfig	—	—	—

data_encryption

DataEncryptionConfig controls how sensitive data is encrypted at rest.

Key	Type	Default	Env var	Notes
data_encryption.aes_master.key_env	string	—	AUTHPLANE_DATA_ENCRYPTION_KEY_ENV	KeyEnv is the name of the env var containing the 64-hex-char (32-byte) master key.
data_encryption.aes_master.old_key_env	string	—	—	OldKeyEnv is the name of the env var containing the previous master key (decrypt-only fallback). Used during key rotation: set both key_env (new) and old_key_env (old), run re-encrypt, then remove old_key_env.
data_encryption.driver	string	—	AUTHPLANE_DATA_ENCRYPTION_DRIVER	"aes_master" or "vault_transit_encrypt"
data_encryption.vault_transit_encrypt.address	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_ADDRESS	Vault address (e.g. https://vault:8200) Required when driver is vault_transit_encrypt.
data_encryption.vault_transit_encrypt.approle.role_id_env	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_ROLE_ID_ENV	Required when auth_method is approle.
data_encryption.vault_transit_encrypt.approle.secret_id_env	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_SECRET_ID_ENV	Required when auth_method is approle.
data_encryption.vault_transit_encrypt.auth_method	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_AUTH_METHOD	"token" or "approle"
data_encryption.vault_transit_encrypt.key_name	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_KEY_NAME	Transit key name Required when driver is vault_transit_encrypt.
data_encryption.vault_transit_encrypt.mount_path	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_MOUNT_PATH	Transit mount path (default: "transit")
data_encryption.vault_transit_encrypt.token_env	string	—	AUTHPLANE_DATA_ENCRYPTION_VAULT_TOKEN_ENV	Env var for Vault token

client_credentials

ClientCredentialsConfig controls the client_credentials grant (RFC 6749 §4.4).

Key	Type	Default	Env var	Notes
client_credentials.enabled	bool	true	AUTHPLANE_CLIENT_CREDENTIALS_ENABLED	—
client_credentials.token_expiry	duration	1h	AUTHPLANE_CLIENT_CREDENTIALS_TOKEN_EXPIRY	machine token TTL (default: 1h)

dpop

DPoPConfig controls DPoP proof-of-possession (RFC 9449).

Key	Type	Default	Env var	Notes
dpop.enabled	bool	true	AUTHPLANE_DPOP_ENABLED	enable DPoP support (default: true; support only — a client that sends no proof still receives a bearer token)
dpop.nonce_ttl	duration	60s	AUTHPLANE_DPOP_NONCE_TTL	TTL for server-issued nonces (default: 60s)
dpop.proof_lifetime	duration	60s	AUTHPLANE_DPOP_PROOF_LIFETIME	max |now - iat| for proof freshness (default: 60s)
dpop.require_nonce	bool	—	AUTHPLANE_DPOP_REQUIRE_NONCE	when true, all DPoP proofs must include server nonce (default: false)

token_exchange

TokenExchangeConfig controls RFC 8693 token exchange.

Key	Type	Default	Env var	Notes
token_exchange.allow_self_exchange	bool	—	AUTHPLANE_TOKEN_EXCHANGE_ALLOW_SELF_EXCHANGE	when true, client may exchange its own token for narrower scope (default: false)
token_exchange.enabled	bool	true	AUTHPLANE_TOKEN_EXCHANGE_ENABLED	—
token_exchange.max_chain_depth	int	5	AUTHPLANE_TOKEN_EXCHANGE_MAX_CHAIN_DEPTH	maximum delegation chain depth (required when enabled, 1-10)
token_exchange.token_expiry	duration	1h	AUTHPLANE_TOKEN_EXCHANGE_TOKEN_EXPIRY	TTL for exchanged tokens (required when enabled)

agents

AgentsConfig controls agent identity features (Authplane extension).

Key	Type	Default	Env var	Notes
agents.enable_jwks_listing	bool	—	AUTHPLANE_AGENTS_ENABLE_JWKS_LISTING	expose agent list in JWKS endpoint (privacy: exposes client IDs publicly, default: false)

connect

ConnectConfig controls the upstream-connection OAuth connect flow.

Key	Type	Default	Env var	Notes
connect.allowed_return_urls	[]string	—	AUTHPLANE_CONNECT_ALLOWED_RETURN_URLS	—
connect.redirect_base_url	string	—	AUTHPLANE_CONNECT_REDIRECT_BASE_URL	Base URL for OAuth callbacks
connect.state_secret	string	—	AUTHPLANE_CONNECT_STATE_SECRET	HMAC key for state tokens (required, min 32 chars)

xaa

XAAConfig controls Enterprise-Managed Authorization (Cross App Access).

Key	Type	Default	Env var	Notes
xaa.enabled	bool	true	AUTHPLANE_XAA_ENABLED	—
xaa.jwks_cache_ttl	duration	1h	AUTHPLANE_XAA_JWKS_CACHE_TTL	JWKS cache TTL (default: 1h)
xaa.max_assertion_age	duration	5m	AUTHPLANE_XAA_MAX_ASSERTION_AGE	Max age of ID-JAG iat (default: 5m)
xaa.require_resource	bool	false	AUTHPLANE_XAA_REQUIRE_RESOURCE	Refuse exchanges that name no resource, on the assertion or the request (default: false)
xaa.subject_mode	string	auto_map	AUTHPLANE_XAA_SUBJECT_MODE	"auto_map" or "strict" (default: "auto_map")
xaa.token_expiry	duration	1h	AUTHPLANE_XAA_TOKEN_EXPIRY	TTL for XAA-issued access tokens (default: 1h)

client_secret_pepper

Key	Type	Default	Env var	Notes
client_secret_pepper	string	—	AUTHPLANE_CLIENT_SECRET_PEPPER	ClientSecretPepper is the HMAC key for client-secret hashing. When non-empty, client secrets are hashed/verified with HMAC-SHA256 instead of bcrypt; empty keeps bcrypt (the default). User passwords are unaffected. Env: AUTHPLANE_CLIENT_SECRET_PEPPER.