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.27.0 or newer.
• clock v1 for deterministic time seams.
• jwt: lestrrat-go/jwx v3.
• oidc: coreos/go-oidc v3 and go-jose v4.
• adapters/otel: OpenTelemetry API v1.47.

Install

The root security-contract release v2.0.0 is published. Select its major-qualified import path:

go get github.com/faustbrian/go-authentication/v2@v2.0.0

The independently published optional modules below still consume root v1. They do not implement the root v2 nominal contracts; do not combine their v1 authenticators or instrumentation with root v2. Their own major adoptions follow publication of the root. Install these only for retained root v1 routes:

go get github.com/faustbrian/go-authentication/jwt
go get github.com/faustbrian/go-authentication/oidc
go get github.com/faustbrian/go-authentication/adapters/otel

Five-minute quickstart

extractor, err := authenticationhttp.NewExtractor(authenticationhttp.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 := authenticationhttp.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.

For ecosystem-wide package selection, construction, ownership, and lifecycle guidance, see the versioned Golib ecosystem index and its Service edge family.

Development

Use Go 1.27.2 and start with GOWORK=off go test ./... in the affected module. Install the published golib release declared by .golib.yaml, without building it from source. make check and make ci are bounded ordinary routes across five modules, including the pinned RFC vector guard and selected JWT shutdown race tests. The catalog has no required external services; OIDC retains its integration tag and configured-provider skip behavior.

Base-free local checks run deterministic fuzz seeds/corpus, not active fuzz campaigns. Use a focused native 2-second fuzz command for an affected parser; changed-source CI selects active smoke for affected targets. make check-full retains full campaigns, including explicit provider interoperability. See CONTRIBUTING.md for standalone commands, optional one-package mutation and local release qualification.

License

MIT. See LICENSE.

Continue with the documentation index.