configuration.md

Configuration reference

This is the canonical reference for vigil.* properties. Values below reflect VigilProperties; omitted optional sections use the stated defaults.

Required JWT configuration

Configure exactly one signing mode.

vigil:
  jwt:
    algorithm: HS256 # default
    secret: ${JWT_SECRET} # required for HS256; at least 32 characters
    access-ttl: 15m
    refresh-ttl: 7d
    issuer: my-service # optional
    audience: my-api # optional
    clock-skew: 0s # maximum 5m

For RS256, replace the HS256 secret with the active private/public pair. Additional public keys only verify existing tokens during key rotation.

vigil:
  jwt:
    algorithm: RS256
    rsa-private-key: ${RSA_PRIVATE_KEY}
    rsa-public-key: ${RSA_PUBLIC_KEY}
    rsa-public-keys: []

rsa-private-key, rsa-public-key, and rsa-public-keys accept inline PEM, classpath: or file: locations. RS256 automatically registers /.well-known/jwks.json.

The HS256 length check counts characters; it does not measure entropy. Generate random key material with at least 256 bits of entropy and encode it without truncation. Do not use a human password or repeated text merely because it reaches 32 characters.

Optional configuration

vigil:
  auth:
    realm: app

  cookie:
    secure: true
    http-only: true
    same-site: Lax
    profiles:
      default:
        access-token-name: access_token
        refresh-token-name: refresh_token

  password:
    strength: 12

  blacklist:
    max-size: 10000
    ttl: 24h
    grace-period: 30s # maximum 60s

  login:
    max-failures: 5
    base-lock: 1m
    max-lock: 15m
    failure-window: 15m
    max-tracked-identifiers: 100000

  tenant:
    enabled: false
    header-name: X-Tenant-ID

  filter:
    ignored-paths: []
    public-paths: []
    profile-paths: {}

  session:
    enabled: false
    cookie-name: session_token
    ttl: 30m

  reset:
    ttl: 1h

  step-up:
    challenge-ttl: 2m
    proof-ttl: 5m
    max-size: 10000
    pin:
      min-length: 6
      max-length: 12
      bcrypt-strength: 12
      reject-common-patterns: true

  enrollment:
    enabled: false
    audience: enrollment-api # required only when enabled; trusted by configuration, never a request field
    proof-format: opaque-token # or decimal-code
    code-hmac-key: ${ENROLLMENT_CODE_HMAC_KEY} # required only for decimal-code
    proof-ttl: 15m
    total-lifetime: 24h
    attempt-limit: 5
    resend-limit: 3
    resend-cooldown: 1m

Validation and deployment notes

Spring Boot duration syntax is accepted for duration properties, for example 30s, 15m, and 7d. Lists and maps use standard YAML binding.

Property	Validation or normalization
jwt.secret	Required for HS256; at least 32 characters
jwt.clock-skew	Between 0s and 5m
jwt.rsa-private-key, jwt.rsa-public-key	Both required for RS256
password.strength	BCrypt cost 4–31; invalid values normalize to 12
blacklist.max-size	Non-positive values normalize to 10000
blacklist.grace-period	Values above 60s normalize to 60s
login.max-failures, login.max-tracked-identifiers	Non-positive values normalize to their defaults
login.base-lock, login.failure-window	Non-positive or omitted values normalize to their defaults
login.max-lock	Omitted values, or values shorter than base-lock, normalize to the default (15m, or base-lock if longer)
step-up.challenge-ttl, step-up.proof-ttl	Non-positive values normalize to their defaults
step-up.pin.min-length	Values below 4 normalize to 6
step-up.pin.max-length	Must be at least min-length and at most 128; otherwise normalizes to 12
step-up.pin.bcrypt-strength	BCrypt cost 4–31; invalid values normalize to 12
enrollment.audience	Required and non-blank when enrollment.enabled=true; fixed trusted proof audience
enrollment.proof-format	opaque-token by default; decimal-code opts into eight-digit manual entry
enrollment.code-hmac-key	Canonical Base64URL encoding of exactly 32 bytes; required for decimal-code and never derived from JWT keys
enrollment.proof-ttl, enrollment.total-lifetime	Positive; total lifetime must be at least proof TTL
enrollment.attempt-limit, enrollment.resend-limit	Attempt limit positive; resend limit non-negative
enrollment.resend-cooldown	Cannot be negative

For decimal-code, proof-ttl cannot exceed 15 minutes and attempt-limit cannot exceed five. Attempts remain cumulative across resend. The configured proof format governs generation and verification; changing it invalidates pending proofs issued under the prior format.

• Invalid JWT signing configuration fails at application startup.
• secure: true requires HTTPS for browser clients.
• vigil.login.* configures the lockout shared by PasswordLoginGuard and step-up PIN verification: after max-failures consecutive failures a key is locked for base-lock, the lock doubles on each further failure up to max-lock, and failures are forgotten after failure-window without a new failure. Password and step-up keys are namespaced separately.
• The built-in blacklist, login-attempt, and step-up stores are node-local. See deployment and operations before running more than one instance.
• Enrollment has no built-in store or delivery adapter. When enabled, every enrollment host port is required and missing ports fail startup; its store must be durable and atomic across instances.
• public-paths changes Vigil credential processing only. The application must configure its own anonymous authorization rules.
• Ownership details are canonical in system boundaries.