Skip to main content
Version: Next

Nauthilus 4.1.0

Published as tag v4.1.0 on November 19, 2026. This page describes the changes since v4.0.9.

Nauthilus 4.1 is a feature release on the v4 line. It keeps the v4 module path, pluginapi.APIVersion, and the configuration roots. Operators of 4.0.x follow Upgrading from 4.0.x to 4.1; the items marked Action below need an operator decision or a configuration change.

Highlights​

  • Support authentication history. A read-only API answers "what happened to this login?" from the evidence the ClickHouse plugin recorded: attempts, MFA steps, OIDC completion, the answered status, and brute-force bans with their contributing attempts. See Support Authentication History.
  • Read-only support access over MCP. An optional MCP endpoint lets support staff ask Codex or Claude Code about authentication attempts, bans, and the operational state, authenticated through Nauthilus itself and limited to read-only tools. See Read-only Support Access over MCP.
  • Compact support answers. An attempt search can answer in a compact form and link brute-force rejections to the recorded ban and to the accounts that fed it, so support gets one readable answer per rejected attempt.
  • Operational diagnostics. POST /api/v1/support/operations/diagnostics reports findings from the instance's own metrics and, optionally, from Loki and Prometheus, with separate findings and hypotheses.
  • Versioned ClickHouse diagnostic capture. Login rows carry a contract version and the sealed terminal outcome; optional streams record step events and brute-force evidence.
  • Scoped backchannel credentials. HTTP Basic callers can be given exactly the scopes they need, and every /api/v1 route family asks only for its own scopes; nauthilus:authenticate is no longer a base scope of all routes. See Backchannel caller authorization.
  • Brute-force toleration works again and counts failures per attempt within the window; affected accounts age out.
  • Encrypted session and token state. Browser session payloads and the edge token cache are encrypted in Redis, and browser sessions slide their idle expiry while they are in use. See Sessions and tokens.
  • Profile-guided optimization. Server builds consume a refreshed server/default.pgo profile from the release workload, and native plugins are built with the same profile.

Support history and diagnostics​

  • Add: read-only support history API over recorded ClickHouse evidence: POST /api/v1/support/authentication-attempts/search, /api/v1/support/authentication-attempts/detail, and /api/v1/support/bruteforce-bans/search. Scopes nauthilus:history_read and nauthilus:history_detail, held by a Bearer token or a scoped Basic credential; the unrestricted backchannel Basic credential and nauthilus:admin receive 403. Configured under storage.history.clickhouse with a dedicated reader account (contrib/clickhouse-kubernetes/history-reader.sql); a restart applies changes. Every call is audited (audit=support_history). Without a configured source the routes answer 503 HISTORY_NOT_CONFIGURED.
  • Add: OIDC completion and answered status in the history: oidc.code_issuance and oidc.code_redemption events, a completion block, and decision.answered_status_code / answered_status_message.
  • Security: recorded free text in history answers is sanitized: control, format, and bidirectional characters are replaced, and values are capped at 256 characters.
  • Add: operational diagnostics under observability.diagnostics.operations with the instance-local nauthilus_runtime source and an optional Loki source with the fixed nauthilus_diagnostics query profile. New route POST /api/v1/support/operations/diagnostics and scope nauthilus:operations_read. Action: the Loki source needs the raw slog JSON or text line stored in Loki.
  • Add: compact answers and ban context for the attempt search. The optional request fields response_mode (detailed, the default, or compact) and include_ban_context work over HTTP, the MCP tool authentication_attempts_search, and the Admin Client, and change no rights. compact returns attempt_summaries and an empty attempts list. The ban context links each brute-force rejected request to the recorded ban that was effective at that time (recorded hit, activation request, or bounded interval overlap), lists every matching ban, and classifies the contributions by recorded account (SUBJECT_ACCOUNT, MULTIPLE_ACCOUNTS, OTHER_ACCOUNTS_ONLY, NOT_SUFFICIENTLY_ATTRIBUTABLE), with evidence limits and without ever naming a person. Requests without the two fields get the unchanged answer, and the audit action of a ban-context search is attempt_search_ban_context. See Ban context and compact answers.
  • Add: for brute-force rules whose windows reach beyond the 14-day raw retention, the ban history lists the contributions that are still retained and marks the list with RAW_CONTRIBUTIONS_PARTIALLY_RETAINED; such a ban is never reported as complete.
  • Add: optional prometheus diagnostics source (observability.diagnostics.operations.sources.prometheus) with the same keys as the Loki source. It reports the increase of fixed counters inside the requested window for every scraped instance, and proves coverage with nauthilus_version_info. Action: the scrape must keep the core metric families the profile reads; a keep rule that lets only plugin metrics through leaves every component unknown. See Prometheus Source.
  • Add: diagnostics classify ldap_errors_total by operation and result code. A rejected user password (bind, code 49) is reported as the informational symptom LDAP_BIND_REJECTED and derives no hypothesis, because it is an outcome about the client and not a fault of the directory. The auth_backend component has runtime evidence (failed plugin backend calls, replaced Lua backend VMs, unexpected application errors) instead of reading unknown.

Backchannel caller authorization​

  • Add: scoped Basic credentials under auth.backchannel.basic_auth.users. Each entry has a username, a password, and scopes, and is authorized exactly like a Bearer token carrying those scopes: on the HTTP management API, on the gRPC authority listener, and on custom hooks (Lua and native) that declare scopes. The top-level username and password remain the unrestricted credential; when it is configured, Nauthilus logs a warning at configuration load that recommends scoped credentials. See Backchannel Basic Credentials.
  • Behavior change: nauthilus:authenticate is no longer a base scope of every /api/v1 route. Each route family asks only for its own scopes; nauthilus:authenticate opens /api/v1/auth/* and the management OpenAPI documents. The support routes need only the support scopes. Existing tokens keep working: nothing they could do before is refused now. A valid credential without the route scope receives 403 with missing required scope: .... See OIDC Bearer Access.
  • Add: scopes nauthilus:security_read (brute-force and OIDC session listings) and nauthilus:security_write (cache and brute-force flushes, OIDC session deletion); either one reads the status of an asynchronous job. nauthilus:security includes both, and nauthilus:admin is accepted wherever they are.
  • Add: the support routes under /api/v1/support/* accept a scoped Basic credential that holds the support scopes. Audit records name the Basic username with the method basic_auth. The MCP endpoint is unchanged and accepts OAuth user tokens only.
  • Behavior change: stricter validation of auth.backchannel.basic_auth: enabled: true requires the username and password pair or at least one users entry, username and password must be set together, usernames must be unique and must not contain a colon or a space, and users[].scopes must list at least one valid scope. Action: check configurations that enable Basic authentication before the upgrade.
  • Behavior change: a custom hook that declares scopes refuses the unrestricted Basic credential with 403 instead of 401. Hooks without scopes and without public: true stay reachable only with the unrestricted credential.

MCP support access and OIDC​

  • Add: optional read-only MCP endpoint runtime.servers.mcp, disabled by default. It runs on its own listener behind a TLS-terminating reverse proxy, uses OAuth 2.1 with Nauthilus as issuer and RFC 9728 protected resource metadata, and offers four read-only tools that return the same JSON as the /api/v1/support/* routes. Clients use a pre-registered static client; dynamic registration is refused. New metric mcp_requests_total{result} and audit records audit=support_mcp and audit=support_operations.
  • Add: OIDC identity.oidc.hosted_resources: static clients only, a user right from groups or group_dns checked at authorization, max_authentication_age (default 12h), an access-token lifetime cap max_access_token_lifetime (default 15m), exclusive grants, and no device flow.
  • Change: claims of a custom scope (identity.oidc.custom_scopes and identity.oidc.clients[].custom_scopes) is optional. A custom scope without claims declares the scope and its consent text only; see Custom Scopes.
  • Add: scope consistency warnings at configuration load for an enabled OIDC issuer: a mapped claim that no scope allowed for its client releases, a custom scope no client may request, and a client scope that is neither built in nor declared. They never fail the load. Action: review the warnings after the upgrade; a mapped claim reported as never released has been missing from every token of that client whose request named a scope.
  • Behavior change: RFC 8414 authorization server metadata at /.well-known/oauth-authorization-server and its path-insertion form; discovery advertises authorization_response_iss_parameter_supported: true. Action: route the new well-known path to Nauthilus if the reverse proxy forwards only openid-configuration.
  • Behavior change: every redirect-based authorization response, success or error, carries the RFC 9207 iss parameter. Action: keep identity.oidc.issuer exactly as clients know it.
  • Security: pending consent decisions were stored in the authorization-code key space. A client could redeem the consent challenge, which the user agent sees, with its own credentials and PKCE verifier at the token endpoint and receive tokens before the user consented. Consent state now has its own key family, and the token endpoint refuses code values outside the issued shape with invalid_grant. During a rolling update, consent pages started on a 4.0.x instance must be restarted; nothing needs to be migrated.

Sessions and tokens​

  • Security: browser session payloads (anchor, flows, enrollment, step-up, WebAuthn ceremony, TOTP and recovery material, consent, logout index) were stored as plain JSON in Redis. They are now sealed with ChaCha20-Poly1305 under storage.redis.encryption_secret; a payload that does not open is deleted and the browser starts a fresh session. Upgrade effect: every live browser session ends once and stored OIDC consents are requested once more.
  • Security: the edge token cache stores the shared authority bearer token encrypted, deletes a rejected token by its digest, so a token another replica just refreshed survives, and releases its refresh lock only by its owner. Upgrade effect: each edge replica fetches its authority token once more.
  • Fix: browser sessions slide their idle expiry while they are in use. Every opened session is extended to now plus 30 minutes, at most once per 5 minutes and never past the absolute expiry. Before, a session ended 30 minutes after its creation or login.
  • Behavior change: generated OIDC signing keys follow identity.oidc.key_max_age (default 7 days) instead of a 365-day fallback, and the cleanup removes every inactive key older than that age. A key_rotation_interval that is not shorter than key_max_age is replaced by half the maximum age with a warning, so the active key never expires before its successor.
  • Fix: the admin user flush revokes OIDC tokens by backend account. Tokens whose subject is the backend unique user ID, for example an LDAP entryUUID, used to stay valid after a flush. Tokens issued before the upgrade are reached when their subject equals the account, or after their next refresh.
  • Add: the consent page shows translated texts for nauthilus:history_read, nauthilus:history_detail, and nauthilus:operations_read in all shipped locales instead of the raw scope names.

ClickHouse plugin​

  • Add: versioned diagnostic capture: rows carry contract_version = 1, the sealed terminal outcome, transport_status, flow_ref, brute_force_tolerated, and reputation_assessments; new decision sources tls_encryption and relay_domains; optional step-event and brute-force evidence streams; host metric plugin_auth_events_total{outcome,lane}.
  • Behavior change: tempfails are recorded as outcome=tempfail with http_status=500 and their tempfail text instead of a credential failure; dashboards that filter on status_msg='Invalid login or password' stop counting them. Deduplication follows the sealed outcome, tempfails and unknown outcomes are never deduplicated, and the key version v3 starts a fresh deduplication window.
  • Remove: the 20 retired login columns are no longer exported: the flat reputation_* columns and the gp_*, prot_*, and dyn_* fields. The bundled Grafana dashboard reads reputation_assessments. Action: update dashboards and queries; the optional retire-legacy-columns block of schema.sql is a separate, irreversible step.
  • Action: apply migrations/diagnostic-contract.sql before deploying the plugin and migrations/bruteforce-evidence.sql before enabling the brute-force URLs; ClickHouse drops unknown fields silently by default. Optionally append &input_format_skip_unknown_fields=0 to the insert URLs afterwards.
  • Add: a reserved share of the login buffer for brute-force rejects, max_brute_force_reject_rows (default half of max_buffer_rows); excess rows are counted as dropped_reject_limit.

See ClickHouse.

Brute-force protection​

  • Behavior change: brute-force toleration works again. Every authenticate request with a host-verified credential outcome records one positive or negative observation; on 4.0.x tolerate_percent, custom_tolerations, adaptive_toleration, and the reputation-scaled bucket limits had no effect. Action: review these settings before the upgrade.
  • Security fix: toleration negatives count every failed attempt from an address within tolerate_ttl, positives count distinct resolved accounts, and repeated wrong passwords are not counted. Before, a few valid accounts could keep an address tolerated while another account was attacked without limit. Counters are evaluated over exactly the window, keep at most 10,000 failures, and a saturated count is never tolerated. The flush endpoints now delete the toleration sets.
  • Fix: a request that runs a second brute-force update is counted once and keeps its first repeating-wrong-password verdict.
  • Behavior change: affected accounts age out per account after auth.controls.brute_force.affected_accounts.retention (default 24h); cleanup_enabled: false keeps the previous behavior. The leased background maintenance needs Redis 6.2 or newer. New metrics bruteforce_affected_accounts_maintenance_total, bruteforce_affected_accounts_maintenance_errors_total, and bruteforce_affected_accounts_members; redis_write_total now counts three commands per affected-account write and flush.
  • Add: POST /api/v1/bruteforce/list accepts "account_resolution": "account_mapping" for 1 to 100 distinct accounts and returns per-name resolutions.
  • Behavior change: if the stored account mappings cannot be read, /api/v1/cache/flush answers 503 Account mapping lookup failed before removing anything; automation must retry. The flush no longer removes mappings of other users whose login names start with <name>|.
  • Fix: the user flush deletes the repeating-wrong-password window of every login identity behind the flushed accounts; before, the windows survived until rwp_window expired.

See Brute Force.

Policy and post-actions​

  • Add: an authn target can declare terminal_post_actions. They run once per answered request, whichever rule answered it, including built-in rejects such as ban hits; rule obligations naming the same effect are folded in. They are best-effort and accept only host_post_action effects. New metric policy_terminal_post_actions_total{operation,post_action,result}.
  • Change: best-effort post-action plans are accepted only while fewer than half of policy.runtime.post_actions.queue_capacity is in flight; rejections count as post_action_acceptance_failures_total{error_class="best_effort_saturated"} and never fail a request.
  • Fix: a Policy reload with an in-flight post-action no longer stalls for the 30-second cleanup budget.
  • Fix: a tempfail answered without a presenting rule names the failed checkpoint as its stage.

See Policy configuration.

SAML​

  • Fix: a LogoutRequest listing several SessionIndex elements matches when any of them matches.
  • Security: SHA-1 AuthnRequest signatures are also rejected in the library validation path.
  • Fix: HTTP-Redirect SLO messages are signed with SigAlg and Signature query parameters; Redirect-bound LogoutResponses previously reached service providers unsigned.
  • Fix: concurrent LogoutResponses of one SLO fan-out transaction are applied atomically, so no outcome is lost.

See SAML.

Bundled Lua plugins​

  • Fix: the bundled Lua plugins keep the keys of one Redis script on one hash tag, so Redis Cluster no longer separates writers from readers. soft_delay.lua and dynamic_response.lua read the per-protocol layouts the writers create, haveibeenpwnd.lua sends its leak notification again, and the reset_account admin hook clears the current keys of one account. Action: on Redis Cluster, delete the untagged and {lua-nauthilus}-renamed multilayer:global:current_metrics hashes once; all other old keys expire.

Secret redaction​

  • Security: secret configuration values render as <hidden> in every formatted and logged output, including nested and unexported fields. With debug logging, earlier v4 releases printed OIDC client secrets in plain text in the configuration they log at startup. Action: restrict or purge debug logs written by earlier releases and rotate the OIDC client secrets they contain.

Admin client​

  • Add: a support command group for the history API with --summary output and exit codes, and a hash-guarded standalone installer contrib/client/install-admin-client.sh. support attempts search accepts --include-ban-context and --response-mode. The commands work with a bearer token, OIDC client credentials, or a scoped Basic credential (--basic-user and --basic-password); the server decides by the scopes configured for that user.
  • Add: bruteforce list --via-mapping.
  • Behavior change: repeated --resolve flags replace NAUTHILUS_RESOLVE; bruteforce list requests a page of 100 entries by default.

See Admin Client.

Native Go plugins and builds​

  • Add: pluginapi/v1 event sinks AuthEventSink and BruteForceEventSink with their registrars, PostActionRequest.Outcome and FactsTrimmed, IDPInfo.FlowRef, RequestDiagnostics.BruteForceTolerated, and the exchange features FeatureTLSEncryption and FeatureRelayDomains. All additions are optional. See Event sinks.
  • Build: server builds apply profile-guided optimization from server/default.pgo, which the release workflow refreshes from a dedicated authentication workload of the release end-to-end test. Action: build every native plugin with the same profile (sh scripts/native-pgo-flag.sh prints the flag); a PGO-built server refuses plugins compiled without it. See PGO profile and Compiling.
  • Build: github.com/twmb/franz-go is pinned to v1.22.1 (kmsg v1.14.0) and github.com/pierrec/lz4/v4 to v4.1.31, because lz4 v4.1.32 and later cannot be built with -buildmode=plugin on amd64. Out-of-tree plugins that share these modules must use the same versions.

Documentation​

Known issues​

  • The ClickHouse schema embedded in the Kubernetes initialization Job does not yet contain the diagnostic contract columns, auth_events, and the brute-force tables. Use schema.sql or the migrations.