- Go 75.8%
- TypeScript 19.7%
- CSS 3.4%
- Go Template 0.6%
- Dockerfile 0.2%
- Other 0.3%
| backend | ||
| deploy/helm/auth-server | ||
| frontend | ||
| .dockerignore | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| README.md | ||
| renovate.json | ||
Auth Server
A small OIDC provider with Traefik forward auth and a user account UI. Go backend, React frontend, one Helm chart.
- Backend: Go, Gin, GORM, godotenv, go-libs (config and logging), gin-logrus. SQLite (default), MariaDB, PostgreSQL. No cgo.
- Frontend: React, Vite, TypeScript. Light and dark theme follow the system setting.
- Deploy: two images (backend, frontend) and one Helm chart. The ingress sends
/api,/oauth2,/.well-knownand/authto the backend, everything else to the UI.
Status
| Area | State |
|---|---|
| OIDC code flow with PKCE, token, userinfo, discovery, JWKS | done |
Traefik ForwardAuth (/auth/forward) and Middleware CRD in the chart |
done |
| Local users, bcrypt passwords, sessions | done |
Per-app group policy (allowed_groups) |
done |
| Auth history, allowed apps, password change in the UI | done |
Clients from a JSON file (CLIENTS_FILE) |
done |
| Tests, GitLab pipeline, Helm lint and render | done |
| Swagger / swaggo | not done |
| LDAP (and LDAP group sync, combined with local users) | not done |
| SAML | not done |
| TOTP 2FA, passkeys (also as passwordless login) | not done |
| Admin UI for users and clients | not done |
| CRDs for clients, auto-created secret per client in the app namespace | not done |
| Login rate limiting | not done |
| OIDC provider policies beyond group allow-list | not done |
Local development
cd backend
ISSUER=http://localhost:8080 ADMIN_PASSWORD=dev-admin-password go run ./cmd/server # API on :8080
cd frontend && npm ci && npm run dev # UI on :5173, proxies to :8080
Tests: cd backend && go test ./... and cd frontend && npm test.
Configuration
Environment variables. The server reads a .env file if present.
| Variable | Default | Purpose |
|---|---|---|
ISSUER |
– (required) | Public base URL. Becomes the OIDC iss claim |
LISTEN_ADDR |
:8080 |
HTTP listen address |
DB_DRIVER |
sqlite |
sqlite, mariadb or postgres |
DB_DSN |
data/auth.db |
SQLite file path, or the driver DSN for a server database |
SIGNING_KEY_PATH |
– | PKCS#8 RSA key (PEM). Without it a new key is made at each start |
CLIENTS_FILE |
– | JSON list of OIDC clients, upserted at start-up (see below) |
ADMIN_USERNAME / ADMIN_PASSWORD |
admin / – |
First user, created when missing, in group admins |
SESSION_TTL |
12h |
Browser session lifetime |
COOKIE_DOMAIN |
– | Set to the parent domain (e.g. example.com) so forward auth sees the session on app hosts |
COOKIE_SECURE |
true |
Secure flag on the session cookie |
TRUSTED_PROXIES |
– | CIDRs of the ingress, whose X-Forwarded-For is used for the auth history |
ALLOWED_RETURN_DOMAINS |
– | Domains a login may redirect to, besides the issuer host |
LOG_LEVEL |
INFO |
ERROR, WARN, INFO or DEBUG (go-libs) |
CLIENTS_FILE example. The secret is read from the env var named in client_secret_env and stored as a bcrypt hash.
Leave client_secret_env out for a public client, which then must use PKCE.
[
{
"client_id": "grafana",
"name": "Grafana",
"client_secret_env": "GRAFANA_OIDC_SECRET",
"redirect_uris": ["https://grafana.example.com/login/generic_oauth"],
"allowed_groups": ["admins"]
}
]
Traefik forward auth
The chart creates a Middleware (traefik.io/v1alpha1) named auth-forward in the release namespace. Apps use it with:
traefik.ingress.kubernetes.io/router.middlewares: <namespace>-auth-forward@kubernetescrd
Unauthenticated requests get a 302 to the login page with the original URL. Authenticated requests pass with the headers
X-Auth-User and X-Auth-Groups. Traefik overwrites client-sent copies of these headers.
Helm
helm install auth deploy/helm/auth-server --set host=auth.example.com \
--set signingKey.existingSecret=auth-signing --set secrets.existingSecret=auth-secrets
The secret auth-secrets needs ADMIN_PASSWORD, DB_DSN and one key per client_secret_env. The signing key secret
holds signing.pem. Without it, tokens stop working at every restart. Several backend replicas need a server database and
the signing key secret; the chart refuses other combinations.
Pipeline
.gitlab-ci.yml: backend gofmt, vet and tests; frontend typecheck, tests and build; both images; Helm lint, render and
push of the chart to the project's OCI registry.