go-pkgz/auth: OAuth2, JWT, and direct login for Go

Where go-pkgz/auth fits in a Go service

go-pkgz/auth addresses a common problem in Go HTTP services: adding several login paths without designing each one independently. The library supports social login through GitHub, Google, Facebook, Microsoft, Twitter, Yandex, Battle.net, Apple, Patreon, Discord, and Telegram. It also supports custom OAuth2 providers, local development through a special dev provider, direct authentication against an application-supplied credential checker, and verified authentication through an application-supplied sender.

The intended users are backend developers who want reusable authentication infrastructure inside an HTTP router. go-pkgz/auth is a Go library rather than a complete user account product. Applications still supply OAuth2 client credentials, validate direct credentials, send verification messages, decide which token claims to retain, and implement storage-specific behavior where required.

Its scope extends beyond login callbacks. The library stores a JWT in a secure cookie with XSRF protection, supplies authentication and administration middleware, extracts user information from requests, supports multiple JWT audiences, provides pre-authentication and post-authentication hooks, and includes role-based access control. Avatar support includes an HTTP handler, local filesystem storage, BoltDB, GridFS, user-defined storage, and generated identicons. This makes it suitable when login identity and the authenticated user representation are part of the same service boundary. It is less attractive when the application already has a complete identity system and needs only one small provider callback.

The go-pkgz/auth request and token flow

Application code creates an auth.Opts value containing service-wide policy. The documented options include a SecretReader for JWT secrets, TokenDuration for token expiry, CookieDuration for the browser cookie, Issuer, URL, AvatarStore, and Validator. This separation leaves several decisions with the host application. For example, the SecretReader can return a secret for a token ID, while the Validator decides whether claims associated with that token should be accepted.

Providers are added to a service created by auth.NewService. Multiple providers can coexist, which allows a single service to expose GitHub and Facebook login at the same time. The service returns separate authentication and avatar handlers through service.Handlers. It also returns middleware through service.Middleware. A router can mount the handlers below /auth/ and /avatar/, then apply m.Auth to protected routes.

The token represents a small user profile. The README says the default scope requests only the user name, ID, and picture. Additional information can be stored in the token and retrieved at login. Blacklists use a user-defined validator, while pre-auth and post-auth hooks provide extension points for custom use cases. These are application-policy points rather than a fixed account database supplied by the library.

A subtle boundary is that a successful OAuth2 exchange does not make every incoming request new. Middleware checks the presented JWT and cookie state, then exposes user information to wrapped handlers. Applications still need to define what their protected routes permit, how roles are assigned, and how banned users are identified. The README documents the extension points but does not prescribe a particular application data model.

Installing go-pkgz/auth v2 and mounting protected routes

New projects should use the v2 module path. The README gives this installation command:

go get -u github.com/go-pkgz/auth/v2

After installation, create auth.Opts, construct the service, add at least one provider, and connect both handlers and middleware to an HTTP router. The following is the README example condensed to the configuration and routing flow:

options := auth.Opts{
	SecretReader: token.SecretFunc(func(id string) (string, error) {
		return "secret", nil
	}),
	TokenDuration:  time.Minute * 5,
	CookieDuration: time.Hour * 24,
	Issuer:         "my-test-app",
	URL:            "http://127.0.0.1:8080",
	AvatarStore:    avatar.NewLocalFS("/tmp"),
	Validator: token.ValidatorFunc(func(_ string, claims token.Claims) bool {
		return claims.User != nil && strings.HasPrefix(claims.User.Name, "dev_")
	}),
}

This configuration creates a five-minute token, a one-day cookie, and a validator that accepts only names beginning with dev_. The literal secret and /tmp path are example values, not production defaults.

Register real provider credentials and retrieve the authentication middleware:

service := auth.NewService(options)
service.AddProvider("github", "<Client ID>", "<Client Secret>")
service.AddProvider("facebook", "<Client ID>", "<Client Secret>")

m := service.Middleware()

The README's routegroup example leaves GET /open public, applies m.Auth to GET /private, and mounts the generated handlers at /auth/ and /avatar/. A chi example uses router.With(m.Auth).Get for the private route and router.Mount for the same handler groups. After routing and provider callback configuration are correct, the application listens on :8080 and exposes the provider-driven authentication endpoints.

Provider coverage, direct login, and extension costs

Provider breadth is a convenience, not a single universal abstraction with identical setup. Each OAuth2 provider still requires its own client ID, client secret, callback configuration, and agreement with that provider about the scopes used. The library supports multiple providers simultaneously, but the README does not claim that their user profiles or account-linking behavior are identical. A service that presents several login buttons must also decide whether accounts with the same email or provider subject should be linked.

Direct authentication follows a different trust model. The host application supplies a credential checker, so go-pkgz/auth is not responsible for defining password storage, hashing, password policy, or recovery. Verified authentication similarly depends on an application-supplied sender. Email, instant messaging, or another channel is described as a mechanism, but the sender implementation determines message delivery and verification behavior.

Custom providers add another configuration layer. The library can use a custom OAuth2 server or a third-party provider, which is useful when an identity endpoint is not among the named services. The trade-off is that standard provider behavior may not apply. Custom token parsing, profile mapping, or validation remains work for the adopter unless it matches an interface already handled by the package.

This breadth can also complicate upgrades. Custom storage, validators, hooks, senders, credential checkers, OAuth2 providers, and RefreshCache implementations all sit at boundaries where application assumptions may meet library interfaces. The README confirms role-based access control, avatar storage options, multiple audiences, and hook support, but it does not document a universal compatibility test for every possible combination.

Why go-pkgz/auth v2 changes existing integrations

Version 2 changes several types rather than only changing the import path. It moves JWT handling from github.com/golang-jwt/jwt/v3 to github.com/golang-jwt/jwt/v5. StandardClaims is replaced by RegisteredClaims. Expiration, not-before, and issued-at fields become *jwt.NumericDate instead of int64. The ID field changes from Id, and Audience changes from a string to []string.

The RefreshCache interface also becomes strongly typed. Its documented methods use token.Claims in Get and Set:

Get(key string) (value token.Claims, ok bool)
Set(key string, value token.Claims)

An existing implementation that accepted looser values will need to match these signatures. Code that manually inspects expiry or audience claims will not compile unchanged in many cases because both the field names and value types differ. The migration therefore affects application policy code, not just an import declaration.

The repository contains both top-level packages and a v2 directory, while the installation instructions point new projects to github.com/go-pkgz/auth/v2. The README explicitly identifies v2 as the actively developed version and recommends it for new projects. Existing applications should first locate custom Claims access, RefreshCache methods, audience assumptions, and tests that validate token parsing. The migration documentation also points to Remark42's migration pull request as an example of a service with extensive auth usage.

Where go-pkgz/auth is the wrong choice

The clearest wrong-tool case is a service that needs only one straightforward OAuth2 provider and already has its own session handling. In that situation, using this library requires adopting its token claims, cookie policy, handlers, middleware, and avatar model even if most optional features remain unused. A hand-built callback around an OAuth2 client may be less integration surface if the application already controls sessions.

The library is also a poor substitute for account lifecycle design. It offers direct authentication, but application code must supply the credential checker. It supports verified authentication, but application code supplies the sender. Neither feature by itself supplies password hashing, account recovery, message delivery, identity linking, or an administrative user directory. Assuming those responsibilities are already solved would leave security-sensitive product requirements undefined.

Avatar handling introduces another boundary. Local filesystem, BoltDB, GridFS, user-defined storage, and identicons are available, but selecting a durable storage backend is an infrastructure decision. The README does not document a default recommendation for production capacity, backup, replication, or cleanup.

License and release state also deserve attention. The repository uses the MIT license. The last push was on 2026-10-11, and release v2.3.1 was published on the same date. This indicates current repository activity at that point, but it does not eliminate migration work. Adopters must account for v2 interface changes and review their own extensions when upgrading.

go-pkgz/auth against direct OAuth2 and session code

The real alternative is not another Go package named in the repository documentation. It is the approach of implementing OAuth2 callbacks, cookie handling, token validation, request middleware, avatar storage, and user extraction directly inside the application. That approach gives an engineer full control over session format and route behavior, but every security-sensitive boundary remains application responsibility.

go-pkgz/auth reduces that assembly work by supplying named provider support, a shared Claims model, JWT cookie storage, XSRF protection, generated handlers, middleware, validators, hooks, and role-oriented wrappers. It is especially useful when the application wants GitHub, Google, Telegram, direct login, and email verification to sit behind one service object. The v1 to v2 migration notes also show that centralizing these concerns creates a shared contract across a codebase.

The direct implementation approach can be simpler when the service has one login mechanism and an established session package. It can also avoid unnecessary avatar, audience, blacklist, and role concepts. go-pkgz/auth earns its additional abstraction when those concerns are already part of the product or when several authentication modes need consistent token and middleware behavior. The choice should therefore be based on application scope, not on provider count alone.

Editorial conclusion

Adopt go-pkgz/auth/v2 when a Go HTTP service needs several authentication methods behind one middleware and claim model. Do not choose it merely for a single simple OAuth callback, and do not migrate until code that reads JWT claims or implements RefreshCache has been checked against the v2 API changes. The first implementation review should verify provider credentials, the public URL, secret management, token and cookie lifetimes, and whether application code depends on the changed Claims fields.

Frequently asked questions

Official sources

1. go-pkgz/auth on GitHub
2. License: MIT
3. Project website
4. README
5. Releases