Configuration

The server loads its configuration in this order of precedence: defaults < YAML file < environment. Point it at a file with --config (or NAUTHERA_SERVER_CONFIG). Environment variables always win.

nauthera-server --config /etc/nauthera/config.yaml

The annotated reference is config.example.yaml in the nauthera-server repository.

#Environment variables

Every key has the prefix NAUTHERA_SERVER_. To get the variable name, upper-case the dotted key and replace . and - with _:

server.http.read_header_timeout  ->  NAUTHERA_SERVER_SERVER_HTTP_READ_HEADER_TIMEOUT
database.dsn                     ->  NAUTHERA_SERVER_DATABASE_DSN
tracing.sample_ratio             ->  NAUTHERA_SERVER_TRACING_SAMPLE_RATIO

Durations are Go duration strings ("15s", "30m"). Lists are comma-separated.

Prefer the file. The file is decoded strictly, so a mistyped key is a startup error that names it. A mistyped environment variable is silently ignored, and you run on a default you believe you overrode. The Helm chart renders config to a file for this reason.

#Secrets from files

Keys that hold secrets also accept a mounted file. Append _FILE to the variable name:

NAUTHERA_SERVER_DATABASE_DSN_FILE=/var/run/secrets/db/uri
NAUTHERA_SERVER_DATABASE_PASSWORD_FILE=/var/run/secrets/db/password
NAUTHERA_SERVER_CACHE_PASSWORD_FILE=/var/run/secrets/redis/password
NAUTHERA_SERVER_MFA_ENCRYPTION_KEY_FILE=/var/run/secrets/mfa/key
NAUTHERA_SERVER_KEYS_ENCRYPTION_KEY_FILE=/var/run/secrets/keys/kek

The retired-key lists (mfa.retired_keys, keys.retired_keys) have no file form and are read from the environment.

#Top-level sections

#Production guards

When the issuer host is not loopback, the server refuses to start unless:

• the issuer is https with no path,
• cache.enabled is true (otherwise authorization codes and refresh tokens would live in one replica's memory),
• keys.provider is file and mfa.provider is file (otherwise keys would be regenerated on every restart), and
• security.trusted_proxies is not empty.

localhost and names under .localhost count as loopback, so local development gets a real HTTPS issuer without having to run Redis.

#Example: minimal production file

issuer:
  url: https://auth.example.com
database:
  driver: postgres
  host: postgres.example.svc
  user: nauthera
  name: nauthera
  sslmode: verify-full
  migrate: true
cache:
  enabled: true
  address: redis.example.svc:6379
  tls: true
keys:
  provider: file
  signing_key_path: /etc/nauthera/keys/ec/tls.key
  rsa_signing_key_path: /etc/nauthera/keys/rsa/tls.key
mfa:
  provider: file
security:
  trusted_proxies: ["10.0.0.0/8"]
  hsts: true
server:
  grpc:
    tls:
      enabled: true
      cert_file: /etc/nauthera/grpc/tls.crt
      key_file: /etc/nauthera/grpc/tls.key
      client_ca_file: /etc/nauthera/grpc/ca.crt
      allowed_client_identities: ["nauthera-operator"]

Supply the database password, the MFA encryption key and the key-encryption key through the _FILE variables above.