Home

govengers/auth

Authentication and authorization for Go services on net/http (gin through an adapter), plus a forward-auth proxy image for Traefik. Module github.com/govengers/auth, Go 1.26, Apache 2.0.

Model

Every provider produces one auth.Identity. Password, OIDC and GitHub logins store it in a server-side session (session.Store; the cookie holds a random ID only). One session.Guard puts the stored identity into the request context or refuses the request: RequireAPI answers 401 JSON, RequireUI 302 to the login. API keys and JWTs put an identity into the context without a session. Handlers read it with auth.IdentityFrom(ctx). Authorization is an authorization.Check, a func(context.Context) error over that identity.

Core packages never log and never start goroutines; they report outcomes to an optional auth.Observer. Constructors are New(options *Options) (*X, error): they validate the options, copy what they keep, never write to your struct and fail at startup.

Packages

Import github.com/govengers/auth/...	Use it for	Page
(root) auth	Identity, Permission, IdentityFrom, Error + WriteError + ResponseFor, Observer, Hook, Route, RegisterRoutes, IdentityHandler	Errors-and-Observability, Authorization
session	Store (cookie + server-side values), Guard (RequireAPI, RequireUI), Impersonator, MemoryBackend, Refresher	Sessions
session/redisbackend	session backend shared by replicas	Sessions
password	username/email + password login, TOTP, registration; you implement Storage	Password
oidc	OIDC code flow login (Keycloak, Google, any IdP) and logout	OIDC
oidc/keycloak	roles, groups and attributes from the Keycloak Admin API as an OnLogin hook	OIDC
github	GitHub OAuth login, access by team, GitHub API calls as the user	GitHub
apikey	static or application-issued API keys	API-Keys
jwt	sign identities (forward auth) and verify them in a backend	JWT
authorization	Check primitives and All, Any, Not, Real	Authorization
ginadapter	net/http middleware and provider routes on gin, Require, wide-event Observe	Gin
prometheusadapter	Observer counting outcomes on your registry	Gin
cmd/forwardauth	the image ghcr.io/govengers/forwardauth for apps you do not change	Forward-Auth

Importing one provider compiles none of the others' dependencies. Heavy dependencies per package: session/redisbackend go-redis, password x/crypto and otp, oidc go-oidc, jwt jwx v3, ginadapter gin and wide-event-logger, prometheusadapter client_golang.

Which package for which need

• Users and password hashes live in your database: password + session. Example: examples/password.
• Users log in at Keycloak, Google or another OIDC IdP: oidc + session; add oidc/keycloak for composite roles and groups from the Admin API. Example: examples/oidc.
• Users log in with GitHub, access by team: github + session. Example on gin: examples/github.
• Machines call your API: apikey in front of the Guard.
• Your service sits behind the forward-auth image (or any jwt.Signer): jwt.Verifier, no sessions.
• You cannot change the app, or it is not Go: the forward-auth image.
• More than one replica: session/redisbackend.
• Admins act as a user (support): session.Impersonator on the same Guard. Sessions
• Several login methods at once: one Store and one Guard, every provider on that store; an OIDC provider per IdP with distinct Names.

Wiring order (session-based providers)

1. Backend: session.NewMemoryBackend(nil) (one replica) or redisbackend.New.
2. session.NewStore with a 32-byte EncryptionKey (session.ParseKey).
3. Provider New with Sessions: store.
4. session.NewGuard with LoginURL: provider.LoginURL() and the provider in Refreshers (password, GitHub).
5. auth.RegisterRoutes(serveMux, provider.Routes()) or ginadapter.RegisterRoutes(engine, ...); provider routes are never behind the Guard.
6. guard.RequireAPI() / RequireUI() around your routes, authorization checks after the Guard.

Pages

• Password: password login, Storage, TOTP, registration.
• OIDC: OIDC login and logout, Keycloak enrichment, Google.
• GitHub: GitHub login, teams, refresh, API client.
• Sessions: Store, Guard, backends, refresh, cookies.
• Authorization: identity fields, roles, permissions, checks, own checks.
• JWT: Signer, Verifier, backend verification.
• API-Keys: static keys and Resolver.
• Gin: ginadapter, prometheusadapter.
• Errors-and-Observability: auth.Error, status mapping, Observer, wide events.
• Forward-Auth: the image and its Traefik wiring.
• Forward-Auth-Configuration: compose, TLS and Kubernetes wiring, routes, environment variables, operations.
• Security: guarantees and known limits.
• Gotchas: the rules that are easy to get wrong.

Reference: README (overview), design (binding design, flows, decisions), migration (from go-basicauth, oidc-fwd-auth, github-fwd-auth), pkg.go.dev.