Skip to main content

Server Configuration

This section defines all required settings that are needed to run the Nauthilus server.

Basic Server Settings

server::address

Default: "127.0.0.1:9080"

This is the IPv4 or IPv6 addresses combined with a TCP port.

server:
address: "[::]:9443"

server::max_concurrent_requests

Default: 100

This setting defines the maximum number of concurrent requests that can be processed by the server.

server:
max_concurrent_requests: 200

server::max_password_history_entries

Default: 0

This setting defines the maximum number of password history entries to store for each user.

server:
max_password_history_entries: 10

server::haproxy_v2

Default: false

If this setting is turned on (true), Nauthilus can make use of the HAproxy version 2 protocol header to identify the original client request.

server:
haproxy_v2: true

server::http3

Default: false

Enable HTTP/3 support for the server. There does not exist the PROXY protocol for this version!

server::disabled_endpoints

New in version 1.4.9
Default: All endpoints are enabled

It is possible to disable certain HTTP location endpoints that are not needed.

server:
disabled_endpoints:
auth_header: false
auth_json: false
auth_basic: false
auth_nginx: false
auth_saslauthd: false
auth_jwt: false
custom_hooks: false
configuration: false # Available from version 1.7.11
tip

Disableing unused endpoints may enhance overall security!

Meaning

Key-namelocationdescription
auth_header/api/v1/auth/headerTurn off requests based on HTTP headers
auth_json/api/v1/auth/jsonTurn off HTTP JSON-POST requests
auth_basic/api/v1/auth/basicTurn off HTTP Basic Authorization requests (recommended!)
auth_nginx/api/v1/auth/nginxTurn off Nginx based requests used by the mail plugin of Nginx
auth_saslauthd/api/v1/auth/saslauthdTurn off saslauthd requests used with cyrus-sasl
auth_jwt/api/v1/jwt/*Turn off JWT authentication endpoints
custom_hooks/api/v1/custom/*Turn off all Lua based custom hooks
configuration/api/v1/config/*Turn off all configuration related endpoints

HTTP Client Configuration

server::http_client

Whenever Nauthilus is acting as an HTTP client, a common shared Go-builtin HTTP client is used to handle all requests.

There do exist the following HTTP clients in Nauthilus:

ScopeUsage
coreIf the Ory hydra frontend is turned on, all admin-API requests are handled by this client
actionUsed for Lua actions, if HTTP requests are used
filterUsed for Lua filters, if HTTP requests are used
featureUsed for Lua featuress, if HTTP requests are used
hookUsed for Lua custom hooks, if HTTP requests are used

Settings are shared with all HTTP clients!

SettingMeaning (Used from official Go docs)Default
max_connections_per_hostLimits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block.0, no limits
max_idle_connectionsControls the maximum number of idle (keep-alive) connections across all hosts.0, no limits
max_idle_connections_per_hostControls the maximum idle (keep-alive) connections to keep per-host.0, no limits
idle_connection_timeoutIs the maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.0, no limits
proxyHTTP proxy URL to use for client connections. New in version 1.7.11"", no proxy
tlsTLS configuration for the HTTP client. New in version 1.7.11See below

Units for the timeout option should add a time unit like

  • s - seconds
  • m - minutes
  • h - hours
server:
http_client:
max_connections_per_host: 10
max_idle_connections: 5
max_idle_connections_per_host: 1
idle_connection_timeout: 60s
proxy: "http://proxy.example.com:8080"
tls:
skip_verify: false

TLS Configuration

server::tls

This object defines TLS related settings.

server::tls::enabled

Default: false

This flag turns on (true) TLS support in the server.

server:
tls:
enabled: true

server::tls::cert and server::tls::key

Default: ""

These two settings define a path to an X509 PEM-formatted certificate and key.

server:
tls:
cert: /usr/local/etc/nauthilus/localhost.localdomain.pem
key: /usr/local/etc/nauthilus/localhost.localdomain.key.pem

server::tls::skip_verify

Default: false
New in version 1.7.11

This flag turns on (true) insecure TLS connections by skipping client certificate verification.

server:
tls:
skip_verify: true

server::tls::http_client_skip_verify

Default: false
Deprecated: Use server::http_client::tls::skip_verify instead

This flag turns on (true) insecure TLS connections for HTTP(s) requests that are originating from Nauthilus to some remote.

server:
tls:
http_client_skip_verify: true

server::tls::min_tls_version

Default: "TLS1.2"
New in version 1.7.11

This setting defines the minimum TLS version that the server will accept. Valid values are "TLS1.2" and "TLS1.3".

server:
tls:
min_tls_version: "TLS1.3"

server::tls::ca_file

Default: ""
New in version 1.7.11

This setting defines the path to a CA certificate file in PEM format. This is used to verify client certificates when mutual TLS authentication is enabled.

server:
tls:
ca_file: /usr/local/etc/nauthilus/ca.pem

server::tls::cipher_suites

Default: []
New in version 1.7.11

This setting defines a list of cipher suites that the server will use for TLS connections. If not specified, the default Go cipher suites will be used.

server:
tls:
cipher_suites:
- "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"
- "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
- "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256"

Authentication Configuration

server::basic_auth

This object defines basic authorization settings.

server::basic_auth::enabled

Default: false

This flag turns on (true) Basic Auth support in the server.

server::basic_auth::username and server::basic_auth::password

Default: ""

These settings define a username and its password that is required by HTTP(s) clients to communicate with Nauthilus. The password must be at least 16 characters long and can contain alphanumeric characters and symbols, but no spaces.

server::jwt_auth

This object defines JWT (JSON Web Token) authentication settings. JWT authentication provides a more secure and flexible alternative to HTTP Basic Authentication.

When enabled, Nauthilus provides the following JWT endpoints:

  • Token Generation: POST /api/v1/jwt/token - Generate a new JWT token with username and password
  • Token Refresh: POST /api/v1/jwt/refresh - Refresh an existing token using a refresh token

JWT tokens include roles that determine what actions the user can perform:

  • authenticate: This role is needed to perform authentication requests (renamed from "authenticated" in version 1.7.11)
  • user_info: Required to access endpoints with mode=no-auth
  • list_accounts: Required to access endpoints with mode=list-accounts
  • security: Access to security-related features like metrics and brute force management
  • admin: Full access to all features
  • Custom roles: Can be defined for your users and used for custom hooks

For multi-instance environments (e.g., behind a load balancer), enable Redis storage for JWT tokens to ensure that tokens generated by one instance can be validated by another instance.

server::jwt_auth::enabled

Default: false

This flag turns on (true) JWT authentication support in the server.

server:
jwt_auth:
enabled: true

server::jwt_auth::secret_key

Default: ""

This setting defines the secret key used for JWT signing. It should be at least 32 characters long and can contain alphanumeric characters and symbols, but no spaces.

server:
jwt_auth:
secret_key: "your-secret-key-at-least-32-characters"

server::jwt_auth::token_expiry

Default: 1h

This setting defines the expiration time for JWT tokens.

server:
jwt_auth:
token_expiry: 2h

server::jwt_auth::refresh_token

Default: false

This flag enables refresh tokens for JWT authentication.

server:
jwt_auth:
refresh_token: true

server::jwt_auth::refresh_token_expiry

Default: 24h

This setting defines the expiration time for JWT refresh tokens.

server:
jwt_auth:
refresh_token_expiry: 48h

server::jwt_auth::store_in_redis

Default: false

This flag enables storing JWT tokens in Redis.

server:
jwt_auth:
store_in_redis: true

server::jwt_auth::users

This section defines users that can authenticate using JWT.

server:
jwt_auth:
users:
- username: admin
password: "secure-password"
roles:
- admin
- user
- username: user
password: "another-secure-password"
roles:
- user

Instance Name

server::instance_name

Default: "nauthilus"

This defines the application name. If not defined, it defaults to nauthilus

Logging Configuration

server::logs

This object defined logging relates settings.

server::log::json

Default: false

This flag turns on (true) logging in JSON format.

server:
log:
json: true

server::log::level

Default: "none"

This string defines the log level. It is one of:

LevelComment
noneEntirely turn of logging
debugSee debug modules below!
info
warn
error
server:
log:
level: debug

server::log::debug_modules

Default: empty list

if debugging is turned on, only very limited debug messages are logged by default. You can increase logging by activating additional log modules. This is the list of all available debug modules:

ModuleApplication
allFull debugging
authThis turns on logging for the main authentication process
hydraCommunication with the Ory hydra server
webauthnTurn on debugging for WebAuthn (under development)
statisticsPrometheus related debugging
whitelistShow whitelist related debugging
ldapShow LDAP command and filter related debugging
ldappoolShow LDAP-pool related debugging such as free/busy/closed connections and housekeeping
cacheTurn on cache backend related debugging
brute_forceTurn on brute-force related debugging
rblTurn on RBL (realtime-blackhole-list) related debugging
actionTurn on Lua post-action related debugging
featureTurn on feature related debugging
luaTurn on Lua related debugging
filterTurn on filter related debugging
tolerateTurn on debugging for operations related to tolerance or error allowances
neuralTurn on debugging for neural network-related operations
jwtTurn on debugging for JWT-related operations
httpTurn on debugging for HTTP-related operations
server:
log:
debug_modules:
- auth
- ldap
- filter

Backend Configuration

server::backends

Default: none
required

This object defines, which backends are enabled. You must define at least one backend!

NameComment
cacheThe Redis cache backend is used for positive and failed login requests and should be enabled
ldapThis is the native LDAP backend. See settings below for configuration
luaThis is a Lua backend

For Multi-LDAP and Multi Lua-backends, you can use a special syntax to specify which pool or backend to use:

server:
backends:
- cache
- ldap(pool1) # Use the LDAP pool named "pool1"
- lua(backend2) # Use the Lua backend named "backend2"

This syntax allows you to use multiple LDAP pools or Lua backends with different configurations. The pool or backend name must match a name defined in the optional_ldap_pools or optional_lua_backends sections.

note

The *cache backend not only caches positive and negative requests. It is also a major component for the brute force buckets to detect users with repetitive wrong passwords.

warning

The cache backend should always be the first backend. The order of backends matters!

Features Configuration

server::features

Default: empty list

This object defines runtime features.

Here is a list of features that can be turned on:

NameUsage
luaGeneral purpose Lua feature. You can have as many features as you like. They run in sequential order
tls_encryptionClients must be connected securely to a service to be allowed to authenticate
relay_domainsIf the login name equals to an email address, the domain component is compared to a list of known domains
rblCheck a client IP address against realtime blackhole lists
backend_server_monitoringThis is a special feature that is not used for filtering

These features are primarely used to filter out requests before the main authentication process starts.

note

The features are run one-by-one. The rbl feature does query lists in parallel. The lua feature is always run as first feature and is the only one that can skip further processing of other features!

The backend_server_monitoring feature turns on a background job that does a health check for any kind of backend servers. It holds an in-memory list of alive servers that can be used in Lua scripts to select healthy servers.

server:
features:
- tls_encryption
- lua
- rbl

Brute Force Configuration

server::brute_force_protocols

Default: empty list

This object defines a list of protocols for which the brute force protection is turned on.

When a service talks to Nauthilus, it must provide a protocol that is used by a remote client while authenticating.

This list describes protocols for which Nauthilus does brute force checks.

Here is a good working example that can be taken in a production environment:

server:
brute_force_protocols:
- imap
- imaps
- submission
- smtp
- smtps
- ory-hydra
- http
note

While most of the protocols are free to chose, ory-hydra has a special meaning for Nauthilus and is assigned to the communication between Nauthilus and the Ory hydra serverr.

Ory Hydra Configuration

server::ory_hydra_admin_url

Default: "http://127.0.0.1:4445"

This setting is the Ory hydra admin URL.

server:
ory_hydra_admin_url: https://hydra.example.com:4445

DNS Configuration

server::dns

This object defines settings related to the DNS name resolver.

server::dns::resolver

Default: ""

If this setting is given, Nauthilus does not use the Go internal DNS resolver. Instead, it uses the provided resolver for DNS resolution.

server:
dns:
resolver: 192.168.0.1

server::dns::timeout

Default: 5

If a custom DNS resolver is set, you can specify a default timeout in seconds, after which DNS queries are aborted without waiting for a result.

server:
dns:
timeout: 3

server::dns::resolve_client_ip

Default: false

If a DNS reverse lookup should be done for incoming client requests, you can turn on (true) this feature.

server:
dns:
resolve_client_ip: true
warning

Turning on this feature will heavily increase network latency and DNS resolver load. It is suggested to use this feature with care.

Insights Configuration

server::insights

This object defines settings related to go pprof and is mainly useful for developers.

server::insights::enable_pprof

Default: false

Enable (true) pprof in Go for debugging purposes.

server:
insights:
enable_pprof: true

server::insights::enable_block_profile

Default: false

If pprof is enabled (required for this flag), you can also activate a block profile, which helps to find blocking code.

server:
insights:
enable_block_profile: true

server::insights::monitor_connections

Default: false

This flag turns on (true) connection monitoring.

server:
insights:
monitor_connections: true

Redis Configuration

server::redis

This object defines settings related to the Redis server.

server::redis::database_number

Default: 0

If Redis is configured to run standalone, master-slave or as sentinel, you can select the database number that Nauthilus must use.

server:
redis:
database_number: 2

server::redis::prefix

Default: ""

You can define a prefix that has to be used for any keys in Redis.

server:
redis:
prefix: "nt_"
note

This prefix is for Nauthilus internal keys only. If you chode to use Redis within Lua, you have to manage Redis keys yourself

tip

You may define custom prefixes in Lua with "ntc:" Like "Nauthilus-custom". That way you have a difference between built-in keys and user defined keys.

server::redis::password_nonce

Default: ""
required

This is a random string used to concatenate it with the password. The result will be hashed and truncated and is used in Redis. This helps secure password storage in Redis. The password nonce must be at least 16 characters long and can contain alphanumeric characters and symbols, but no spaces.

server:
redis:
password_nonce: "some-random-string-used-for-password-hashing"

server::redis::pool_size

Default: 0
required

This is a Redis pool size. The pool is managed by the underlying redis library go-redis.

server:
redis:
pool_size: 10

server::redis::idle_pool_size

Default: 0

This is a Redis idle pool size. The pool is managed by the underlying redis library go-redis.

server:
redis:
idle_pool_size: 2

server::redis::tls

New in version 1.7.11

This section configures TLS for Redis connections.

server:
redis:
tls:
skip_verify: false

server::redis::positive_cache_ttl and server::redis::negative_cache_ttl

Default: 3600

Both values set the expiration value for Redis keys in seconds. The positive cache TTL is for authenticated users, while the negative cache TTL is for authentication failures. The latter may be larger as it is also used in the brute-force logic to detect users that try to log in with a repeating wrong password. Such requests are never treated as an attack.

server:
redis:
positive_cache_ttl: 3600
negative_cache_ttl: 7200

Changes in version 1.4.9:

Units should now add a time unit like

  • s - seconds
  • m - minutes
  • h - hours

server::redis::master

If running Redis standalone or in master-slave mode, you have to define the master object.

server::redis::master::address

Default: "127.0.0.1:6379"

This is the socket for a Redis connection to either a standalone server or for a master.

server:
redis:
master:
address: 127.0.0.1:6379

server::redis::master::username and server::redis::master::password

Default: empty

This is an optional username and password for Redis, if the service requires authentication.

Server:
redis:
master:
username: some_user
password: some_secret

server::redis::replica

This object defines a replica to a master. Currently, there is only support for one master and one replica. If you need more replica server, consider using sentinel instead or use some load balancer in front of Nauthilus that may distribute replica connections to more than one replica instance.

server::redis::replica::address

Deprecated in version 1.4.10
Default: ""

This is the socket for a Redis connection to a replica instance.

server:
redis:
replica:
address: 10.10.10.10:6379

server::redis::replica::addresses

New in version 1.4.10
_Default: []

This is a list of one or more sockets for a Redis connection to a replica instance.

server:
redis:
replica:
addresses:
- 10.10.10.10:6379

server::redis::sentinels

NAuthilus can connect to Redis sentinels. The following options define such a setup.

server::redis::sentinels::master

Default: ""

This is the name of the sentinel master.

server:
redis:
sentinels:
master: mymaster

server::redis::sentinels::addresses

Default: empty list

This is a list of Redis sentienl sockets.

server:
redis:
sentinels:
addresses:
- 127.0.0.1:26379
- 127.0.0.1:26378
- 127.0.0.1:26377
note

At least one sentinel address is required.

Here is an example for K8s redis-operator sentinel, if you run Nauthilus in Kubernetes on-premise and a NodePort service:

server:
redis:
sentinels:
master: myMaster
addresses:
- redis-sentinel-sentinel-0.redis-sentinel-sentinel-headless.ot-operators.svc.cluster.local:26379
- redis-sentinel-sentinel-1.redis-sentinel-sentinel-headless.ot-operators.svc.cluster.local:26379
- redis-sentinel-sentinel-2.redis-sentinel-sentinel-headless.ot-operators.svc.cluster.local:26379

server::redis::sentinels::username and server::reids::sentinels::password

Default: ""

Both of these parameters are optional settings, if your Redis sentinels require authentication.

server:
redis:
sentinels:
username: some_user
password: some_secret

server::redis::cluster

If NAuthilus should be connected to a Redis cluster, the following settings can be set to do so.

server::redis::cluster::addresses

Default: empty list

This is a list of one or more Redis sockets pointing to a Redis cluster.

server:
redis:
cluster:
addresses:
- 127.0.0.1:6379
- 127.0.0.1:6378
- 127.0.0.1:6377

server::redis::cluster::username and server::redis::cluster::password

Default: ""

These parameters are optional settings for authentication with the Redis cluster.

server:
redis:
cluster:
username: some_user
password: some_secret

server::redis::cluster::route_by_latency

Default: false

When enabled, commands are routed to the Redis node with the lowest latency.

server:
redis:
cluster:
route_by_latency: true

server::redis::cluster::route_randomly

Default: false

When enabled, commands are routed randomly across Redis nodes.

server:
redis:
cluster:
route_randomly: true

server::redis::cluster::route_reads_to_replicas

New in version 1.7.11
Default: false

When enabled, read commands are routed to Redis replica nodes, which can improve performance by distributing the read load across the cluster.

server:
redis:
cluster:
route_reads_to_replicas: true

server::redis::cluster::read_only

Default: false
Deprecated: Use route_reads_to_replicas instead

When enabled, read commands are routed to Redis replica nodes. This parameter has been renamed to route_reads_to_replicas to better reflect its actual functionality.

server:
redis:
cluster:
read_only: true # Deprecated

server::redis::cluster::max_redirects

Default: 3

This setting defines the maximum number of redirects to follow when executing Redis commands.

server:
redis:
cluster:
max_redirects: 5

server::redis::cluster::read_timeout and server::redis::cluster::write_timeout

Default: 0 (no timeout)

These settings define the timeout duration for read and write operations to the Redis cluster.

Units should add a time unit like:

  • s - seconds
  • m - minutes
  • h - hours
server:
redis:
cluster:
read_timeout: 3s
write_timeout: 3s

Master User Configuration

server::master_user

This object defines settings related to a so-called master user

server::master_user::enabled

Default: false

If this flag is turned on (true), Nauthilus honors login usernames that are master users. A master user looks something like this:

user@domain.tld*masteruser

As you can see, the master user is separated from the real login name by a "*" character followed by the name of a master user. If NAuthilus detecs such a user, it will do authentication against the master user.

server:
master_user:
enabled: true

server::master_user::delimiter

Default: "*"

This is the character that splits the real username from the master user.

server:
master_user:
delimiter: "*"

Frontend Configuration

server::frontend

Nauthilus specific settings for the frontend (OIDC)

server::frontend::enabled

Default: false

Turn on the frontend.

server:
frontend:
enabled: true

server::frontend::csrf_secret

Default: ""
required

This key is required whenever CSRF (cross-site-request-forgery) attacks must be prevented. This is currently used, if Nauthilus is configured to communicate with Ory Hydra. The login, consent and logout pages are protected with a CSRF token. This value defines the secret used for that token.

This value MUST be 32 bytes long and can contain alphanumeric characters and symbols, but no spaces.

server::frontend::cookie_store_auth_key and server::frontend::cookie_store_encryption_key

Default: ""
required

These keys are used to encrypt and decrypt session cookies.

The cookie_store_auth_key MUST be 32 bytes long and can contain alphanumeric characters and symbols, but no spaces.

The cookie_store_encryption_key MUST be 16, 24, or 32 bytes long and can contain alphanumeric characters and symbols, but no spaces.

Prometheus Timer Configuration

server::prometheus_timer

Turn on several Prometheus labels, which are timers for certain aspects of the application.

server::prometheus\timer::enabled

Turn on the prometheus timers.

server:
prometheus_timer:
enabled: true

server::prometheus\timer::labels

The following labels can be turned on:

Label nameDescription
accountMode "list-accounts" timer
actionTimers for Lua actions
backendTimers for backends
brute_forceTimers for the brute force functions
featureTimers for all features
filterTimers for Lua filters
requestTimer for the entire client request without post actions
store_totpTimer for storing a new TOTP secret to a backend
post_actionTimers for Lua post actions
dnsTimers for DNS queries

Example:

server:
prometheus_timer:
enabled: true
labels:
- request
- dns

Compression Configuration

server::compression

This object defines settings related to HTTP response compression.

server::compression::enabled

Default: false

This flag turns on (true) HTTP response compression.

server:
compression:
enabled: true

server::compression::level

Default: 5

This setting defines the compression level (1-9, where 1 is fastest and 9 is best compression).

server:
compression:
level: 7

server::compression::content_types

Default: ["text/html", "text/css", "text/plain", "text/javascript", "application/javascript", "application/x-javascript", "application/json", "application/xml", "application/vnd.api+json"]

This setting defines the content types that should be compressed.

server:
compression:
content_types:
- text/html
- application/json

server::compression::min_length

Default: 1024

This setting defines the minimum content length required for compression.

server:
compression:
min_length: 2048

Keep Alive Configuration

server::keep_alive

This object defines settings related to HTTP connection keep-alive optimization.

server::keep_alive::enabled

Default: false

This flag turns on (true) HTTP keep-alive optimization.

server:
keep_alive:
enabled: true

server::keep_alive::timeout

Default: 30s

This setting defines the keep-alive timeout duration.

server:
keep_alive:
timeout: 60s

server::keep_alive::max_idle_connections

Default: 100

This setting defines the maximum number of idle connections.

server:
keep_alive:
max_idle_connections: 200

server::keep_alive::max_idle_connections_per_host

Default: 10

This setting defines the maximum number of idle connections per host.

server:
keep_alive:
max_idle_connections_per_host: 20