Skip to main content
Version: 3.1

2.1.x Release Notes

This page summarizes the major changes introduced after v2.0.17 and captured in the 2.1 line.

Nauthilus 2.1 focuses on protocol completeness, integration robustness, and operator ergonomics: notably SAML Single Logout support, stronger SAML request validation, improved OIDC behavior, URL-partial-decoded request headers, and more extensible Lua and configuration workflows.

2.1.2​

Released on April 13, 2026.

This patch release extends the 2.1 line with broader OIDC compatibility, better IdP observability, more flexible edge and security controls, stronger LDAP/Lua integration, and recovery fixes for device authorization flows.

Added​

OIDC and IdP Flows​

  • Optional combined client authentication for refresh token exchanges, allowing affected OIDC clients to accept credentials from both HTTP Basic auth and the request body.
  • Centralized logging for incoming and completed OIDC and SAML IdP flows, including request outcome, HTTP status, client IP, and additional flow metadata.
  • Client-specific OIDC custom_scopes, so client definitions can override global scope behavior when names collide.
  • implied_scopes support in OIDC client configuration for compatibility mappings and predictable scope expansion.
  • Redirect URI validation with controlled wildcard matching and dynamic loopback port support for local/native client scenarios.

Configuration, Security, and Integrations​

  • Centralized CORS middleware and server-level CORS configuration for consistent cross-origin handling.
  • Composable security header configuration for Content-Security-Policy, Permissions-Policy, and HSTS.
  • Support for YAML root extensions (x- keys) used together with anchors in included configuration files.
  • LDAP group resolution through memberOf and search-based strategies, including caching for better performance.
  • Improved Lua backend result merging for groups and group DNs returned from backend processing.

Changed​

Processing and Operations​

  • Brute-force rule flushing now uses a structured flush plan with batched Redis operations for more consistent rule processing.
  • Scope handling was refined so implied scopes and client overrides are merged in a stable, deduplicated order.

Fixed​

Device Authorization Reliability​

  • OIDC device authorization flows now persist user snapshots more consistently and can rehydrate missing claims from stored snapshots during consent and token handling.
  • Error handling around incomplete device-flow claims was tightened to reduce authorization failures caused by partially persisted request state.

Upgrade Notes​

  1. If any OIDC clients still send refresh-token credentials in both HTTP Basic auth and the request body, explicitly enable the combined-auth compatibility flag only for those clients.
  2. Review CORS and security-header settings before rollout, because these controls can now be configured centrally and may replace ad-hoc edge behavior.
  3. If you use YAML anchors together with custom root-level extensions, you can now keep those patterns in included config files without triggering unknown-parameter handling.
  4. If you rely on group-based policy decisions, re-check LDAP and Lua-backed group mappings after the upgrade to take advantage of the expanded resolution and merge behavior.

2.1.3​

Released on April 17, 2026.

This patch release aligns Lua test mode with the production callback contracts and updates the shipped Lua examples and fixtures accordingly.

Fixed​

Lua test mode​

  • --test-lua now evaluates filter, feature, and backend callbacks with the same multi-value return contracts used in production.
  • Lua test fixtures and example scripts were updated so filter, feature, and backend examples use the production return values instead of simplified test-only forms.
  • Related documentation now reflects the real callback signatures for current and versioned 2.1 docs.

2.1.0​

Added​

Identity Provider​

  • SAML Single Logout request and response handling, including session fanout across participating services.
  • Optional signing support for SAML logout messages.
  • Validation support for signed SAML AuthnRequests.
  • Configurable legal notice and privacy policy links in the IdP footer and login pages.
  • Optional "Forgot password?" link on the login page.
  • Improved localized logout label handling and logout menu rendering.

OAuth/OIDC and Request Processing​

  • Improved OIDC metadata discovery and token endpoint handling.
  • URL-partial decoding for incoming request-header values used by Nginx, header-auth, and basic-auth integrations.
  • HTTP request cancellation propagation across the core authentication pipeline and Lua-backed actions.

Lua, Testing, and Operations​

  • Configuration validation mode via -config-check for validating configuration and exiting without starting the service.
  • Lua cache-flush hook support through lua.config.cache_flush_script_path and nauthilus_cache_flush(request).
  • Expanded ClickHouse integration with additional exported fields.
  • Reusable Lua builtin helper functions.
  • New Lua backend and action test frameworks with dbmock, plugin unit tests, miniredis, and order-sensitive mock expectations.

Changed​

Security and Reliability​

  • SAML signature validation is stricter and now includes additional signing configuration checks.
  • Header decoding is more robust through the new URL-partial-decoding path.
  • WebAuthn handling was refined with helper enhancements and an additional submission guard.
  • HTTP request cancellation handling in core and Lua actions was streamlined after the initial integration.

Cleanup and Tooling​

  • Removed an unused LDAP WebAuthn credentials filter from configuration handling.
  • Docker workflow OCI annotations were updated for index,manifest.
  • CI guardrails and test coverage were expanded around Lua plugins, Redis-backed tests, and reproducible fixes.

Upgrade Notes​

  1. If you use SAML Service Providers, review logout endpoints, bindings, and signing requirements before upgrading to 2.1.
  2. If you integrate Nauthilus via Nginx or header/basic auth, request-header values may now be URL-partially encoded and will be decoded before processing.
  3. If you use cache flush endpoints, you can now add a dedicated Lua cache-flush hook via lua.config.cache_flush_script_path.
  4. Consider adding -config-check to CI or deployment validation steps to fail fast on invalid configurations.