Merge pull request #76 from systemli/feature/dovecot-sasl-auth

✨ Add Dovecot SASL authentication server

Author: 0x46616c6b

.env.example

@@ -5,6 +5,7 @@ ALIAS_LISTEN_ADDR=":10001"
 DOMAIN_LISTEN_ADDR=":10002"
 MAILBOX_LISTEN_ADDR=":10003"
 SENDERS_LISTEN_ADDR=":10004"
+SASL_LISTEN_ADDR=":10006"
 METRICS_LISTEN_ADDR=":10005"
 RATE_LIMIT_MESSAGE="Rate limit exceeded, please try again later"
 REDIS_URL="redis://redis:6379/0"

README.md

@@ -4,6 +4,7 @@
 
 This is a postfix socketmap adapter for the [userli](https://github.com/systemli/userli) project.
 It implements the [socketmap protocol](https://www.postfix.org/socketmap_table.5.html) to provide dynamic lookups for aliases, domains, mailboxes, and senders.
+It also provides a Dovecot SASL authentication server, allowing Postfix to authenticate SMTP clients against the Userli API without requiring Dovecot.
 
 ## Configuration
 
@@ -14,6 +15,7 @@ The adapter is configured via environment variables:
 - `POSTFIX_RECIPIENT_DELIMITER`: The recipient delimiter used in Postfix (e.g., `+`). Default: empty.
 - `SOCKETMAP_LISTEN_ADDR`: The address to listen on for socketmap requests. Default: `:10001`.
 - `POLICY_LISTEN_ADDR`: The address to listen on for policy requests (rate limiting). Default: `:10003`.
+- `SASL_LISTEN_ADDR`: The address to listen on for Dovecot SASL authentication. Supports TCP (e.g., `:10006`) and UNIX sockets (e.g., `/var/spool/postfix/private/auth`). Default: empty (disabled).
 - `METRICS_LISTEN_ADDR`: The address to listen on for metrics. Default: `:10002`.
 - `RATE_LIMIT_MESSAGE`: The rejection message returned when a sender exceeds their quota. Default: `Rate limit exceeded, please try again later`.
 - `REDIS_URL`: Connection URL for Redis (required). Format follows [`redis.ParseURL`](https://pkg.go.dev/github.com/redis/go-redis/v9#ParseURL), e.g. `redis://[user:password@]host:port/db`. Rate-limit state is stored in Redis so it survives restarts.
@@ -52,6 +54,28 @@ Where `0` means unlimited. If the API is unreachable, messages are allowed (fail
 
 Rate-limit state is persisted to Redis (`REDIS_URL`) so it survives restarts. If Redis is unreachable, messages are also allowed (fail-open) and the `userli_postfix_adapter_ratelimit_backend_errors_total` counter is incremented.
 
+### SASL Authentication (Dovecot SASL)
+
+The adapter implements the Dovecot SASL authentication protocol, so Postfix can authenticate SMTP clients via `smtpd_sasl_type=dovecot` without requiring Dovecot itself. Authentication is performed against the Userli API (`/api/postfix/auth`). Supported mechanisms: PLAIN and LOGIN.
+
+**Important:** SASL authentication is fail-closed. If the API is unreachable, authentication is rejected.
+
+Configure in Postfix `main.cf` (TCP):
+
+```text
+smtpd_sasl_type = dovecot
+smtpd_sasl_path = inet:localhost:10006
+smtpd_sasl_auth_enable = yes
+```
+
+Or using a UNIX socket (set `SASL_LISTEN_ADDR=/var/spool/postfix/private/auth`):
+
+```text
+smtpd_sasl_type = dovecot
+smtpd_sasl_path = private/auth
+smtpd_sasl_auth_enable = yes
+```
+
 ## Docker
 
 You can run the adapter using Docker.
@@ -178,6 +202,13 @@ The adapter exposes Prometheus metrics on `/metrics` (port 10002) and provides h
 - `userli_postfix_adapter_quota_checks_total` - Total quota checks performed
 - `userli_postfix_adapter_ratelimit_backend_errors_total` - Total Redis errors hit by the rate limiter, labelled by `operation`
 
+**SASL Authentication Metrics:**
+
+- `userli_postfix_adapter_sasl_active_connections` - Active SASL connections gauge
+- `userli_postfix_adapter_sasl_auth_total` - Total SASL authentication attempts (by mechanism and result)
+- `userli_postfix_adapter_sasl_auth_duration_seconds` - SASL authentication duration histogram
+- `userli_postfix_adapter_sasl_connection_pool_full_total` - SASL connection pool rejections
+
 All metrics include relevant labels (handler, status, endpoint, etc.).
 
 ### Health Endpoints

config.go

@@ -40,6 +40,11 @@ type Config struct {
 	// LookupCacheTTL is the TTL for cached successful lookup responses.
 	// Zero disables caching entirely.
 	LookupCacheTTL time.Duration
+
+	// SASLListenAddr is the address to listen for Dovecot SASL auth requests.
+	// Supports TCP (e.g. ":10004") or UNIX socket (e.g. "/var/spool/postfix/private/auth").
+	// Leave empty to disable the SASL auth server.
+	SASLListenAddr string
 }
 
 // NewConfig creates a new Config with default values.
@@ -93,6 +98,8 @@ func NewConfig() (*Config, error) {
 		lookupCacheTTL = parsed
 	}
 
+	saslListenAddr := os.Getenv("SASL_LISTEN_ADDR")
+
 	return &Config{
 		UserliBaseURL:             userliBaseURL,
 		UserliToken:               userliToken,
@@ -103,5 +110,6 @@ func NewConfig() (*Config, error) {
 		RateLimitMessage:          rateLimitMessage,
 		RedisURL:                  redisURL,
 		LookupCacheTTL:            lookupCacheTTL,
+		SASLListenAddr:            saslListenAddr,
 	}, nil
 }

docker-compose.yml

@@ -8,6 +8,7 @@ services:
       - "10001:10001"
       - "10002:10002"
       - "10003:10003"
+      - "10006:10006"
     env_file:
       - .env
     depends_on:
@@ -38,6 +39,9 @@ services:
       POSTFIX_virtual_mailbox_maps: "socketmap:inet:adapter:10001:mailbox"
       POSTFIX_smtpd_sender_login_maps: "socketmap:inet:adapter:10001:senders"
       POSTFIX_smtpd_end_of_data_restrictions: "check_policy_service inet:adapter:10003"
+      POSTFIX_smtpd_sasl_type: "dovecot"
+      POSTFIX_smtpd_sasl_path: "inet:adapter:10006"
+      POSTFIX_smtpd_sasl_auth_enable: "yes"
     networks:
       - userli
 

main.go

@@ -76,6 +76,12 @@ func main() {
 	wg.Add(1)
 	go StartPolicyServer(ctx, &wg, config.PolicyListenAddr, policyServer)
 
+	if config.SASLListenAddr != "" {
+		saslServer := NewSASLServer(userli, logger.Named("sasl"))
+		wg.Add(1)
+		go StartSASLServer(ctx, &wg, config.SASLListenAddr, saslServer)
+	}
+
 	wg.Wait()
 	logger.Info("All servers stopped")
 }

mock_UserliService.go

@@ -42,6 +42,10 @@ func (m *MockUserliServiceForPolicy) GetQuota(_ context.Context, _ string) (*Quo
 	return m.quota, nil
 }
 
+func (m *MockUserliServiceForPolicy) Authenticate(_ context.Context, _ string, _ string) (bool, string, error) {
+	return false, "", nil
+}
+
 func TestPolicyServer_ReadRequest(t *testing.T) {
 	input := `request=smtpd_access_policy
 protocol_state=END-OF-MESSAGE

policy_test.go

@@ -99,6 +99,28 @@ var (
 		Name: "userli_postfix_adapter_lookup_cache_total",
 		Help: "Total number of lookup cache events, by handler and result (hit, miss, error)",
 	}, []string{"handler", "result"})
+
+	// SASL server metrics
+	saslActiveConnections = prometheus.NewGauge(prometheus.GaugeOpts{
+		Name: "userli_postfix_adapter_sasl_active_connections",
+		Help: "Number of currently active SASL auth connections",
+	})
+
+	saslAuthTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "userli_postfix_adapter_sasl_auth_total",
+		Help: "Total number of SASL authentication attempts",
+	}, []string{"mechanism", "result"})
+
+	saslAuthDuration = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "userli_postfix_adapter_sasl_auth_duration_seconds",
+		Help:    "Duration of SASL authentication requests",
+		Buckets: prometheus.ExponentialBuckets(0.001, 2, 10),
+	}, []string{"mechanism", "result"})
+
+	saslConnectionPoolFullTotal = prometheus.NewCounter(prometheus.CounterOpts{
+		Name: "userli_postfix_adapter_sasl_connection_pool_full_total",
+		Help: "Total number of SASL connections rejected because the connection pool is full",
+	})
 )
 
 // StartMetricsServer starts a new HTTP server for prometheus metrics and health checks.
@@ -123,6 +145,10 @@ func StartMetricsServer(ctx context.Context, listenAddr string, userliClient Use
 		policyConnectionPoolFullTotal,
 		rateLimitBackendErrors,
 		lookupCacheTotal,
+		saslActiveConnections,
+		saslAuthTotal,
+		saslAuthDuration,
+		saslConnectionPoolFullTotal,
 	)
 
 	mux := http.NewServeMux()