nauthilus

module
v3.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: GPL-3.0

README

Release Build Unit Tests Guardrails Lua Plugin Tests Govulncheck CodeQL Docker Image Go Version

Nauthilus

Nauthilus is an authentication and identity platform written in Go. It combines classic authentication for mail and web workloads with an integrated identity provider for OIDC and SAML, plus MFA, WebAuthn, LDAP, Lua-based policy logic, and Redis-backed state handling.

Table of Contents

Overview

Nauthilus can be used as a central authentication service for infrastructure components such as mail servers, reverse proxies, and web applications. At the same time, it can act as a full identity provider with browser-based login and consent flows.

Typical use cases include:

  • Central authentication for IMAP, SMTP, and HTTP-facing services
  • LDAP-backed or Lua-driven authentication and authorization decisions
  • OIDC and SAML identity provider flows for modern applications
  • MFA enforcement with TOTP, WebAuthn, and recovery codes
  • Token, session, and flow state management with Redis

Core Features

  • Integrated IdP with OIDC and SAML 2.0 support
  • OIDC discovery, JWKS, userinfo, introspection, logout, device authorization, and consent flows
  • SAML SSO and SLO support
  • MFA with TOTP, WebAuthn, and recovery codes
  • LDAP integration for identity and credential lookups
  • Lua extensibility for custom backends, hooks, filters, and actions
  • Redis-backed flow, session, and token storage
  • Prometheus metrics and OpenTelemetry instrumentation
  • Bundled test clients and contrib tooling for OIDC, SAML, IMAP, SMTP, LDAP, and Grafana

Architecture at a Glance

  • server/ contains the main Nauthilus service
  • client/ contains a CSV-driven test and load client
  • contrib/oidctestclient/ and contrib/saml2testclient/ provide protocol-specific test clients
  • server/lua-plugins.d/ contains reusable Lua modules and plugin entry points
  • IDP.md documents the integrated identity provider in more detail

Project Layout

.
├── server/                 Main server
├── client/                 CSV-driven test/load client
├── contrib/                Additional tools, demos, and integrations
├── static/                 Static UI assets
├── testdata/               Test fixtures
├── IDP.md                  Integrated IdP documentation
├── Makefile                Common build and test targets
└── README.md               Project overview

Build and Test

Requirement: Go 1.26

Build the main binaries:

make build
make build-client

Run tests:

GOEXPERIMENT=runtimesecret make test
GOEXPERIMENT=runtimesecret make race

Run the local guardrails:

make guardrails

Documentation

Community

Mailing lists are available at:

https://lists.nauthilus.org

Support Nauthilus

Nauthilus is maintained as an open source project. If it saves you time or runs in your infrastructure, you can support ongoing development through:

Sponsorships and donations are appreciated, but never required to use Nauthilus under the GPLv3 license.

Commercial Support

Commercial support for Nauthilus is available for integration, customization, deployment guidance, and production troubleshooting.

For commercial inquiries, contact support@nauthilus.com or visit https://nauthilus.org.

License

This project is licensed under the GPLv3 License. See the LICENSE file for details.

Directories

Path Synopsis
Package main provides the blocklist command.
 Package main provides the blocklist command.
Package main provides the client command.
 Package main provides the client command.
engine
Package engine provides engine functionality.
 Package engine provides engine functionality.
contrib
csv2ldap command
Package main provides the csv2ldap command.
 Package main provides the csv2ldap command.
csv2ldap/engine
Package engine provides engine functionality.
 Package engine provides engine functionality.
encryption-secret-decoder command
Package main provides a Nauthilus encryption-secret decoder helper.
 Package main provides a Nauthilus encryption-secret decoder helper.
identity-proxy-e2e/cmd/smoke command
Package main runs the split identity proxy E2E smoke checks.
 Package main runs the split identity proxy E2E smoke checks.
imap-server command
Package main provides the imap server command.
 Package main provides the imap server command.
oidctestclient command
Package main provides the oidctestclient command.
 Package main provides the oidctestclient command.
plugins/clickhouse command
Package main provides the bundled ClickHouse native post-action plugin.
 Package main provides the bundled ClickHouse native post-action plugin.
plugins/geoip command
Package main implements the GeoIP native plugin reference build target.
 Package main implements the GeoIP native plugin reference build target.
plugins/haveibeenpwnd command
Package main provides the bundled Have I Been Pwned native post-action plugin.
 Package main provides the bundled Have I Been Pwned native post-action plugin.
plugins/internal/pluginutil
Package pluginutil contains narrow helpers shared by bundled native plugins.
 Package pluginutil contains narrow helpers shared by bundled native plugins.
saml2testclient command
Package main provides the saml2testclient command.
 Package main provides the saml2testclient command.
smtp-server command
Package main provides the smtp server command.
 Package main provides the smtp server command.
Package main provides the docker healthcheck command.
 Package main provides the docker healthcheck command.
internal
flagutil
Package flagutil provides shared helpers for CLI flag usage output.
 Package flagutil provides shared helpers for CLI flag usage output.
pluginapi
v1
Package pluginapi defines the stable public contract for native Nauthilus Go plugins.
 Package pluginapi defines the stable public contract for native Nauthilus Go plugins.
v1/exchange
Package exchange defines the public runtime exchange keyspace shared by Nauthilus plugins.
 Package exchange defines the public runtime exchange keyspace shared by Nauthilus plugins.
v1/helpers
Package helpers contains deterministic, non-secret helpers for native plugins.
 Package helpers contains deterministic, non-secret helpers for native plugins.
v1/password
Package password exposes Nauthilus-compatible password comparison and full password-hash helpers for native Go plugins without importing server internals.
 Package password exposes Nauthilus-compatible password comparison and full password-hash helpers for native Go plugins without importing server internals.
Command read_yaml_as_json converts YAML input into order-preserving JSON for converter tooling.
 Command read_yaml_as_json converts YAML input into order-preserving JSON for converter tooling.
list_config_syntax_keys command
Package main prints the known configuration syntax keys as JSON.
 Package main prints the known configuration syntax keys as JSON.
app/bootfx
Package bootfx provides bootfx functionality.
 Package bootfx provides bootfx functionality.
app/configfx
Package configfx provides configfx functionality.
 Package configfx provides configfx functionality.
app/envfx
Package envfx provides envfx functionality.
 Package envfx provides envfx functionality.
app/languagefx
Package languagefx provides languagefx functionality.
 Package languagefx provides languagefx functionality.
app/localizationfx
Package localizationfx wires declarative policy catalogs into startup and reload handling.
 Package localizationfx wires declarative policy catalogs into startup and reload handling.
app/logfx
Package logfx provides logfx functionality.
 Package logfx provides logfx functionality.
app/loopsfx
Package loopsfx provides loopsfx functionality.
 Package loopsfx provides loopsfx functionality.
app/opsfx
Package opsfx provides opsfx functionality.
 Package opsfx provides opsfx functionality.
app/policyfx
Package policyfx wires policy snapshot reloads into the runtime container.
 Package policyfx wires policy snapshot reloads into the runtime container.
app/redifx
Package redifx provides redifx functionality.
 Package redifx provides redifx functionality.
app/reloadfx
Package reloadfx provides reloadfx functionality.
 Package reloadfx provides reloadfx functionality.
app/restartfx
Package restartfx provides restartfx functionality.
 Package restartfx provides restartfx functionality.
app/signalsfx
Package signalsfx provides signalsfx functionality.
 Package signalsfx provides signalsfx functionality.
backend
Package backend provides backend functionality.
 Package backend provides backend functionality.
backend/accountcache
Package accountcache provides accountcache functionality.
 Package accountcache provides accountcache functionality.
backend/bktype
Package bktype provides bktype functionality.
 Package bktype provides bktype functionality.
backend/ldapendpoint
Package ldapendpoint parses LDAP URIs into secret-free endpoint metadata.
 Package ldapendpoint parses LDAP URIs into secret-free endpoint metadata.
backend/ldappool
Package ldappool provides ldappool functionality.
 Package ldappool provides ldappool functionality.
backend/priorityqueue
Package priorityqueue provides priorityqueue functionality.
 Package priorityqueue provides priorityqueue functionality.
backend/remote
Package remote implements edge-side backends backed by a Nauthilus authority.
 Package remote implements edge-side backends backed by a Nauthilus authority.
backendmonitoring
Package backendmonitoring provides backendmonitoring functionality.
 Package backendmonitoring provides backendmonitoring functionality.
bruteforce
Package bruteforce provides bruteforce functionality.
 Package bruteforce provides bruteforce functionality.
bruteforce/l1
Package l1 provides l1 functionality.
 Package l1 provides l1 functionality.
bruteforce/tolerate
Package tolerate provides tolerate functionality.
 Package tolerate provides tolerate functionality.
config
core
Package core provides core functionality.
 Package core provides core functionality.
core/auth
Package auth provides auth functionality.
 Package auth provides auth functionality.
core/cookie
Package cookie provides secure encrypted cookie management for storing sensitive session data in a single encrypted browser cookie.
 Package cookie provides secure encrypted cookie management for storing sensitive session data in a single encrypted browser cookie.
core/language
Package language provides language functionality.
 Package language provides language functionality.
core/localization
Package localization contains transport-neutral policy message localization.
 Package localization contains transport-neutral policy message localization.
definitions
Package definitions provides definitions functionality.
 Package definitions provides definitions functionality.
encoding/cborcodec
Package cborcodec centralizes the CBOR policy used by HTTP handlers and Lua helpers.
 Package cborcodec centralizes the CBOR policy used by HTTP handlers and Lua helpers.
errors
Package errors provides errors functionality.
 Package errors provides errors functionality.
frontend
Package frontend provides frontend functionality.
 Package frontend provides frontend functionality.
grpcapi/auth/v1
Package authv1 contains the versioned gRPC auth service contract.
 Package authv1 contains the versioned gRPC auth service contract.
grpcapi/common/v1
Package commonv1 contains shared gRPC transport messages used across versioned APIs.
 Package commonv1 contains shared gRPC transport messages used across versioned APIs.
grpcapi/identity/v1
Package identityv1 contains the versioned gRPC identity backend service contract.
 Package identityv1 contains the versioned gRPC identity backend service contract.
grpcapi/internal/prototest
Package prototest provides descriptor assertions for protobuf contract tests.
 Package prototest provides descriptor assertions for protobuf contract tests.
grpcclient/authority
Package authority contains outbound gRPC authority client helpers.
 Package authority contains outbound gRPC authority client helpers.
handler/api/v1
Package v1 provides v1 functionality.
 Package v1 provides v1 functionality.
handler/asyncjobs
Package asyncjobs provides asyncjobs functionality.
 Package asyncjobs provides asyncjobs functionality.
handler/auth
Package auth provides auth functionality.
 Package auth provides auth functionality.
handler/backchannel
Package backchannel provides backchannel functionality.
 Package backchannel provides backchannel functionality.
handler/bruteforce
Package bruteforce provides bruteforce functionality.
 Package bruteforce provides bruteforce functionality.
handler/cache
Package cache provides cache functionality.
 Package cache provides cache functionality.
handler/common
Package common provides common functionality.
 Package common provides common functionality.
handler/custom
Package custom provides custom functionality.
 Package custom provides custom functionality.
handler/deps
Package deps provides deps functionality.
 Package deps provides deps functionality.
handler/devui
Package devui provides devui functionality.
 Package devui provides devui functionality.
handler/frontend/idp
Package idp contains frontend handlers for IDP browser flows.
 Package idp contains frontend handlers for IDP browser flows.
handler/grpcauthority
Package grpcauthority adapts authority-side gRPC APIs to application services.
 Package grpcauthority adapts authority-side gRPC APIs to application services.
handler/health
Package health provides health functionality.
 Package health provides health functionality.
handler/metrics
handler/mfa_backchannel
Package mfa_backchannel provides mfa backchannel functionality.
 Package mfa_backchannel provides mfa backchannel functionality.
handler/registry
Package registry provides registry functionality.
 Package registry provides registry functionality.
idp
Package idp provides idp functionality.
 Package idp provides idp functionality.
idp/clientauth
Package clientauth provides OOP abstractions for OIDC client authentication endpoints.
 Package clientauth provides OOP abstractions for OIDC client authentication endpoints.
idp/flow
Package flow provides flow functionality.
 Package flow provides flow functionality.
idp/oidckeys
Package oidckeys provides oidckeys functionality.
 Package oidckeys provides oidckeys functionality.
idp/signing
Package signing provides OOP abstractions for JWT signing and verification.
 Package signing provides OOP abstractions for JWT signing and verification.
idp/slo
Package slo provides slo functionality.
 Package slo provides slo functionality.
internal/passwordhash
Package passwordhash contains bounded server-internal Redis hash compatibility.
 Package passwordhash contains bounded server-internal Redis hash compatibility.
ipscoper
Package ipscoper provides ipscoper functionality.
 Package ipscoper provides ipscoper functionality.
localcache
Package localcache provides localcache functionality.
 Package localcache provides localcache functionality.
log
Package log provides log functionality.
 Package log provides log functionality.
log/color
Package color provides ANSI color helpers and a slog.Handler wrapper that preserves slog.TextHandler formatting while coloring entire lines.
 Package color provides ANSI color helpers and a slog.Handler wrapper that preserves slog.TextHandler formatting while coloring entire lines.
log/level
Package level is a thin compatibility wrapper that mimics common go-kit/log/level usage patterns while delegating to the Go standard library's log/slog package.
 Package level is a thin compatibility wrapper that mimics common go-kit/log/level usage patterns while delegating to the Go standard library's log/slog package.
lualib
lualib/action
Package action provides action functionality.
 Package action provides action functionality.
lualib/bruteforce
Package bruteforce provides bruteforce functionality.
 Package bruteforce provides bruteforce functionality.
lualib/cacheflush
Package cacheflush executes the optional Lua callback used by cache flush endpoints.
 Package cacheflush executes the optional Lua callback used by cache flush endpoints.
lualib/connmgr
Package connmgr provides connmgr functionality.
 Package connmgr provides connmgr functionality.
lualib/convert
Package convert provides convert functionality.
 Package convert provides convert functionality.
lualib/environment
Package environment executes Lua environment source scripts.
 Package environment executes Lua environment source scripts.
lualib/hook
Package hook provides hook functionality.
 Package hook provides hook functionality.
lualib/luamod
Package luamod provides luamod functionality.
 Package luamod provides luamod functionality.
lualib/luapool
Package luapool provides a pool for reusing Lua states.
 Package luapool provides a pool for reusing Lua states.
lualib/luastack
Package luastack provides luastack functionality.
 Package luastack provides luastack functionality.
lualib/metrics
Package metrics provides metrics functionality.
 Package metrics provides metrics functionality.
lualib/pipeline
Package pipeline plans deterministic dependency levels for request-local Lua execution.
 Package pipeline plans deterministic dependency levels for request-local Lua execution.
lualib/policyschedule
Package policyschedule adapts policy script schedules to Lua execution plans.
 Package policyschedule adapts policy script schedules to Lua execution plans.
lualib/redislib
Package redislib provides redislib functionality.
 Package redislib provides redislib functionality.
lualib/smtp
Package smtp provides smtp functionality.
 Package smtp provides smtp functionality.
lualib/subject
Package subject executes Lua subject source scripts.
 Package subject executes Lua subject source scripts.
lualib/vmpool
Package vmpool provides per-key (backend/category) pools of reusable Lua VMs.
 Package vmpool provides per-key (backend/category) pools of reusable Lua VMs.
middleware/auth
Package auth provides auth functionality.
 Package auth provides auth functionality.
middleware/brmw
Package brmw provides brmw functionality.
 Package brmw provides brmw functionality.
middleware/compression
Package compression provides compression functionality.
 Package compression provides compression functionality.
middleware/cors
Package cors provides centralized CORS handling for HTTP routes.
 Package cors provides centralized CORS handling for HTTP routes.
middleware/csrf
Package csrf provides Cross-Site Request Forgery (CSRF) protection middleware for Gin.
 Package csrf provides Cross-Site Request Forgery (CSRF) protection middleware for Gin.
middleware/i18n
Package i18n provides i18n functionality.
 Package i18n provides i18n functionality.
middleware/limit
Package limit provides limit functionality.
 Package limit provides limit functionality.
middleware/logging
Package logging provides logging functionality.
 Package logging provides logging functionality.
middleware/lua
Package lua provides lua functionality.
 Package lua provides lua functionality.
middleware/metrics
Package metrics provides metrics functionality.
 Package metrics provides metrics functionality.
middleware/oidcbearer
Package oidcbearer provides a Gin middleware that validates Bearer tokens issued by the Nauthilus IDP (client_credentials flow).
 Package oidcbearer provides a Gin middleware that validates Bearer tokens issued by the Nauthilus IDP (client_credentials flow).
middleware/openapivalidation
Package openapivalidation contains the opt-in runtime request validation pilot for selected OpenAPI operations.
 Package openapivalidation contains the opt-in runtime request validation pilot for selected OpenAPI operations.
middleware/securityheaders
Package securityheaders provides securityheaders functionality.
 Package securityheaders provides securityheaders functionality.
middleware/zstdmw
Package zstdmw provides zstdmw functionality.
 Package zstdmw provides zstdmw functionality.
model/admin
Package admin provides admin functionality.
 Package admin provides admin functionality.
model/authdto
Package authdto provides authdto functionality.
 Package authdto provides authdto functionality.
model/bruteforce
Package bruteforce provides bruteforce functionality.
 Package bruteforce provides bruteforce functionality.
model/mfa
Package mfa provides mfa functionality.
 Package mfa provides mfa functionality.
model/rest
Package rest provides rest functionality.
 Package rest provides rest functionality.
monitoring
Package monitoring contains backend reachability and protocol health-check logic.
 Package monitoring contains backend reachability and protocol health-check logic.
monitoring/authmetrics
Package authmetrics provides bounded authentication response-boundary labels.
 Package authmetrics provides bounded authentication response-boundary labels.
monitoring/trace
Package trace provides trace functionality.
 Package trace provides trace functionality.
objpool
Package objpool provides objpool functionality.
 Package objpool provides objpool functionality.
openapi
Package openapi exposes embedded OpenAPI contracts for stable HTTP APIs.
 Package openapi exposes embedded OpenAPI contracts for stable HTTP APIs.
openapi/client
Package client exposes the supported production boundary around selected generated OpenAPI clients.
 Package client exposes the supported production boundary around selected generated OpenAPI clients.
openapi/generated/idp
Package idp provides primitives to interact with the openapi HTTP API.
 Package idp provides primitives to interact with the openapi HTTP API.
openapi/generated/management
Package management provides primitives to interact with the openapi HTTP API.
 Package management provides primitives to interact with the openapi HTTP API.
openapi/requesttest
Package requesttest provides reusable OpenAPI request-contract helpers for handler tests.
 Package requesttest provides reusable OpenAPI request-contract helpers for handler tests.
openapi/requestvalidation
Package requestvalidation provides OpenAPI request validation for selected HTTP boundaries.
 Package requestvalidation provides OpenAPI request validation for selected HTTP boundaries.
pluginloader
Package pluginloader verifies native plugin artifacts before loading them.
 Package pluginloader verifies native plugin artifacts before loading them.
pluginloader/cmd/nauthilus-plugin-sign command
Command nauthilus-plugin-sign creates and signs native plugin distribution keys.
 Command nauthilus-plugin-sign creates and signs native plugin distribution keys.
pluginregistry
Package pluginregistry records native plugin declarations before runtime execution is enabled.
 Package pluginregistry records native plugin declarations before runtime execution is enabled.
pluginruntime
Package pluginruntime owns native plugin lifecycle execution.
 Package pluginruntime owns native plugin lifecycle execution.
policy
Package policy contains shared vocabulary for the internal policy decision layer.
 Package policy contains shared vocabulary for the internal policy decision layer.
policy/collection
Package collection maps current auth mechanisms into policy check facts.
 Package collection maps current auth mechanisms into policy check facts.
policy/compiler
Package compiler defines the internal policy snapshot compiler boundary.
 Package compiler defines the internal policy snapshot compiler boundary.
policy/enforcement
Package enforcement defines the internal policy enforcement handoff boundary.
 Package enforcement defines the internal policy enforcement handoff boundary.
policy/evaluation
Package evaluation evaluates built-in policy decisions from collected facts.
 Package evaluation evaluates built-in policy decisions from collected facts.
policy/fsm
Package fsm evaluates policy-owned auth FSM markers.
 Package fsm evaluates policy-owned auth FSM markers.
policy/observability
Package observability contains policy logging, metric, and tracing helpers.
 Package observability contains policy logging, metric, and tracing helpers.
policy/registry
Package registry contains internal policy attribute registry primitives.
 Package registry contains internal policy attribute registry primitives.
policy/report
Package report contains redaction-aware policy decision report primitives.
 Package report contains redaction-aware policy decision report primitives.
policy/runtime
Package runtime contains policy snapshot activation primitives.
 Package runtime contains policy snapshot activation primitives.
policy/subjectschedule
Package subjectschedule classifies policy subject checks around the supported Lua/native boundary.
 Package subjectschedule classifies policy subject checks around the supported Lua/native boundary.
privilege
Package privilege implements chroot and privilege-drop (setuid/setgid) for the Nauthilus server process.
 Package privilege implements chroot and privilege-drop (setuid/setgid) for the Nauthilus server process.
processcache
Package processcache provides dependency-light process-local cache semantics.
 Package processcache provides dependency-light process-local cache semantics.
rediscli
Package rediscli contains Redis client helpers and key builders.
 Package rediscli contains Redis client helpers and key builders.
router
Package router provides router functionality.
 Package router provides router functionality.
secret
Package secret provides secret functionality.
 Package secret provides secret functionality.
security
Package security provides security functionality.
 Package security provides security functionality.
stats
svcctx
Package svcctx is a small package that provides a long-lived service/root context for the application.
 Package svcctx is a small package that provides a long-lived service/root context for the application.
testing/dbmock
Package dbmock provides dbmock functionality.
 Package dbmock provides dbmock functionality.
testing/luatest
testing/oteltest
Package oteltest provides config-independent OpenTelemetry test collection.
 Package oteltest provides config-independent OpenTelemetry test collection.
testing/tracetest
Package tracetest provides small OpenTelemetry helpers for focused tracing tests.
 Package tracetest provides small OpenTelemetry helpers for focused tracing tests.
util
util/contentneg
Package contentneg implements server-driven content negotiation against the HTTP Accept header following RFC 9110 section 12.5.1.
 Package contentneg implements server-driven content negotiation against the HTTP Accept header following RFC 9110 section 12.5.1.
util/crypto
Package crypto provides crypto functionality.
 Package crypto provides crypto functionality.
util/keygen
Package keygen provides keygen functionality.
 Package keygen provides keygen functionality.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.