Configuration

Thunder's behavior is controlled by a combination of default configurations and deployment-specific overrides. This page covers all available configuration options and how to customize them.

Configuration System

Thunder uses a two-tier configuration system:

1. Default Configuration — Provides sensible defaults for all settings. These are built into Thunder.
2. Deployment Configuration — Located at repository/conf/deployment.yaml in your Thunder installation directory. This file overrides specific defaults for your deployment.

note

Only settings you want to override need to be specified in deployment.yaml. All other values will use the built-in defaults.

tip

Thunder must be restarted after any configuration change.

Server Configuration

Controls the Thunder server's network settings and identity.

Setting	Default	Description
server.hostname	localhost	The hostname or IP address the server binds to
server.port	8090	Port the server listens on
server.http_only	false	If true, disables HTTPS and uses HTTP only (not recommended for production)
server.identifier	default-deployment	Unique identifier for this deployment instance

Gate Client Configuration

Configures the connection to Thunder Gate (the login UI).

Setting	Default	Description
gate_client.hostname	localhost	The hostname where Thunder Gate is hosted
gate_client.port	8090	Port where Thunder Gate is accessible
gate_client.scheme	https	Protocol scheme (http or https)
gate_client.path	/gate	Base path for Thunder Gate

TLS Configuration

Controls HTTPS/TLS settings for secure communication.

Setting	Default	Description
tls.min_version	1.3	Minimum TLS version to accept (1.2 or 1.3)
tls.cert_file	repository/resources/security/server.cert	Path to TLS certificate file
tls.key_file	repository/resources/security/server.key	Path to TLS private key file

Self-Signed Certificate

Thunder ships with a self-signed certificate for local development at repository/resources/security/server.cert. For production, replace it with a certificate from a trusted Certificate Authority.

Database Configuration

Thunder uses three separate databases for different purposes. Each database can be configured independently.

Connection parameters are grouped under a type-specific sub-key (postgres, sqlite, or redis). Only type is a top-level field; all other settings belong under the matching sub-key.

Config Database

Stores identity provider configurations, applications, and authentication flows.

Setting	Default	Description
database.config.type	sqlite	Database type (sqlite or postgres)

database.config.postgres.* — only read when database.config.type: postgres:

Setting	Default	Description
database.config.postgres.hostname	""	Database server hostname
database.config.postgres.port	0	Database server port
database.config.postgres.name	""	Database name
database.config.postgres.username	""	Database username
database.config.postgres.password	""	Database password
database.config.postgres.sslmode	""	SSL mode (disable, require, verify-ca, verify-full)
database.config.postgres.max_open_conns	500	Maximum number of open connections
database.config.postgres.max_idle_conns	100	Maximum number of idle connections
database.config.postgres.conn_max_lifetime	3600	Maximum connection lifetime in seconds

database.config.sqlite.* — only read when database.config.type: sqlite:

Setting	Default	Description
database.config.sqlite.path	repository/database/configdb.db	SQLite database file path
database.config.sqlite.options	_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)	SQLite connection options
database.config.sqlite.max_open_conns	500	Maximum number of open connections
database.config.sqlite.max_idle_conns	100	Maximum number of idle connections
database.config.sqlite.conn_max_lifetime	3600	Maximum connection lifetime in seconds

Runtime Database

Stores runtime data like sessions, tokens, and temporary data. The runtime database supports three backend types: sqlite, postgres, and redis.

Setting	Default	Description
database.runtime.type	sqlite	Database type (sqlite, postgres, or redis)

database.runtime.postgres.* — only read when database.runtime.type: postgres:

Setting	Default	Description
database.runtime.postgres.hostname	""	Database server hostname
database.runtime.postgres.port	0	Database server port
database.runtime.postgres.name	""	Database name
database.runtime.postgres.username	""	Database username
database.runtime.postgres.password	""	Database password
database.runtime.postgres.sslmode	""	SSL mode (disable, require, verify-ca, verify-full)
database.runtime.postgres.max_open_conns	500	Maximum number of open connections
database.runtime.postgres.max_idle_conns	100	Maximum number of idle connections
database.runtime.postgres.conn_max_lifetime	3600	Maximum connection lifetime in seconds

database.runtime.sqlite.* — only read when database.runtime.type: sqlite:

Setting	Default	Description
database.runtime.sqlite.path	repository/database/runtimedb.db	SQLite database file path
database.runtime.sqlite.options	_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)	SQLite connection options
database.runtime.sqlite.max_open_conns	500	Maximum number of open connections
database.runtime.sqlite.max_idle_conns	100	Maximum number of idle connections
database.runtime.sqlite.conn_max_lifetime	3600	Maximum connection lifetime in seconds

database.runtime.redis.* — only read when database.runtime.type: redis:

Setting	Default	Description
database.runtime.redis.address	""	Redis server address in host:port format, for example localhost:6379
database.runtime.redis.username	""	Redis ACL username — leave empty if ACLs are not configured
database.runtime.redis.password	""	Redis password or ACL user password
database.runtime.redis.db	0	Redis logical database index (0–15)
database.runtime.redis.key_prefix	""	Prefix applied to all Redis keys written by Thunder, for example thunder:

Redis Connection Requirements

• Thunder requires Redis 6.0 or later.
• Thunder connects to a single Redis node. Cluster mode and Sentinel mode are not currently supported.
• The default Redis port is 6379. Ensure the port is reachable from the Thunder server.
• Thunder does not enforce TLS at the client configuration level. To encrypt traffic, place a TLS-terminating proxy in front of Redis and point database.runtime.redis.address at the proxy endpoint.
• If your Redis deployment uses Access Control Lists (ACLs), create a dedicated user and grant the following commands: GET, SET, DEL, EXPIRE, EVAL, EVALSHA. Set database.runtime.redis.username and database.runtime.redis.password accordingly.
• Thunder calls PING at startup to verify connectivity. The process terminates if the Redis server is unreachable.

User Database

Stores user profiles and credentials.

Setting	Default	Description
database.user.type	sqlite	Database type (sqlite or postgres)

database.user.postgres.* — only read when database.user.type: postgres:

Setting	Default	Description
database.user.postgres.hostname	""	Database server hostname
database.user.postgres.port	0	Database server port
database.user.postgres.name	""	Database name
database.user.postgres.username	""	Database username
database.user.postgres.password	""	Database password
database.user.postgres.sslmode	""	SSL mode (disable, require, verify-ca, verify-full)
database.user.postgres.max_open_conns	500	Maximum number of open connections
database.user.postgres.max_idle_conns	100	Maximum number of idle connections
database.user.postgres.conn_max_lifetime	3600	Maximum connection lifetime in seconds

database.user.sqlite.* — only read when database.user.type: sqlite:

Setting	Default	Description
database.user.sqlite.path	repository/database/userdb.db	SQLite database file path
database.user.sqlite.options	_journal_mode=WAL&_busy_timeout=5000&_pragma=foreign_keys(1)	SQLite connection options
database.user.sqlite.max_open_conns	500	Maximum number of open connections
database.user.sqlite.max_idle_conns	100	Maximum number of idle connections
database.user.sqlite.conn_max_lifetime	3600	Maximum connection lifetime in seconds

Cache Configuration

Thunder includes both in-memory and Redis-backed caching to improve performance.

Setting	Default	Description
cache.disabled	false	If true, disables caching entirely
cache.type	inmemory	Cache type (inmemory or redis). When cache.type is redis, Thunder does not use the periodic cleanup routine.
cache.size	1000	Maximum number of cache entries
cache.ttl	3600	Default time-to-live for cache entries in seconds
cache.eviction_policy	LRU	Cache eviction policy (LRU - Least Recently Used)
cache.cleanup_interval	300	In-memory only. Interval in seconds to clean up expired entries. Not used when cache.type is redis.
cache.properties[]	[]	Per-cache overrides for name, disabled, size, ttl, and eviction_policy
cache.redis.address	""	Redis server address in host:port format
cache.redis.username	""	Redis username
cache.redis.password	""	Redis password
cache.redis.db	0	Redis database index
cache.redis.key_prefix	thunder	Prefix added to all Redis cache keys

Cache Property Overrides

Use cache.properties when you want to override cache behavior for a specific internal cache instead of changing the global cache settings for all caches.

Each item in cache.properties supports these fields:

Field	Required	Description
name	Yes	Internal cache name to override. The value must match the cache name exactly.
disabled	No	Disables only that cache when set to true.
size	No	Maximum number of entries for that cache. This setting applies to in-memory caches only.
ttl	No	Time-to-live for that cache in seconds.
eviction_policy	No	Eviction policy for that cache. Supported values are LRU and LFU. This setting applies to in-memory caches only.

If you omit a field in a cache.properties entry, Thunder falls back to the corresponding global cache.* setting.

That means you can override only the fields you need. Thunder continues to use the global cache settings for any fields you leave unset.

Thunder currently uses cache names such as:

• ApplicationByIDCache
• ApplicationByNameCache
• OAuthAppCache
• FlowByIDCache
• FlowByHandleCache
• CertificateByIDCache
• CertificateByReferenceCache
• UserSchemaByIDCache
• UserSchemaByNameCache
• FlowGraphCache

note

FlowGraphCache is always in-memory. It caches process-local flow graph Go objects during flow execution, not shared system-level cache data.

note

When cache.type is redis, per-cache ttl and disabled remain useful. Per-cache size and eviction_policy do not affect Redis behavior because Redis manages memory and eviction independently.

Redis Cache Configuration

Set cache.type to redis and configure cache.redis.address to enable Redis-backed cache storage.

cache:
  type: "redis"
  ttl: 3600
  redis:
    address: "localhost:6379"
    username: ""
    password: ""
    db: 0
    key_prefix: "thunder"

note

When Redis caching is enabled, Thunder expires keys automatically based on TTL.

warning

If Thunder cannot connect to Redis during startup, it disables the cache layer.

JWT Configuration

Controls JWT (JSON Web Token) generation and validation.

Setting	Default	Description
jwt.validity_period	3600	Default JWT validity period in seconds (1 hour)
jwt.audience	application	Default audience claim for JWTs
jwt.preferred_key_id	default-key	Key ID to use for signing JWTs
jwt.leeway	30	Clock skew tolerance in seconds for token validation

OAuth Configuration

OAuth 2.0 and OpenID Connect settings.

Setting	Default	Description
oauth.refresh_token.renew_on_grant	false	If true, issues a new refresh token on each access token grant
oauth.refresh_token.validity_period	86400	Refresh token validity period in seconds (24 hours)
oauth.authorization_code.validity_period	600	Authorization code validity period in seconds (10 minutes)
oauth.dcr.insecure	false	If true, allows insecure dynamic client registration (development only)

Flow Configuration

Authentication and registration flow settings.

Setting	Default	Description
flow.default_auth_flow_handle	default-basic-flow	Handle of the default authentication flow
flow.user_onboarding_flow_handle	default-user-onboarding	Handle of the default user onboarding flow
flow.max_version_history	10	Maximum number of flow versions to retain
flow.auto_infer_registration	true	If true, automatically infers registration from authentication flows

User Configuration

User management settings.

Setting	Default	Description
user.indexed_attributes	["username", "email", "mobileNumber", "sub"]	User attributes that are indexed for fast lookups

Declarative Resources

Controls declarative configuration support.

Setting	Default	Description
declarative_resources.enabled	false	If true, enables declarative resource configuration

For Helm deployments, this setting is managed through declarativeResources.enabled in the Helm values. When enabled, the chart also mounts declarative resource files from either a ConfigMap or Secret into the Thunder repository/resources directory.

Example Helm values:

declarativeResources:
  enabled: true
  # Base mount path inside the Thunder container (default: /opt/thunder/repository/resources)
  mountPath: /opt/thunder/repository/resources
  # Mount as read-only (recommended)
  readOnly: true
  configMap:
    name: thunder-declarative-resources
    items:
      # Format 1 — string shorthand: key and path are the same
      - "identity_providers/google.yaml"
      # Format 2 — explicit key/path mapping
      - key: app1
        path: applications/application1.yaml
      # Format 3 — per-item mountPath override (absolute path)
      - key: org-default
        path: organization_units/default.yaml
        mountPath: /opt/thunder/repository/resources/organization_units/default.yaml

To source files from a Kubernetes Secret instead (for resources containing sensitive values):

declarativeResources:
  enabled: true
  mountPath: /opt/thunder/repository/resources
  readOnly: true
  secret:
    name: thunder-declarative-resources-secret
    items:
      - key: my-app-with-secrets
        path: applications/my-app.yaml

Templates (email and other templated content) are now supported as a declarative resource. See the templates guide for schema, examples, and the configured directory location: Template declarative resources.

Resource Configuration

Authorization resource settings.

Setting	Default	Description
resource.default_delimiter	:	Default delimiter for resource hierarchies

Observability Configuration

Monitoring and observability settings.

Setting	Default	Description
observability.enabled	false	If true, enables observability features
observability.output.console.enabled	false	If true, outputs observability data to console
observability.output.console.format	json	Console output format (json or text)
observability.output.console.categories	["observability.all"]	Observability categories to output

Crypto Configuration

Cryptographic settings for encryption and signing.

Encryption

Setting	Default	Description
crypto.encryption.key	file://repository/resources/security/crypto.key	Path to encryption key file

Password Hashing

Setting	Default	Description
crypto.password_hashing.algorithm	PBKDF2	Password hashing algorithm
crypto.password_hashing.parameters.iterations	600000	Number of hashing iterations
crypto.password_hashing.parameters.key_size	32	Derived key size in bytes
crypto.password_hashing.parameters.salt_size	16	Salt size in bytes

Signing Keys

Signing keys are configured as an array. Each key has the following properties:

Setting	Description
crypto.keys[].id	Unique identifier for the key
crypto.keys[].cert_file	Path to certificate file
crypto.keys[].key_file	Path to private key file

Default Key:

- id: "default-key"
  cert_file: "repository/resources/security/signing.cert"
  key_file: "repository/resources/security/signing.key"

The key type under crypto.keys determines the algorithm in id_token_signing_alg_values_supported in the OIDC discovery document. RSA keys advertise RS256; ECDSA P-256, P-384, and P-521 keys advertise ES256, ES384, and ES512; Ed25519 keys advertise EdDSA. If multiple keys are configured, all resulting algorithms are included without duplicates.

Email Configuration

Controls email sending capabilities (e.g., for magic link authentication, user invitations).

Setting	Default	Description
email.smtp.host	""	SMTP server hostname
email.smtp.port	0	SMTP server port (e.g., 587 for STARTTLS)
email.smtp.username	""	SMTP authentication username
email.smtp.password	""	SMTP authentication password
email.smtp.from_address	""	Sender email address
email.smtp.enable_start_tls	true	Enable STARTTLS encryption
email.smtp.enable_authentication	true	Enable SMTP authentication

Example:

email:
  smtp:
    host: "smtp.example.com"
    port: 587
    username: "yourUsername"
    password: "yourPassword"
    from_address: "yourEmail"
    enable_start_tls: true
    enable_authentication: true

note

Transport Mode: Referencing keys enable_start_tls and enable_authentication, only explicit STARTTLS is supported (set enable_start_tls: true). Implicit SMTPS (port 465) is not supported by this transport.

note

The email configuration is optional. If not provided, features that depend on email (e.g., magic link, user invitations) will not be available.

Authentication Provider Configuration

External authentication provider settings.

Setting	Default	Description
authn_provider.type	default	Provider type (default or rest)
authn_provider.rest.base_url	""	Base URL for REST authentication provider
authn_provider.rest.timeout	10	Request timeout in seconds
authn_provider.rest.security.api_key	""	API key for REST provider authentication

CORS Configuration

Cross-Origin Resource Sharing settings (typically defined in deployment.yaml).

Setting	Description
cors.allowed_origins	Array of allowed origins for CORS requests

Example:

cors:
  allowed_origins:
    - "https://localhost:3000"
    - "http://localhost:5173"

Passkey Configuration

WebAuthn/Passkey settings (typically defined in deployment.yaml).

Setting	Description
passkey.allowed_origins	Array of allowed origins for passkey operations

Example:

passkey:
  allowed_origins:
    - "https://localhost:8090"

Security Configuration

Controls server-wide security behavior that is not specific to any single authenticator. Maps to SecurityConfig in the backend, nested under server.security.

Setting	Default	Description
server.security.jwks_cache_ttl	300	JWKS cache TTL in seconds. Applies to every JWKS consumer in the server (trusted issuer validation, federated OIDC authenticators such as Google, and so on). Fetched signing keys are reused from the in-process cache for this duration before being re-fetched. Plan external-server key rotations with at least this much overlap. Set to 0 to disable caching

Trusted Issuer Configuration

Maps to TrustedIssuerConfig in the backend, nested under server.security.trusted_issuer. Setting server.security.trusted_issuer.issuer activates the feature: Thunder trusts access tokens issued by an external authorization server and validates them against the external server's JWKS endpoint. When issuer is set, jwks_url and audience are required and Thunder fails to start if either is missing. This is used for federated authentication scenarios where a central Thunder instance issues tokens that tenant instances accept.

Setting	Default	Description
server.security.trusted_issuer.issuer	""	Expected value of the token's iss claim. Must match the external authorization server's issuer URL exactly
server.security.trusted_issuer.jwks_url	""	URL of the external authorization server's JWKS endpoint used to fetch signing keys. Must use HTTPS (HTTP allowed only for localhost)
server.security.trusted_issuer.audience	""	Expected value of the token's aud claim. This should be this server's own identifier (typically its public URL)
server.security.trusted_issuer.required_claims	[]	List of claims that every accepted token must contain. Each entry has a claim name and an expected value. If any required claim is missing or does not match, the token is rejected

Example:

server:
  security:
    trusted_issuer:
      issuer: "https://cloud.example.com"
      jwks_url: "https://cloud.example.com/oauth2/jwks"
      audience: "https://tenant.example.com"
      required_claims:
        - claim: "ouId"
          value: "tenant-123"

note

The frontend must include a matching resource parameter in the authorization request so the external authorization server sets the token's aud claim to this server's identifier. See the Trusted Issuer guide for the end-to-end setup.