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.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.requests_per_second	float64	100	AUTHPLANE_RATE_LIMIT_RPS	—

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.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.require_scope	bool	true	AUTHPLANE_OAUTH_REQUIRE_SCOPE	RequireScope rejects authorize requests missing the scope parameter with invalid_scope (RFC 6749 §3.3 compliant). When false, missing scope defaults to all registered scopes for the resource (ADR-012).

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 Required when oidc is enabled.
oidc.client_secret_env	string	—	—	env var name for client_secret (takes precedence over client_secret)
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	show password form when OIDC is enabled (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	false	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	false	AUTHPLANE_DPOP_ENABLED	enable DPoP support (default: false)
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	false	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	—	—	—
xaa.jwks_cache_ttl	duration	—	—	JWKS cache TTL (default: 1h)
xaa.max_assertion_age	duration	—	—	Max age of ID-JAG iat (default: 5m)
xaa.require_resource	bool	—	—	Require resource claim in assertions (default: false)
xaa.subject_mode	string	—	—	"auto_map" or "strict" (default: "auto_map")
xaa.token_expiry	duration	—	—	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.