auth-proxy

A lightweight Go auth proxy that sits in front of sensitive services (phpMyAdmin, Gitea, uptime kuma) and provides:

• IP-based whitelisting (permanent and temporary via REST API with TTL, stored in SQLite)
• No domain changes — NGINX continues to proxy to the same server_name

Architecture

Client ──NGINX auth_request──► auth-proxy ──► allow / deny

NGINX calls auth-proxy as an internal subrequest. On 200 the original request proceeds. On 401/403 NGINX returns the response to the client. Whitelisted IPs never see auth.

Build

go build -o auth-proxy ./src

Docker

docker build -t db123/auth-proxy:latest .

or

docker pull git.yejayekhoob.com/db123/auth-proxy:latest

Quick start

# Set required env vars (see .env.example)
cp .env.example .env
vim .env

# Start
./auth-proxy

Directory structure

├── src/
│   ├── main.go       — entry point
│   ├── auth.go       — HTTP handlers
│   ├── db.go         — database operations
│   ├── config.go     — configuration
│   ├── cleanup.go    — cleanup goroutine
│   └── auth_test.go  — unit tests
├── docs/
│   ├── api.md
│   ├── deploy.md
│   ├── design.md
│   └── security.md
├── Dockerfile
├── docker-compose.yml
├── go.mod
└── openapi.yaml

API

The API requires a bearer token set via AUTH_PROXY_API_TOKEN. All endpoints return 401 Unauthorized if the token is missing or invalid.

Method	Path	Description
POST	/api/whitelist/temp	Add a temporary whitelisted IP
GET	/api/whitelist/temp/list	List active temporary entries
DELETE	/api/whitelist/temp/{ip}	Remove a temporary entry
POST	/api/whitelist/perm	Add a permanent whitelisted IP/CIDR
GET	/api/whitelist/perm/list	List active permanent entries
DELETE	/api/whitelist/perm/{entry}	Remove a permanent entry
GET	/api/logs	Retrieve audit log entries
GET	/status	Health check with DB status

See docs/api.md for full API reference.

NGINX integration

See docs/deploy.md for the full NGINX auth_request configuration.

Documentation

• README.md — this file
• docs/api.md — API reference
• docs/security.md — security model and notes
• docs/deploy.md — deployment instructions
• docs/design.md — design rationale