Getting Started with Nauthilus

This guide will help you understand, deploy, and configure Nauthilus for your environment.

What is Nauthilus?

Nauthilus is a universal authentication and authorization platform written in Go. It serves as a central hub for handling various authentication requests from different services such as:

Mail servers (SMTP, IMAP, POP3)
Web applications via OAuth2/OpenID Connect
Custom applications through its flexible API

Key features include:

Multiple authentication backends (LDAP, Lua scripts)
Redis-based caching for performance
Brute force attack protection
Realtime blackhole list (RBL) checking
Two-factor authentication support
OAuth2/OpenID Connect integration
Extensibility through Lua scripts

Prerequisites

Before deploying Nauthilus, ensure you have:

A system with Docker installed (for containerized deployment)
Redis server (standalone, master-replica, sentinel, or cluster)
Authentication backend (LDAP server or Lua scripts)
Basic understanding of YAML configuration

Deployment Options

Docker Deployment (Recommended)

Create a Docker Compose File

Create a docker-compose.yml file with Nauthilus and Redis:

version: '3'

services:
  nauthilus:
    image: nauthilus/nauthilus:latest
    ports:
      - "9443:9443"
    volumes:
      - ./config:/etc/nauthilus
    environment:
      - TZ=UTC
    depends_on:
      - redis

  redis:
    image: redis:alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes

volumes:
  redis-data:

Create Configuration Directory
```
mkdir -p config
```
Create Configuration File

Create config/nauthilus.yml with your configuration (see example below).
Start the Services
```
docker-compose up -d
```

Manual Installation

For manual installation, refer to the project documentation or build from source:

Clone the repository
Build the binary
Configure the service
Set up as a system service

Basic Configuration

Create a minimal nauthilus.yml configuration file:

server:
  address: "0.0.0.0:9443"  # Listen on all interfaces
  log:
    level: "info"
  redis:
    master:
      address: "redis:6379"  # Use "localhost:6379" for non-Docker setup
    password_nonce: "generate-a-random-string-here"
    pool_size: 10
    positive_cache_ttl: 3600s
    negative_cache_ttl: 7200s
  backends:
    - cache
    - ldap  # Or "lua" if using Lua backend

# LDAP Backend Configuration (if using LDAP)
ldap:
  config:
    server_uri: "ldap://ldap-server:389"
    bind_dn: "cn=admin,dc=example,dc=com"
    bind_pw: "password"
    lookup_pool_size: 8
    auth_pool_size: 8
  search:
    - protocol:
        - "imap"
        - "smtp"
        - "default"
      cache_name: "mail"
      base_dn: "ou=people,dc=example,dc=com"
      filter:
        user: "(&(objectClass=inetOrgPerson)(uid=%u))"
      mapping:
        account_field: "uid"
      attribute:
        - "uid"
        - "userPassword"

Configuration Structure

Nauthilus configuration consists of several main sections:

Server Configuration: Core settings for the server
Backend Configuration: Authentication backends (LDAP, Lua)
Feature Configuration: Optional features like RBL checks
Protocol Configuration: Settings for different protocols

Environment Variables

Some settings can be configured using environment variables. These are typically used for sensitive information like passwords. See the Reference for details.

Configuration File Location

By default, Nauthilus looks for its configuration file in these locations:

/usr/local/etc/nauthilus/nauthilus.yml
/etc/nauthilus/nauthilus.yml
$HOME/.nauthilus/nauthilus.yml
./nauthilus.yml (current directory)

Understanding Backends and Protocols

Backends

Nauthilus supports multiple authentication backends:

cache: Redis-based caching (should always be first)
ldap: LDAP directory service
lua: Custom Lua scripts

A typical configuration uses cache followed by either LDAP or Lua (or both):

server:
  backends:
    - cache
    - ldap
    - lua

Protocols

Protocols define how Nauthilus handles different types of authentication requests. When a client connects to Nauthilus, it specifies a protocol in the AUTH-Protocol header.

Each protocol can have its own configuration for:

Filters and attributes to retrieve
Cache prefixes for Redis storage
Authentication rules

Example protocol configuration for LDAP:

ldap:
  search:
    - protocol:
        - "imap"
        - "pop3"
      cache_name: "mail"
      base_dn: "ou=people,dc=example,dc=com"
      filter:
        user: "(&(objectClass=inetOrgPerson)(uid=%u))"
      mapping:
        account_field: "uid"
      attribute:
        - "uid"
        - "userPassword"

Redis Configuration

Redis is essential for Nauthilus as it stores authentication results, brute force detection data, and more. You can configure Redis in several ways:

Standalone or Master-Replica

server:
  redis:
    master:
      address: "redis:6379"
    replica:
      addresses:
        - "redis-replica:6379"

Redis Sentinel

server:
  redis:
    sentinels:
      master: "mymaster"
      addresses:
        - "sentinel1:26379"
        - "sentinel2:26379"
        - "sentinel3:26379"

Redis Cluster

server:
  redis:
    cluster:
      addresses:
        - "redis1:6379"
        - "redis2:6379"
        - "redis3:6379"

Integration Options

Mail Server Integration

Dovecot Integration (Recommended)

Dovecot can be integrated with Nauthilus using its Lua backend:

Configure Dovecot to use the HTTP authentication backend
Set up the Lua script to communicate with Nauthilus
Configure Nauthilus to handle Dovecot authentication requests

See the Dovecot Lua example for detailed instructions.

Nginx Mail Proxy

Nauthilus can be integrated with Nginx's mail module:

Configure Nginx to use the HTTP authentication backend
Set up Nginx to forward authentication requests to Nauthilus
Configure Nauthilus to handle Nginx authentication requests

See the Nginx mail plugin example for details.

Postfix with Cyrus SASL

For Postfix SMTP submission:

Configure Cyrus SASL to use the HTTP authentication backend
Set up Cyrus SASL to communicate with Nauthilus
Configure Nauthilus to handle SASL authentication requests

Note: This integration provides fewer features compared to Dovecot integration.

Web Application Integration (OAuth2/OpenID Connect)

For Single Sign-On (SSO) with web applications:

Set up Ory Hydra as the OAuth2/OpenID Connect provider
Configure Nauthilus as the login and consent provider for Hydra
Configure your load balancer to route authentication requests to Nauthilus

Example HAProxy configuration:

acl oidc path_beg,url_dec -m beg -i /login /device /consent /logout /2fa/v1 /notify /static

use_backend be_nauthilus_oidc if oidc

backend be_nauthilus_oidc
  mode http
  balance roundrobin
  option forwardfor
  http-check connect ssl alpn h2,http/1.1
  http-check send meth GET uri /ping body "pong"
  http-check expect status 200
  server nauthilus1 nauthilus:9443 check ssl

Security Features

Brute Force Protection

Configure brute force protection to prevent password guessing attacks:

server:
  brute_force_protocols:
    - imap
    - smtp
    - submission
    - ory-hydra

brute_force:
  buckets:
    - name: b_1min_ipv4_32
      period: 60
      cidr: 32
      ipv4: true
      failed_requests: 10

Realtime Blackhole Lists (RBL)

Check client IP addresses against RBL services:

server:
  features:
    - rbl

realtime_blackhole_lists:
  threshold: 10
  lists:
    - name: "SpamRats AuthBL"
      rbl: "auth.spamrats.com"
      ipv4: true
      ipv6: false
      return_code: "127.0.0.43"
      weight: 10

Monitoring and Maintenance

Health Checks

Nauthilus provides a /ping endpoint that returns "pong" when the service is healthy.

Reloading Configuration

To reload the configuration without restarting Nauthilus:

kill -HUP $(pidof nauthilus)

For changes to web server settings, follow with:

kill -SIGUSR1 $(pidof nauthilus)

Metrics

Enable Prometheus metrics for monitoring:

server:
  prometheus_timer:
    enabled: true
    labels:
      - request
      - backend
      - brute_force

Troubleshooting

Common Issues

Authentication Failures
- Check LDAP connection and credentials
- Verify protocol configuration matches client requests
- Examine Redis connectivity
Performance Issues
- Increase Redis pool size
- Optimize LDAP queries
- Enable caching for frequently used requests
Configuration Errors
- Validate YAML syntax
- Check log files for configuration parsing errors
- Ensure all required fields are provided

Logging

Increase log verbosity for troubleshooting:

server:
  log:
    level: debug
    debug_modules:
      - auth
      - ldap
      - cache

Next Steps

After basic setup, consider exploring:

Advanced Configuration - Detailed configuration options
LDAP Backend - LDAP integration details
Lua Backend - Custom authentication with Lua
OAuth2 Configuration - Setting up SSO
Full Configuration Example - Complete configuration reference

Getting Help

Visit the official website
Subscribe to the mailing lists
Check the documentation
Consider commercial support for enterprise deployments

What is Nauthilus?​

Prerequisites​

Deployment Options​

Docker Deployment (Recommended)​

Manual Installation​

Basic Configuration​

Configuration Structure​

Environment Variables​

Configuration File Location​

Understanding Backends and Protocols​

Backends​

Protocols​

Redis Configuration​

Standalone or Master-Replica​

Redis Sentinel​

Redis Cluster​

Integration Options​

Mail Server Integration​

Dovecot Integration (Recommended)​

Nginx Mail Proxy​

Postfix with Cyrus SASL​

Web Application Integration (OAuth2/OpenID Connect)​

Security Features​

Brute Force Protection​

Realtime Blackhole Lists (RBL)​

Monitoring and Maintenance​

Health Checks​

Reloading Configuration​

Metrics​

Troubleshooting​

Common Issues​

Logging​

Next Steps​

Getting Help​