No description
  • Go 75.8%
  • TypeScript 19.7%
  • CSS 3.4%
  • Go Template 0.6%
  • Dockerfile 0.2%
  • Other 0.3%
Find a file
2026-11-07 13:00:30 +01:00
backend Add OIDC provider, Traefik forward auth and account API 2026-11-07 12:51:35 +01:00
deploy/helm/auth-server Add Helm chart with split frontend and backend 2026-11-07 12:53:28 +01:00
frontend Serve security headers from each nginx location 2026-11-07 12:55:21 +01:00
.dockerignore Add Go module, ignore rules and backend image 2026-11-07 12:51:35 +01:00
.gitignore Add Go module, ignore rules and backend image 2026-11-07 12:51:35 +01:00
.gitlab-ci.yml Add GitLab pipeline for tests, images and the Helm chart 2026-11-07 12:53:28 +01:00
README.md Document the auth server and its status 2026-11-07 12:55:21 +01:00
renovate.json add renovate config 2026-11-07 13:00:30 +01:00

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-known and /auth to 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.