Skip to content

authn

Transport-agnostic request authentication for Go — API-key, JWT/OIDC, and mTLS verifiers, a verified Identity, and a pluggable authorization predicate. No HTTP or gRPC imports, so the same verifiers plug into either transport, or a tool calling them directly.

go get gitlab.com/phpboyscout/go/authn

gitlab.com/phpboyscout/go/authn separates the two questions every server has to answer — who are you? (a Verifier returns a verified Identity) and what may you do? (a single AuthorizeFunc predicate) — into small, testable primitives. It is the auth layer extracted from go-tool-base, where it backs both server transports.

Why

  • Framework-free. Only cockroachdb/errors and golang-jwt/jwt/v5 — no HTTP, no gRPC, no config framework, no go-tool-base. A depfootprint_test.go guard enforces the boundary.
  • Fail closed, leak nothing. A Verifier never encodes why authentication failed in a user-facing form. Callers map any verify error to a generic 401 / Unauthenticated and log the wrapped detail server-side; the ErrUnauthenticated sentinel never crosses the wire. See the security model.
  • authn ≠ authz. Verifiers authenticate; the AuthorizeFunc predicate authorizes. The package ships no policy engine — compose RequireScopes/RequireClaim or your own.

Where next

  • Getting started — build a working authenticated HTTP endpoint in about fifteen minutes.
  • Choose a verifier — API key vs JWT/OIDC vs mTLS, and how to configure each.
  • Authorize requests — AuthorizeFunc, RequireScopes, RequireClaim.
  • Reference — every constructor, config field, default, limit and error string.
  • Security model — fail-closed verification and the authn/authz split.
  • What authn does not do — the credentials it cannot verify and the features it deliberately lacks.

Does authn do what you need?

Three answers that save a wasted afternoon:

  • It verifies API keys, JWTs signed with an asymmetric key published in a JWKS, and client certificates. Nothing else — no HTTP Basic, no session cookies, no opaque token introspection.
  • It cannot verify a JWT signed with a shared secret. HS256 and friends are refused at construction, on purpose. See Symmetric-key JWTs are refused.
  • It is not an OIDC client. The only OIDC affordance is discovering a jwks_uri. There is no login flow.

Part of the phpboyscout Go toolkit — small, framework-free Go modules extracted from go-tool-base.

Further reading

The blog carries a curated route through this subject: Building a web service in Go collects everything written about it, ordered so you can start at the beginning rather than newest-first.

Ask phpbotscout

phpbotscout

He answers questions about the projects over on the Discord, citing the docs where they already cover it, and offering to raise an issue where they don't. Bring a bug, an idea, or a questionable engineering decision.

Join the Discord