8d25bda386
Update project structure to use a src/ directory layout and improve documentation across multiple files. - Update README.md build command to use ./src - Add directory structure documentation - Update status endpoint to include DB health status - Add pagination support (limit/offset) to whitelist list endpoints - Document new query parameters with examples - Update deployment guide to mark API token as required - Add testing instructions - Clarify audit log rotation in design documentation
94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
# auth-proxy
|
|
|
|
A lightweight Go auth proxyway 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
|
|
|
|
```bash
|
|
go build -o auth-proxy ./src
|
|
```
|
|
|
|
## Docker
|
|
|
|
```bash
|
|
docker build -t db123/auth-proxy:latest .
|
|
```
|
|
or
|
|
```bash
|
|
docker pull git.yejayekhoob.com/db123/auth-proxy:latest
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```bash
|
|
# 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
|