authentication

authentication

authentication is a production-oriented authentication library for Go services. It turns Basic credentials, opaque bearer tokens, API keys, JWTs, or OIDC ID tokens into an immutable principal. It does not decide whether that principal may perform an action.

The root, Basic, bearer, API-key, HTTP, logging, and test packages use only the Go standard library plus the narrow clock capability contracts. JWT, OIDC, and OpenTelemetry live in separate modules so their larger dependency graphs are opt-in.

Requirements

• Go 1.26 or newer.
• clock v1 for deterministic time seams.
• jwt: lestrrat-go/jwx v3.
• oidc: coreos/go-oidc v3 and go-jose v4.
• authotel: OpenTelemetry API v1.44.

Install

go get github.com/faustbrian/go-authentication

Add an optional module only when needed:

go get github.com/faustbrian/go-authentication/jwt
go get github.com/faustbrian/go-authentication/oidc
go get github.com/faustbrian/go-authentication/authotel

Five-minute quickstart

extractor, err := authhttp.NewExtractor(authhttp.BearerAuthorization())
if err != nil {
	return err
}

authenticator, err := bearer.New(bearer.ValidatorFunc(
	func(ctx context.Context, token string) (authentication.Principal, error) {
		if token != configuredToken {
			return authentication.Principal{},
				authentication.NewFailure(authentication.FailureRejected)
		}
		return authentication.NewPrincipal(authentication.PrincipalSpec{
			Subject: "orders-worker",
			Method:  "bearer",
		})
	},
))
if err != nil {
	return err
}

middleware, err := authhttp.NewMiddleware(extractor, authenticator)
if err != nil {
	return err
}

handler := middleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	principal, ok := authentication.PrincipalFromContext(r.Context())
	if !ok {
		http.Error(w, "authentication invariant failed", http.StatusInternalServerError)
		return
	}
	fmt.Fprintln(w, principal.Subject())
}))

The middleware is fail-closed. It authenticates and stores the principal, but it deliberately performs no role, permission, ownership, or policy checks.

Packages

Security defaults

• Credential values always format as redacted.
• Static secrets are compared through per-authenticator keyed HMAC-SHA-256 digests with constant-time comparison.
• Multiple credential sources are rejected as ambiguous.
• A 401 Unauthorized response is emitted only with at least one valid WWW-Authenticate challenge; missing challenge metadata fails as unavailable.
• Query and cookie credentials are disabled unless explicitly configured.
• Query credential constructors are deprecated for new designs because URLs can be retained before the extractor sees them.
• Claims, tokens, keys, HTTP bodies, and cache work have explicit bounds.
• JWT algorithms, issuer, audience, key ID, key metadata, and time claims are validated explicitly.
• OIDC uses upstream protocol verification with bounded synchronous JWK refresh and stale known-key availability during issuer outages.
• Instrumentation receives only credential kind, outcome, failure kind, and duration; it never receives credential or principal contents.

Documentation

Start with the quickstart. Protocol-specific guides are under docs/guides, including HTTP, JSON-RPC, service accounts, credential rotation, and anonymous routes. Operational and compatibility material is in docs/operations.md, docs/troubleshooting.md, and docs/compatibility.md. Observable protocol choices are recorded in the specification decision register.

For a security review or rollout, use the adoption checklist, threat model, findings, and test matrices.

The authentication-versus-authorization boundary is documented in docs/authentication-vs-authorization.md. Security reports follow SECURITY.md, and contributions follow CONTRIBUTING.md.

License

MIT. See LICENSE.

Ecosystem

Use the Golib documentation portal to choose companion packages, supported stacks, recipes, and operations guidance.