auth-proxy/docs/security.md

Auth-gate Security Model

Authentication flow

1. Client request arrives at NGINX.
2. NGINX sends an internal auth_request subrequest to auth-gate.
3. Auth-gate checks:
   • Is the IP in the permanent whitelist? → Allow.
   • Is the IP in the temporary whitelist and not expired? → Allow.
   • Does the Authorization header contain valid Basic Auth? → Allow.
   • Otherwise → 401 Unauthorized.
4. NGINX passes the request to the upstream service if auth-gate returned 200.
5. NGINX returns 401 to the client if auth-gate returned 401/403.

IP handling

Permanent whitelist

• Loaded from a file mounted as a volume.
• The file is polled every 30 seconds (configurable).
• Only single IPs and CIDR ranges (as strings) are supported.
• The file is reloaded only when its mtime changes.

Temporary whitelist

• In-memory store.
• Entries expire after their TTL.
• The cleanup goroutine runs every 60 seconds (configurable) to remove expired entries.
• No persistence across restarts.

API key

The API key is the only secret for the /api/* endpoints. It's sent as a bearer token in the Authorization header.

• Keep it secret. Don't log it. Don't put it in the URL.
• Use a strong random string.
• Rotate it regularly.

Basic Auth

The Basic Auth credentials are set via environment variables. The username is admin by default, and the password is changeme by default.

• Change both immediately on first use.
• Use strong passwords.
• The credentials are sent in the Authorization header (base64-encoded).
• Always serve the auth endpoint over TLS.

File watcher

The permanent whitelist file watcher polls the file every 30 seconds. It only reloads if the file's mtime has changed. This means:

• Frequent touch-operations don't cause unnecessary reloads.
• The watcher is simple and doesn't depend on inotify.

Graceful shutdown

The service listens for SIGTERM and SIGINT. On signal:

1. Stop accepting new connections.
2. Close idle connections.
3. Wait for in-flight requests to complete (up to 30 seconds).
4. Exit.

This ensures Docker deployments can shut down cleanly.

What we don't do

• We don't support JWT/OAuth. If you need these, add them later.
• We don't support session state. The auth decision is made per-request.
• We don't support rate limiting. Use NGINX's limit_req for that.
• We don't support IP-based rate limiting. Use NGINX's limit_conn for that.
• We don't support IPv6. If you need IPv6, add it later.
• We don't support TLS. The auth endpoint should always be served over TLS.
• We don't support logging to a file. Logs go to stdout (Docker).
• We don't support metrics. If you need metrics, add them later.
• We don't support health checks with Prometheus. The /status endpoint is a simple text response.
• We don't support configuration via a config file. Use environment variables.
• We don't support multiple domains. The auth-gate service doesn't care about domains.
• We don't support HTTP/2. The auth-gate service uses HTTP/1.1 only.
• We don't support WebSocket. The auth-gate service doesn't need WebSocket.
• We don't support gRPC. The auth-gate service is a simple REST API.