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/diagnosticsreports 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/v1route family asks only for its own scopes;nauthilus:authenticateis 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.pgoprofile 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. Scopesnauthilus:history_readandnauthilus:history_detail, held by a Bearer token or a scoped Basic credential; the unrestricted backchannel Basic credential andnauthilus:adminreceive403. Configured understorage.history.clickhousewith 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 answer503 HISTORY_NOT_CONFIGURED. - Add: OIDC completion and answered status in the history:
oidc.code_issuanceandoidc.code_redemptionevents, acompletionblock, anddecision.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.operationswith the instance-localnauthilus_runtimesource and an optional Loki source with the fixednauthilus_diagnosticsquery profile. New routePOST /api/v1/support/operations/diagnosticsand scopenauthilus: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, orcompact) andinclude_ban_contextwork over HTTP, the MCP toolauthentication_attempts_search, and the Admin Client, and change no rights.compactreturnsattempt_summariesand an emptyattemptslist. 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 isattempt_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 ascomplete. - Add: optional
prometheusdiagnostics 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 withnauthilus_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 componentunknown. See Prometheus Source. - Add: diagnostics classify
ldap_errors_totalby operation and result code. A rejected user password (bind, code49) is reported as the informational symptomLDAP_BIND_REJECTEDand derives no hypothesis, because it is an outcome about the client and not a fault of the directory. Theauth_backendcomponent has runtime evidence (failed plugin backend calls, replaced Lua backend VMs, unexpected application errors) instead of readingunknown.
Backchannel caller authorization
- Add: scoped Basic credentials under
auth.backchannel.basic_auth.users. Each entry has ausername, apassword, andscopes, 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-levelusernameandpasswordremain 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:authenticateis no longer a base scope of every/api/v1route. Each route family asks only for its own scopes;nauthilus:authenticateopens/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 receives403withmissing required scope: .... See OIDC Bearer Access. - Add: scopes
nauthilus:security_read(brute-force and OIDC session listings) andnauthilus:security_write(cache and brute-force flushes, OIDC session deletion); either one reads the status of an asynchronous job.nauthilus:securityincludes both, andnauthilus:adminis 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 methodbasic_auth. The MCP endpoint is unchanged and accepts OAuth user tokens only. - Behavior change: stricter validation of
auth.backchannel.basic_auth:enabled: truerequires theusernameandpasswordpair or at least oneusersentry,usernameandpasswordmust be set together, usernames must be unique and must not contain a colon or a space, andusers[].scopesmust 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
403instead of401. Hooks withoutscopesand withoutpublic: truestay 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 metricmcp_requests_total{result}and audit recordsaudit=support_mcpandaudit=support_operations. - Add: OIDC
identity.oidc.hosted_resources: static clients only, a user right fromgroupsorgroup_dnschecked at authorization,max_authentication_age(default12h), an access-token lifetime capmax_access_token_lifetime(default15m), exclusive grants, and no device flow. - Change:
claimsof a custom scope (identity.oidc.custom_scopesandidentity.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-serverand its path-insertion form; discovery advertisesauthorization_response_iss_parameter_supported: true. Action: route the new well-known path to Nauthilus if the reverse proxy forwards onlyopenid-configuration. - Behavior change: every redirect-based authorization response, success or error, carries the RFC 9207
issparameter. Action: keepidentity.oidc.issuerexactly 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. Akey_rotation_intervalthat is not shorter thankey_max_ageis 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, andnauthilus:operations_readin 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, andreputation_assessments; new decision sourcestls_encryptionandrelay_domains; optional step-event and brute-force evidence streams; host metricplugin_auth_events_total{outcome,lane}. - Behavior change: tempfails are recorded as
outcome=tempfailwithhttp_status=500and their tempfail text instead of a credential failure; dashboards that filter onstatus_msg='Invalid login or password'stop counting them. Deduplication follows the sealed outcome, tempfails and unknown outcomes are never deduplicated, and the key versionv3starts a fresh deduplication window. - Remove: the 20 retired login columns are no longer exported: the flat
reputation_*columns and thegp_*,prot_*, anddyn_*fields. The bundled Grafana dashboard readsreputation_assessments. Action: update dashboards and queries; the optionalretire-legacy-columnsblock ofschema.sqlis a separate, irreversible step. - Action: apply
migrations/diagnostic-contract.sqlbefore deploying the plugin andmigrations/bruteforce-evidence.sqlbefore enabling the brute-force URLs; ClickHouse drops unknown fields silently by default. Optionally append&input_format_skip_unknown_fields=0to the insert URLs afterwards. - Add: a reserved share of the login buffer for brute-force rejects,
max_brute_force_reject_rows(default half ofmax_buffer_rows); excess rows are counted asdropped_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(default24h);cleanup_enabled: falsekeeps the previous behavior. The leased background maintenance needs Redis 6.2 or newer. New metricsbruteforce_affected_accounts_maintenance_total,bruteforce_affected_accounts_maintenance_errors_total, andbruteforce_affected_accounts_members;redis_write_totalnow counts three commands per affected-account write and flush. - Add:
POST /api/v1/bruteforce/listaccepts"account_resolution": "account_mapping"for 1 to 100 distinct accounts and returns per-nameresolutions. - Behavior change: if the stored account mappings cannot be read,
/api/v1/cache/flushanswers503 Account mapping lookup failedbefore 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_windowexpired.
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 onlyhost_post_actioneffects. New metricpolicy_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_capacityis in flight; rejections count aspost_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
SessionIndexelements 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
SigAlgandSignaturequery 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.luaanddynamic_response.luaread the per-protocol layouts the writers create,haveibeenpwnd.luasends its leak notification again, and thereset_accountadmin hook clears the current keys of one account. Action: on Redis Cluster, delete the untagged and{lua-nauthilus}-renamedmultilayer:global:current_metricshashes 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
supportcommand group for the history API with--summaryoutput and exit codes, and a hash-guarded standalone installercontrib/client/install-admin-client.sh.support attempts searchaccepts--include-ban-contextand--response-mode. The commands work with a bearer token, OIDC client credentials, or a scoped Basic credential (--basic-userand--basic-password); the server decides by the scopes configured for that user. - Add:
bruteforce list --via-mapping. - Behavior change: repeated
--resolveflags replaceNAUTHILUS_RESOLVE;bruteforce listrequests a page of 100 entries by default.
See Admin Client.
Native Go plugins and builds
- Add:
pluginapi/v1event sinksAuthEventSinkandBruteForceEventSinkwith their registrars,PostActionRequest.OutcomeandFactsTrimmed,IDPInfo.FlowRef,RequestDiagnostics.BruteForceTolerated, and the exchange featuresFeatureTLSEncryptionandFeatureRelayDomains. 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.shprints the flag); a PGO-built server refuses plugins compiled without it. See PGO profile and Compiling. - Build:
github.com/twmb/franz-gois pinned to v1.22.1 (kmsgv1.14.0) andgithub.com/pierrec/lz4/v4to v4.1.31, because lz4 v4.1.32 and later cannot be built with-buildmode=pluginon amd64. Out-of-tree plugins that share these modules must use the same versions.
Documentation
- Add: the Redis Keyspace Reference lists every Redis key, Lua script, and keyless Redis use of the server and its bundled plugins, and the ClickHouse Data Model Reference lists every ClickHouse table and view with its writers, readers, access model, and migrations. Both live under Data Stores in the developer documentation.
- Add: Server Internals in the developer documentation: the CSRF middleware API, the IdP MFA flow notes, the browser session contract, the MFA cache invalidation notes, and the backchannel FSM decision record.
- Add: the Operational Security Checklist for release readiness and recurring security operations.
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. Useschema.sqlor the migrations.