auth - authentication via oauth2, direct and email

This library provides "social login" with Github, Google, Facebook, Microsoft, Twitter, Yandex, Battle.net, Apple, Patreon, Discord and Telegram as well as custom auth providers and email verification.

• Multiple oauth2 providers can be used at the same time
• Special dev provider allows local testing and development
• JWT stored in a secure cookie with XSRF protection. Cookies can be session-only
• Minimal scopes with user name, id and picture (avatar) only
• Direct authentication with user's provided credential checker
• Verified authentication with user's provided sender (email, im, etc)
• Custom oauth2 server and ability to use any third party provider
• Integrated avatar proxy with an FS, boltdb and gridfs storage
• Support of user-defined storage for avatars
• Identicon for default avatars
• Black list with user-defined validator
• Multiple aud (audience) supported
• Secure key with customizable SecretReader
• Ability to store an extra information to token and retrieve on login
• Pre-auth and post-auth hooks to handle custom use cases.
• Middleware for easy integration into http routers
• Wrappers to extract user info from the request
• Role based access control

v1 vs v2 Differences

The v2 version of this library is now the actively developed version, and we recommend using it for new projects. Key differences include:

• JWT library updated to use github.com/golang-jwt/jwt/v5 (from v3)
• JWT token claims use modern structures from jwt/v5:
  • StandardClaims replaced with RegisteredClaims
  • Claims.ExpiresAt changed from int64 to *jwt.NumericDate
  • Claims.NotBefore changed from int64 to *jwt.NumericDate
  • Claims.IssuedAt changed from int64 to *jwt.NumericDate
  • ID field renamed from Id
  • Audience changed from string to []string
• RefreshCache interface signatures updated to use strongly typed values:
  • Get(key string) (value token.Claims, ok bool)
  • Set(key string, value token.Claims)
• Improved type safety for various interfaces and functions

To migrate from v1 to v2:

1. Update import paths to use /v2 (e.g., github.com/go-pkgz/auth/v2)
2. Update any custom code that accesses token fields to use the new structures
3. If implementing RefreshCache interface, update method signatures

Install

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

Usage

Example with routegroup (stdlib-based router):

func main() {
	// define options
	options := auth.Opts{
		SecretReader: token.SecretFunc(func(id string) (string, error) { // secret key for JWT
			return "secret", nil
		}),
		TokenDuration:  time.Minute * 5, // token expires in 5 minutes
		CookieDuration: time.Hour * 24,  // cookie expires in 1 day and will enforce re-login
		Issuer:         "my-test-app",
		URL:            "http://127.0.0.1:8080",
		AvatarStore:    avatar.NewLocalFS("/tmp"),
		Validator: token.ValidatorFunc(func(_ string, claims token.Claims) bool {
			// allow only dev_* names
			return claims.User != nil && strings.HasPrefix(claims.User.Name, "dev_")
		}),
	}

	// create auth service with providers
	service := auth.NewService(options)
	service.AddProvider("github", "<Client ID>", "<Client Secret>")   // add github provider
	service.AddProvider("facebook", "<Client ID>", "<Client Secret>") // add facebook provider

	// retrieve auth middleware
	m := service.Middleware()

	// setup http server
	router := routegroup.New(http.NewServeMux())
	router.HandleFunc("GET /open", openRouteHandler) // open api
	router.Group().Route(func(r *routegroup.Bundle) {
		r.Use(m.Auth)
		r.HandleFunc("GET /private", protectedRouteHandler) // protected api
	})

	// setup auth routes
	authRoutes, avaRoutes := service.Handlers()
	router.Handle("/auth/", authRoutes) // add auth handlers
	router.Handle("/avatar/", avaRoutes) // add avatar handler

	log.Fatal(http.ListenAndServe(":8080", router))
}

func main() {
	// define options
	options := auth.Opts{
		SecretReader: token.SecretFunc(func(id string) (string, error) { // secret key for JWT
			return "secret", nil
		}),
		TokenDuration:  time.Minute * 5, // token expires in 5 minutes
		CookieDuration: time.Hour * 24,  // cookie expires in 1 day and will enforce re-login
		Issuer:         "my-test-app",
		URL:            "http://127.0.0.1:8080",
		AvatarStore:    avatar.NewLocalFS("/tmp"),
		Validator: token.ValidatorFunc(func(_ string, claims token.Claims) bool {
			// allow only dev_* names
			return claims.User != nil && strings.HasPrefix(claims.User.Name, "dev_")
		}),
	}

	// create auth service with providers
	service := auth.NewService(options)
	service.AddProvider("github", "<Client ID>", "<Client Secret>")   // add github provider
	service.AddProvider("facebook", "<Client ID>", "<Client Secret>") // add facebook provider

	// retrieve auth middleware
	m := service.Middleware()

	// setup http server
	router := chi.NewRouter()
	router.Get("/open", openRouteHandler)                      // open api
	router.With(m.Auth).Get("/private", protectedRouteHandler) // protected api

	// setup auth routes
	authRoutes, avaRoutes := service.Handlers()
	router.Mount("/auth", authRoutes)  // add auth handlers
	router.Mount("/avatar", avaRoutes) // add avatar handler

	log.Fatal(http.ListenAndServe(":8080", router))
}

Middleware

github.com/go-pkgz/auth/middleware provides ready-to-use middleware.

• middleware.Auth - requires authenticated user
• middleware.Admin - requires authenticated admin user
• middleware.Trace - doesn't require authenticated user, but adds user info to request
• middleware.RBAC - requires authenticated user with passed role(s)

Also, there is a special middleware middleware.UpdateUser for population and modifying UserInfo in every request. See "Customization" for more details.

Details

Generally, adding support of auth includes a few relatively simple steps:

1. Setup auth.Opts structure with all parameters. Each of them documented and most of parameters are optional and have sane defaults.
2. Create the new auth.Service with provided options.
3. Add all desirable authentication providers.
4. Retrieve middleware and http handlers from auth.Service
5. Wire auth and avatar handlers into http router as sub–routes.

API

For the example above authentication handlers wired as /auth and provides:

• /auth/<provider>/login?site=<site_id>&from=<redirect_url> - site_id used as aud claim for the token and can be processed by SecretReader to load/retrieve/define different secrets. redirect_url is the url to redirect after successful login. When Opts.AllowedRedirectHosts is set, only targets whose host matches Opts.URL or appears in the allowlist are honoured; others fall back to the user-info JSON response. With the default (nil) allowlist any non-empty from is honoured — see "Allowed redirect hosts" below for the opt-in details.
• /avatar/<avatar_id> - returns the avatar (image). Links to those pictures added into user info automatically, for details see "Avatar proxy"
• /auth/<provider>/logout and /auth/logout - invalidate "session" by removing JWT cookie
• /auth/list - gives a json list of active providers
• /auth/user - returns token.User (json)
• /auth/status - returns status of logged in user (json)

User info

Middleware populates token.User to request's context. It can be loaded with token.GetUserInfo(r *http.Request) (user User, err error) or token.MustGetUserInfo(r *http.Request) User functions.

token.User object includes all fields retrieved from oauth2 provider:

• Name - user name
• ID - hash of user id
• Picture - full link to proxied avatar (see "Avatar proxy")

It also has placeholders for fields application can populate with custom token.ClaimsUpdater (see "Customization")

• IP - hash of user's IP address
• Email - user's email
• Attributes - map of string:any-value. To simplify management of this map some setters and getters provided, for example users.StrAttr, user.SetBoolAttr and so on. See user.go for more details.

Avatar proxy

Direct links to avatars won't survive any real-life usage if they linked from a public page. For example, page like this may have hundreds of avatars and, most likely, will trigger throttling on provider's side. To eliminate such restriction auth library provides an automatic proxy

• On each login the proxy will retrieve user's picture and save it to AvatarStore
• Local (proxied) link to avatar included in user's info (jwt token)
• API for avatar removal provided as a part of AvatarStore
• User can leverage one of the provided stores:
  • avatar.LocalFS - file system, each avatar in a separate file
  • avatar.BoltDB - single boltdb file (embedded KV store).
  • avatar.GridFS - external GridFS (mongo db).
• In case of need custom implementations of other stores can be passed in and used by auth library. Each store has to implement avatar.Store interface.
• All avatar-related setup done as a part of auth.Opts and needs:
  • AvatarStore - avatar store to use, i.e. avatar.NewLocalFS("/tmp/avatars") or more generic avatar.NewStore(uri)
    • file system uri - file:///tmp/location or just /tmp/location
    • boltdb - bolt://tmp/avatars.bdb
    • mongo - "mongodb://127.0.0.1:27017/test?ava_db=db1&ava_coll=coll1
  • AvatarRoutePath - route prefix for direct links to proxied avatar. For example /api/v1/avatars will make full links like this - http://example.com/api/v1/avatars/1234567890123.image. The url will be stored in user's token and retrieved by middleware (see "User Info")
  • AvatarResizeLimit - size (in pixels) used to resize the avatar. Pls note - resize happens once as a part of Put call, i.e. on login. 0 size (default) disables resizing.

Direct authentication

In addition to oauth2 providers auth.Service allows to use direct user-defined authentication. This is done by adding direct provider with auth.AddDirectProvider.

	service.AddDirectProvider("local", provider.CredCheckerFunc(func(user, password string) (ok bool, err error) {
		ok, err = checkUserSomehow(user, password)
		return ok, err
	}))

Such provider acts like any other, i.e. will be registered as /auth/local/login.

The API for this provider supports both GET and POST requests:

• POST request could be encoded as application/x-www-form-urlencoded or application/json:

  POST /auth/<name>/login?session=[1|0]
  body: application/x-www-form-urlencoded
  user=<user>&passwd=<password>&aud=<site_id>
  

  POST /auth/<name>/login?session=[1|0]
  body: application/json
  {
    "user": "name",
    "passwd": "xyz",
    "aud": "bar",
  }
  

• GET request with user credentials provided as query params, but be aware that the https query string is not secure:

  GET /auth/<name>/login?user=<user>&passwd=<password>&aud=<site_id>&session=[1|0]
  

note: password parameter doesn't have to be naked/real password and can be any kind of password hash prepared by caller.

note: session=1 makes the auth cookie session-only, i.e. dropped when the browser closes. sess is accepted as an alias for backward compatibility.

Verified authentication

Another non-oauth2 provider allowing user-confirmed authentication, for example by email or slack or telegram. This is done by adding confirmed provider with auth.AddVerifProvider.

    msgTemplate := "Confirmation email, token: {{.Token}}"
	service.AddVerifProvider("email", msgTemplate, sender)

Message template may use the follow elements:

• {{.Address}} - user address, for example email
• {{.User}} - user name
• {{.Token}} - confirmation token
• {{.Site}} - site ID

Sender should be provided by end-user and implements a single function interface

type Sender interface {
	Send(address string, text string) error
}

For convenience a functional wrapper SenderFunc provided. Email sender provided in provider/sender package and can be used as Sender.

The API for this provider:

• GET /auth/<name>/login?user=<user>&address=<address>&aud=<site_id>&from=<url> - send confirmation request to user. site is accepted as an alias for aud. When host validation is enabled via Opts.AllowedRedirectHosts, the from URL is subject to the same allowlist check described in "Allowed redirect hosts"; otherwise any non-empty value is honoured.
• GET /auth/<name>/login?token=<conf.token>&session=[1|0] - authorize with confirmation token, sess is accepted as an alias for session

The provider acts like any other, i.e. will be registered as /auth/email/login.

Only a signed handshake token that carries this provider's name is accepted for login. Session tokens, confirmations issued by another verify provider, and handshake tokens an application mints without this provider's name are rejected, even though they are signed with the same secret.

Confirmation token replay protection

Confirmation tokens are one-shot: a token redeemed once cannot be redeemed again within its TTL. This stops anyone with read access to the email link (forwarded mail, mail-gateway logs, mailbox archive) from independently consuming it after the user has.

By default the library installs an in-memory store on first call to AddVerifProvider. This is correct for single-instance deployments.

Multi-instance deployments behind a load balancer MUST supply a shared backend. With the default in-memory store, replay protection works only on the instance that originally consumed the token; an attacker who hits any other instance can still replay within the TTL. This is silent: the request succeeds and the auth flow completes normally, with no log indicating the protection was bypassed. Plug in Redis or any shared KV by setting Opts.VerifConfirmationStore to a value implementing provider.VerifConfirmationStore:

type VerifConfirmationStore interface {
    // MarkUsed records key as consumed and returns alreadyUsed=true if it was
    // already recorded. err signals a backend failure -- callers fail-closed
    // (reject the redemption) on non-nil err to avoid replay during outages.
    MarkUsed(key string, ttl time.Duration) (alreadyUsed bool, err error)
}

The store key is the SHA-256 of the raw confirmation token, so existing tokens issued before this protection landed are de-dup'd correctly without changing the wire format. Consumption is final: a transient downstream failure after the mark burns the token; the user must request a new confirmation email rather than retry the same link.

Email-as-identity caveat

The verify provider returns a local user id of the form <provider>_<sha1(address)>. The confirmation round-trip proves current control of the address at the moment of login; it does not prove stable+unique identity over time. The owner of an address can change without the address changing:

• Employer offboarding — [email protected] returns to the company when Alice leaves and may be reassigned to a new employee.
• Lapsed free-mail accounts — providers reclaim and recycle inactive mailboxes; the next person who registers the same handle inherits any service that keys on the address.
• Domain recycling — when a personal domain is not renewed and is re-registered, the new owner can receive mail for every local part it ever had.

This is inherent to email-as-identity, not specific to this library — the verify flow has no upstream identifier (such as an OIDC sub) it could fall back on. Any application that keys its own records directly on the returned id will treat the new owner of an address as the original user.

Integrators that need stable identity should:

• Map the verified address to a server-side immutable user id (e.g., a users table primary key) at first successful verify, and key application records, ACLs, and audit logs on that internal id rather than on the value returned by the provider.
• Treat a verified address whose internal id is missing as a new account, not as a reactivation of an old one.
• For higher-stakes systems, consider re-verification policies (re-prove address control after long inactivity) and reuse-detection signals before granting access to historical data.

If your threat model accepts that whoever currently controls an address gets the corresponding account (e.g. low-stakes commenting), no extra handling is required — but the property should be a deliberate choice, not an inherited default.

Email

For email notify provider, please use github.com/go-pkgz/auth/provider/sender package:

	sndr := sender.NewEmailClient(sender.EmailParams{
		Host:               "email.hostname",
		Port:               567,
		HELOHost:           "mail.example.com", // optional, greeting hostname, defaults to localhost
		SMTPUserName:       "username",
		SMTPPassword:       "pass",
		StartTLS:           true,
		InsecureSkipVerify: false,
		From:               "[email protected]",
		Subject:            "subject",
		ContentType:        "text/html",
		Charset:            "UTF-8",
	}, log.Default())
	authenticator.AddVerifProvider("email", "template goes here", sndr)

See that documentation for full options list.

Telegram

Telegram provider allows your users to log in with Telegram account. First, you will need to create your bot. Contact @BotFather and follow his instructions to create your own bot (call it, for example, "My site auth bot")

Next initialize TelegramHandler with following parameters:

• ProviderName - Any unique name to distinguish between providers
• SuccessMsg - Message sent to user on successfull authentication
• ErrorMsg - Message sent on errors (e.g. login request expired)
• Telegram - Telegram API implementation. Use provider.NewTelegramAPI with following arguments
  1. The secret token bot father gave you
  2. An http.Client for accessing Telegram API's

token := os.Getenv("TELEGRAM_TOKEN")

telegram := provider.TelegramHandler{
	ProviderName: "telegram",
	ErrorMsg:     "❌ Invalid auth request. Please try clicking link again.",
	SuccessMsg:   "✅ You have successfully authenticated!",
	Telegram:     provider.NewTelegramAPI(token, http.DefaultClient),

	L:            log.Default(),
	TokenService: service.TokenService(),
	AvatarSaver:  service.AvatarProxy(),
}

After that run provider and register it's handlers:

// Run Telegram provider in the background
go func() {
	err := telegram.Run(context.Background())
	if err != nil {
		log.Fatalf("[PANIC] failed to start telegram: %v", err)
	}
}()

// Register Telegram provider
service.AddCustomHandler(&telegram)

Avatar handling

Telegram's file API requires the bot token in the URL path (https://api.telegram.org/file/bot<TOKEN>/...), so the URL is a bearer credential and must never reach the JWT, the user JSON, or any debug log. The provider fetches the avatar bytes server-side and stores them via AvatarSaver, returning a clean local proxy URL.

This requires AvatarSaver to support direct content saving. avatar.Proxy (the default returned by service.AvatarProxy()) does -- no extra setup needed. Custom AvatarSaver implementations that don't implement PutContent(userID string, content io.Reader) (string, error) will see an empty User.Picture for Telegram logins, and the avatar proxy will fall back to identicon. To preserve avatars with a custom saver, implement that method alongside Put.

Behaviour change for custom AvatarSaver: before this change, custom savers received the raw Telegram file URL (which included the bot token) via Put. After this change they no longer do, because that URL is a bearer credential. Implementations that relied on receiving and refetching that URL must now implement PutContent to keep saving Telegram avatars, or accept that Telegram users get identicons.

Now all your users have to do is click one of the following links and press start tg://resolve?domain=<botname>&start=<token> or https://t.me/<botname>/?start=<token>

Use the following routes to interact with provider:

1. /auth/<providerName>/login - Obtain auth token. Returns JSON object with bot (bot username) and token (token itself) fields.

2. /auth/<providerName>/login?token=<token> - Check if auth request has been confirmed (i.e. user pressed start). Sets session cookie and returns user info on success, errors with 404 otherwise.

3. /auth/<providerName>/logout - Invalidate user session.

Custom oauth2

This provider brings two extra functions:

1. Adds ability to use any third-party oauth2 providers in addition to the list of directly supported. Included example demonstrates how to do it for bitbucket. In order to add a new oauth2 provider following input is required:
   • Name - any name is allowed except the names from list of supported providers. It is possible to register more than one client for one given oauth2 provider (for example using different names bitbucket_dev and bitbucket_prod)
   • Client - ID and secret of client
   • Endpoint - auth URL and token URL. This information could be obtained from auth2 provider page
   • InfoURL - oauth2 provider API method to read information of logged in user. This method could be found in documentation of oauth2 provider (e.g. for bitbucket https://developer.atlassian.com/bitbucket/api/2/reference/resource/user)
   • MapUserFn - function to convert the response from InfoURL to token.User (s. example below)
   • Scopes - minimal needed scope to read user information. Client should be authorized to these scopes

   c := auth.Client{
   	Cid:     os.Getenv("AEXMPL_BITBUCKET_CID"),
   	Csecret: os.Getenv("AEXMPL_BITBUCKET_CSEC"),
   }
   
   service.AddCustomProvider("bitbucket", c, provider.CustomHandlerOpt{
   	Endpoint: oauth2.Endpoint{
   		AuthURL:  "https://bitbucket.org/site/oauth2/authorize",
   		TokenURL: "https://bitbucket.org/site/oauth2/access_token",
   	},
   	InfoURL: "https://api.bitbucket.org/2.0/user/",
   	MapUserFn: func(data provider.UserData, _ []byte) token.User {
   		userInfo := token.User{
   			ID: "bitbucket_" + token.HashID(sha1.New(),
   				data.Value("username")),
   			Name: data.Value("nickname"),
   		}
   		return userInfo
   	},
   	Scopes: []string{"account"},
   })
   

2. Adds local oauth2 server user can fully customize. It uses gopkg.in/oauth2.v3 library and example shows how to initialize the server and setup a provider.
   • to start local oauth2 server following options are required:
     • URL - url of oauth2 server with port
     • WithLoginPage - flag to define whether login page should be shown
     • LoginPageHandler - function to handle login request. If not specified default login page will be shown

     sopts := provider.CustomServerOpt{
     	URL:           "http://127.0.0.1:9096",
     	L:             options.Logger,
     	WithLoginPage: true,
     }
     prov := provider.NewCustomServer(srv, sopts)
     
     // Start server
     go prov.Run(context.Background())
     

   • to register handler for local oauth2 following option are required:
     • Name - any name except the names from list of supported providers
     • Client - ID and secret of client
     • HandlerOpt - handler options of custom oauth provider

     service.AddCustomProvider("custom123", auth.Client{Cid: "cid", Csecret: "csecret"}, prov.HandlerOpt)
     

Self-implemented auth handler

Additionally it is possible to implement own auth handler. It may be useful if auth provider does not conform to oauth standard. Self-implemented handler has to implement provider.Provider interface.

// customHandler implements provider.Provider interface
c := customHandler{}

// add customHandler to stack of auth handlers
service.AddCustomHandler(c)

Customization

There are several ways to adjust functionality of the library:

1. SecretReader - interface with a single method Get(aud string) string to return the secret used for JWT signing and verification
2. ClaimsUpdater - interface with Update(claims Claims) Claims method. This is the primary way to alter a token at login time and add any attributes, set ip, email, admin status, roles and so on.
3. Validator - interface with Validate(token string, claims Claims) bool method. This is post-token hook and will be called on each request wrapped with Auth middleware. This will be the place for special logic to reject some tokens or users.
4. UserUpdater - interface with Update(claims token.User) token.User method. This method will be called on each request wrapped with UpdateUser middleware. This will be the place for special logic modify User Info in request context. Example of usage.

All of the interfaces above have corresponding Func adapters - SecretFunc, ClaimsUpdFunc, ValidatorFunc and UserUpdFunc.

Additionally, ErrorHandlerFunc type is available in the middleware package for custom error handling on authentication failures:

options := auth.Opts{
    // ... other options ...
    ErrorHandler: middleware.ErrorHandlerFunc(func(w http.ResponseWriter, r *http.Request, code int, err error) {
        // return JSON error for API routes
        if strings.HasPrefix(r.URL.Path, "/api/") {
            w.Header().Set("Content-Type", "application/json")
            w.WriteHeader(code)
            json.NewEncoder(w).Encode(map[string]string{"error": "authentication required"})
            return
        }
        // redirect to login page for web routes
        http.Redirect(w, r, "/login", http.StatusFound)
    }),
}

By default (when ErrorHandler is nil), the middleware returns "Unauthorized" (401) or "Access denied" (403) text responses.

Implementing black list logic or some other filters

Restricting some users or some tokens is two step process:

• ClaimsUpdater sets an attribute, like blocked (or allowed)
• Validator checks the attribute and returns true/false

This technique used in the example code

The process can be simplified by doing all checks directly in Validator, but depends on particular case such solution can be too expensive because Validator runs on each request as a part of auth middleware. In contrast, ClaimsUpdater called on token creation/refresh only.

Multi-tenant services and support for different audiences

For complex systems a single authenticator may serve multiple distinct subsystems or multiple set of independent users. For example some SaaS offerings may need to provide different authentications for different customers and prevent use of tokens/cookies made by another customer.

Such functionality can be implemented in 3 different ways:

• Different instances of auth.Service each one with different secret. Doing this way will ensure the highest level of isolation and cookies/tokens won't be even parsable across the instances. Practically such architecture can be too complicated and not always possible. – Handling "allowed audience" as a part of ClaimsUpdater and Validator chain. I.e. ClaimsUpdater sets a claim indicating expected audience code/id and Validator making sure it matches. This way a single auth.Service could handle multiple groups of auth tokens and reject some based on the audience.
• Using the standard JWT aud claim. This method conceptually very similar to the previous one, but done by library internally and consumer don't need to define special ClaimsUpdater and Validator logic.

In order to allow aud support the list of allowed audiences should be passed in as opts.Audiences parameter. Non-empty value will trigger internal checks for token generation (will reject token creation for alien aud) as well as Auth middleware.

Allowed redirect hosts

The from query parameter accepted by oauth2/oauth1/apple/verify login flows tells the server where to send the user after a successful auth handshake. The value is signed into the handshake JWT, so it can't be tampered with mid-flow — but a caller can put any URL into the initial login link. Without restriction this becomes a phishing vector: an attacker crafts a login link that bounces the victim through legitimate OAuth and then to an attacker-controlled landing page.

Default behaviour is permissive (Opts.AllowedRedirectHosts is nil): any non-empty from value is honoured. This preserves the behaviour of versions before the redirect validator existed, so a dependency bump never silently breaks an existing deployment. Hardening is opt-in.

To enable host validation, set Opts.AllowedRedirectHosts to anything implementing the token.AllowedHosts interface:

type AllowedHosts interface {
    Get() ([]string, error)
}

The token.AllowedHostsFunc adapter wraps an ordinary function, mirroring the token.AudienceFunc pattern:

opts := auth.Opts{
    URL: "https://app.example.com",
    AllowedRedirectHosts: token.AllowedHostsFunc(func() ([]string, error) {
        return []string{"admin.example.com", "billing.example.com"}, nil
    }),
    // ...
}

Once the policy is on:

• The host of Opts.URL is always permitted implicitly (single-host deployments need no list entries — pass func() ([]string, error) { return nil, nil } to enable the policy with same-host-only semantics).
• Values returned by Get() are appended to that. Subdomain wildcards are not supported — list each host explicitly.
• Hostname comparison is port-insensitive: https://app.example.com and https://app.example.com:443 are treated as the same host.
• Relative paths and unparseable URLs are rejected.
• Rejected redirects are logged at [WARN] level with only the host portion of the URL (paths and query strings are stripped to avoid logging attacker-supplied data).

Dev provider

Working with oauth2 providers can be a pain, especially during development phase. A special, development-only provider dev can make it less painful. This one can be registered directly, i.e. service.AddProvider("dev", "", "") or service.AddDevProvider(host, port) and should be activated like this:

	// runs dev oauth2 server on :8084 by default
	go func() {
		devAuthServer, err := service.DevAuth()
		if err != nil {
			log.Fatal(err)
		}
		devAuthServer.Run()
	}()

It will run fake aouth2 "server" on port :8084 and user could login with any user name. See example for more details.

Warning: this is not the real oauth2 server but just a small fake thing for development and testing only. Don't use dev provider with any production code.

Listen address

The dev OAuth server and the embedded CustomServer helper bind to 127.0.0.1 by default so the dev login UI is not silently exposed to the LAN, Docker network siblings, kubernetes pods on the same node, etc.

Dev provider

The dev provider has a separate Host field for the listen address; the OAuth callback URL is taken from Opts.URL and is independent. To bind to all interfaces (e.g. when the auth process runs inside a container and needs to be reachable from the host) pass Host explicitly:

// dev provider -- listen on all interfaces, callback URL stays whatever you set in Opts.URL
service.AddDevProvider("0.0.0.0", 8084)

CustomServer

CustomServer is the awkward case: CustomServerOpt.URL is used both as the bind source and as the advertised OAuth endpoint (it appears verbatim in AuthURL, TokenURL and InfoURL returned to clients). There is no separate bind setting today, so URL: "http://0.0.0.0:9096" is only appropriate when every consumer of those advertised endpoints is fine with 0.0.0.0 as a hostname -- which is essentially never the case in practice.

Recommended approaches:

• Single host, no proxy -- leave URL: "http://localhost:9096" (or your real hostname). The default loopback bind matches the advertised host and everything works.
• Behind a reverse proxy (typical Docker/kubernetes pattern) -- terminate at the proxy on the public hostname and let the auth process talk to the proxy over a docker network or unix socket. Set URL to the public-facing value the proxy serves and bind the auth process to a network the proxy can reach (e.g. a docker network, or 0.0.0.0 if the proxy is on a different host and the network is otherwise restricted). The advertised URL stays correct because that is what Opts.URL says.
• Direct LAN exposure with a sensible advertised URL -- set URL to a real hostname or LAN IP that resolves on every consumer (e.g. http://oauth.lan.example:9096); the bind extracts the host and listens there. Avoid embedding 0.0.0.0 in URL unless you have already accepted the consequence that clients will see 0.0.0.0 in the advertised metadata.

A future change is likely to add a separate bind option (CustomServerOpt.BindAddr or similar) so the bind and the advertised URL can diverge cleanly; until then, the bind follows URL.

By default, Dev provider doesn't return email claim from /user endpoint, to match behaviour of other providers which only request minimal scopes. However sometimes it is useful to have email included into user info. This can be done by configuring devAuthServer.GetEmailFn function:

    go func() {
		devAuthServer, err := service.DevAuth()
		devOauth2Srv.GetEmailFn = func(username string) string {
			return username + "@example.com"
		}
		if err != nil {
			log.Fatal(err)
		}
		devAuthServer.Run()
	}()

Other ways to authenticate

In addition to the primary method (i.e. JWT cookie with XSRF header) there are two more ways to authenticate:

1. Send JWT header as X-JWT. This shouldn't be used for web application, however can be helpful for service-to-service authentication.
2. Send JWT token as query parameter, i.e. /something?token=<jwt>
3. Basic access authentication, for more details see below Basic authentication.

Basic authentication

In some cases the middleware.Authenticator allow use Basic access authentication, which transmits credentials as user-id/password pairs, encoded using Base64 (RFC7235). When basic authentication used, client doesn't get auth token in response. It's auth type expect credentials in a header Authorization at every client request. It can be helpful, if client side not support cookie/token store (e.g. embedded device or custom apps). This mode disabled by default and will be enabled with options.

The auth package has two options of basic authentication:

• simple basic auth will be enabled if Opts.AdminPasswd defined. This will allow access with basic auth admin:<Opts.AdminPasswd> with user admin. Such method can be used for automation scripts.
• basic auth with custom checker function, which allow adding user data from store to context of request. It will be enabled if Opts.BasicAuthChecker defined. When BasicAuthChecker defined then Opts.AdminPasswd option will be ignore.

options := auth.Opts{
   //...
   AdminPasswd:    "admin_secret_password", // will ignore if BasicAuthChecker defined
   BasicAuthChecker: func(user, passwd string) (bool, token.User, error) {
      if user == "basic_user" && passwd == "123456" {
           return true, token.User{Name: user, Role: "test_r"}, nil
      }
      return false, token.User{}, errors.New("basic auth credentials check failed")
   }
   //...
}

Logging

By default, this library doesn't print anything to stdout/stderr, however user can pass a logger implementing logger.L interface with a single method Logf(format string, args ...interface{}). Functional adapter for this interface included as logger.Func. There are two predefined implementations in the logger package - NoOp (prints nothing, default) and Std wrapping log.Printf from stdlib.

Register oauth2 providers

Authentication handled by external providers. You should setup oauth2 for all (or some) of them to allow users to authenticate. It is not mandatory to have all of them, but at least one should be correctly configured.

Google Auth Provider

1. Create a new project: https://console.developers.google.com/project
2. Choose the new project from the top right project dropdown (only if another project is selected)
3. In the project Dashboard center pane, choose "API Manager"
4. In the left Nav pane, choose "Credentials"
5. In the center pane, choose the "OAuth consent screen" tab.

• Select "External" and click "Create"
• Fill in "App name" and select User support email
• Upload a logo, if you want to
• In the App Domain section:
  • Application home page - your site URL, e.g., https://mysite.com
  • Application privacy policy link - /web/privacy.html of your Remark42 installation, e.g. https://remark42.mysite.com/web/privacy.html (please check that it works)
  • Terms of service - leave empty
• Authorized domains - your site domain, e.g., mysite.com
• Developer contact information - add your email, and then click Save and continue
• On the Scopes tab, just click Save and continue
• On the Test users, add your email, then click Save and continue
• Before going to the next step, set the app to "Production" and send it to verification

6. In the center pane, choose the "Credentials" tab
   • Open the "Create credentials" drop-down
   • Choose "OAuth client ID"
   • Choose "Web application"
   • Application Name is freeform; choose something appropriate, like "Comments on mysite.com"
   • Authorized JavaScript Origins should be your domain, e.g., https://remark42.mysite.com
   • Authorized redirect URIs is the location of OAuth2/callback constructed as domain + /auth/google/callback, e.g., https://remark42.mysite.com/auth/google/callback
   • Click "Create"
7. Take note of the Client ID and Client Secret

instructions for google oauth2 setup borrowed from oauth2_proxy

Microsoft Auth Provider

1. Register a new application using the Azure portal.
2. Under "Supported account types" select "Accounts in any organizational directory (Any Microsoft Entra directory - Multitenant) and personal Microsoft accounts"
3. Under "Authentication/Platform configurations/Web" enter the correct url constructed as domain + /auth/microsoft/callback. i.e. https://example.mysite.com/auth/microsoft/callback
4. In "Overview" take note of the Application (client) ID
5. Choose the new project from the top right project dropdown (only if another project is selected)
6. Select "Certificates & secrets" and click on "+ New Client Secret".

By default, the Microsoft provider uses the common tenant endpoint, which requires an application accepting both work or school accounts and personal Microsoft accounts. That corresponds to signInAudience: AzureADandPersonalMicrosoftAccount, which can be checked and changed under "Manifest" for an application that already exists. An application restricted to a single account type is rejected at that endpoint, for instance with AADSTS50194 when it is not registered as multi-tenant.

For single-tenant Entra ID (Azure AD) applications, or for an application limited to personal Microsoft accounts (consumers), use AddMicrosoftProvider to specify the tenant:

service.AddMicrosoftProvider("<Client ID>", "<Client Secret>", "<Tenant ID>")

The tenant value can be a tenant ID (GUID), domain name, or one of the well-known values: common, organizations, consumers.

GitHub Auth Provider

1. Create a new "OAuth App": https://github.com/settings/developers
2. Fill "Application Name" and "Homepage URL" for your site
3. Under "Authorization callback URL" enter the correct url constructed as domain + /auth/github/callback. ie https://example.mysite.com/auth/github/callback
4. Take note of the Client ID and Client Secret

Username-as-identity caveat

By default the GitHub provider derives the local user id from the account login, as github_<sha1(login)>. GitHub releases a username as soon as the account is renamed or deleted, and anyone can claim it afterwards. An application that keys its own records on the returned id will treat the next holder of a released username as the original user. This is the same property described in the email-as-identity caveat above, with one difference: GitHub returns an immutable numeric account id in the same response, so the provider can key on that instead.

To do so, register the provider with AddGithubProviderWithNumericID:

service.AddGithubProviderWithNumericID("<Client ID>", "<Client Secret>")

To combine it with UserAttributes, set GithubNumericID when building provider.Params directly and register the result with service.AddCustomHandler(provider.NewGithub(p)). That handler is registered as-is, so every field the service would normally supply has to be filled in by hand: URL, JwtService: service.TokenService(), AvatarSaver: service.AvatarProxy(), L, and AllowedRedirectHosts set to the same value passed in Opts. Leaving AllowedRedirectHosts nil turns off redirect host validation for that provider, so a service that sets it in Opts must repeat it here.

The numeric derivation is best-effort: if the /user response carries no usable numeric id, the provider keeps the login-derived id and logs a warning rather than failing the login.

This is off by default because it changes the id of every existing GitHub user. On a running deployment the switch is not transparent: comments, roles, blocks and any other records stored under the old id stop matching, and the old ids cannot be translated offline, because a login cannot be recovered from its hash. Turn it on for a new deployment, or migrate the stored ids yourself first. The recommendation in the email-as-identity caveat applies here too, and avoids the problem entirely: map the provider id to an internal immutable id of your own at first login, and key application records on that.

Facebook Auth Provider

1. From https://developers.facebook.com select "My Apps" / "Add a new App"
2. Set "Display Name" and "Contact email"
3. Choose "Facebook Login" and then "Web"
4. Set "Site URL" to your domain, ex: https://example.mysite.com
5. Under "Facebook login" / "Settings" fill "Valid OAuth redirect URIs" with your callback url constructed as domain + /auth/facebook/callback
6. Select "App Review" and turn public flag on. This step may ask you to provide a link to your privacy policy.

Apple Auth Provider

To configure this provider, a user requires an Apple developer account (without it setting up a sign in with Apple is impossible). Sign in with Apple lets users log in to your app using their two-factor authentication Apple ID.

Follow to next steps for configuring on the Apple side:

1. Log in to the developer account.
2. If you don't have an App ID yet, create one. Later on, you'll need TeamID, which is an "App ID Prefix" value.
3. Enable the "Sign in with Apple" capability for your App ID in the Certificates, Identifiers & Profiles section.
4. Create Service ID and bind with App ID from the previous step. Apple will display the description field value to end-users on sign-in. You'll need that service Identifier as a ClientID later on**.**
5. Configure "Sign in with Apple" for created Service ID. Add domain where you will use that auth on to "Domains and subdomains" and its main page URL (like https://example.com/ to "Return URLs".
6. Register a New Key (private key) for the "Sign in with Apple" feature and download it. Write down the Key ID. This key will be used to create JWT Client Secret.
7. Add your domain name and sender email in the Certificates, Identifiers & Profiles >> More section as a new Email Source.

After completing the previous steps, you can proceed with configuring the Apple auth provider. Here are the parameters for AppleConfig:

• ClientID (required) - Service ID (or App ID) which is used for Sign with Apple
• TeamID (required) - Identifier a developer account (use as prefix for all App ID)
• KeyID (required) - Identifier a generated key for Sign with Apple
• ResponseMode - Response Mode, please see documentation for reference, default is form_post

    // apple config parameters
	appleCfg := provider.AppleConfig{
		TeamID:   os.Getenv("AEXMPL_APPLE_TID"), // developer account identifier
		ClientID: os.Getenv("AEXMPL_APPLE_CID"), // Service ID (or App ID)
		KeyID:    os.Getenv("AEXMPL_APPLE_KEYID"), // private key identifier
	}

Then add an Apple provider that accepts the following parameters:

• appleConfig (provider.AppleConfig) created above
• privateKeyLoader (PrivateKeyLoaderInterface)

PrivateKeyLoaderInterface implements a loader for the private key (which you downloaded above) to create a client_secret. The user can use a pre-defined function provider.LoadApplePrivateKeyFromFile(filePath string) to load the private key from local file.

AddAppleProvide tries to load private key at call and return an error if load failed. Always check error when calling this provider.

    if err := service.AddAppleProvider(appleCfg, provider.LoadApplePrivateKeyFromFile("PATH_TO_PRIVATE_KEY_FILE")); err != nil {
		log.Fatalf("[ERROR] failed create to AppleProvider: %v", err)
	}

Limitation:

• Map a userName (if specific scope defined) is only sent in the upon initial user sign up. Subsequent logins to your app using Sign In with Apple with the same account do not share any user info and will only return a user identifier in IDToken claims. This behaves correctly until a user delete sign in for you service with Apple ID in own Apple account profile (security section). It is recommend that you securely cache the at first login containing the user info for bind it with a user UID at next login.

Token validation:

The provider verifies the Apple id_token signature against Apple's published JWK, then enforces:

• iss == "https://appleid.apple.com" -- per Apple's Sign-in-with-Apple REST API spec
• aud == ClientID (your Service ID or App ID)

A token signed by Apple but issued for a different aud is rejected with 403 invalid id_token. The aud check (not the iss check) is what closes the confused-deputy attack: a sibling service in the same Apple developer team (or any other Sign-in-with-Apple client) holds tokens with the real Apple iss but their own aud, and could replay one of those tokens against this service if aud were not enforced. Provider always get user UID (sub claim) in IDToken.

• Apple doesn't have an API for fetch avatar and user info.

See example before use.

Yandex Auth Provider

1. Create a new "OAuth App": https://oauth.yandex.com/client/new
2. Fill "App name" for your site
3. Under Platforms select "Web services" and enter "Callback URI #1" constructed as domain + /auth/yandex/callback. ie https://example.mysite.com/auth/yandex/callback
4. Select Permissions. You need following permissions only from the "Yandex.Passport API" section:
   • Access to user avatar
   • Access to username, first name and surname, gender
5. Fill out the rest of fields if needed
6. Take note of the ID and Password

For more details refer to Yandex OAuth and Yandex.Passport API documentation.

Battle.net Auth Provider

1. Log into Battle.net as a developer: https://develop.battle.net/nav/login-redirect
2. Click "+ CREATE CLIENT" https://develop.battle.net/access/clients/create
3. For "Client name", enter whatever you want
4. For "Redirect URLs", one of the lines must be "http[s]://your_remark_installation:port//auth/battlenet/callback", e.g. https://localhost:8443/auth/battlenet/callback or https://remark.mysite.com/auth/battlenet/callback
5. For "Service URL", enter the URL to your site or check "I do not have a service URL for this client." checkbox if you don't have any
6. For "Intended use", describe the application you're developing
7. Click "Save".
8. You can see your client ID and client secret at https://develop.battle.net/access/clients by clicking the client you created

For more details refer to Complete Guide of Battle.net OAuth API and Login Button or the official Battle.net OAuth2 guide

Patreon Auth Provider

1. Create a new Patreon client https://www.patreon.com/portal/registration/register-clients
2. Fill "App Name", "Description", "App Category" and "Author" for your site
3. Under "Redirect URIs" enter the correct url constructed as domain + /auth/patreon/callback. ie https://example.mysite.com/auth/patreon/callback
4. Take note of the Client ID and Client Secret

Discord Auth Provider

1. Log into Discord Developer Portal https://discord.com/developers/applications
2. Click on New Application to create the application required for Oauth
3. After filling "NAME", navigate to "OAuth2" option on the left sidebar
4. Under "Redirects" enter the correct url constructed as domain + /auth/discord/callback. ie https://remark42.mysite.com/auth/discord/callback
5. Take note of the CLIENT ID and CLIENT SECRET

Twitter Auth Provider

1. Create a new twitter application https://developer.twitter.com/en/apps
2. Fill App name and Description and URL of your site
3. In the field Callback URLs enter the correct url of your callback handler e.g. https://example.mysite.com/{route}/twitter/callback
4. Under Key and tokens take note of the Consumer API Key and Consumer API Secret key. Those will be used as cid and csecret

XSRF Protections

By default, the XSRF protections will apply to all requests which reach the middlewares.Auth, middlewares.Admin or middlewares.RBAC middlewares. This will require setting a request header with a key of <XSRFHeaderKey> containing the value of the cookie named <XSRFCookieName>.

To disable all XSRF protections, set DisableXSRF to true. This should probably only be used during testing or debugging.

When setting a custom request header is not possible, such as when building a web application which is not a Single-Page-Application and HTML link tags are used to navigate pages, specific HTTP methods may be excluded using the XSRFIgnoreMethods option. For example, to disable GET requests, set this option to XSRFIgnoreMethods: []string{"GET"}. Adding methods other than GET to this list may result in XSRF vulnerabilities.

Browser apps: pair with http.CrossOriginProtection (Go 1.25+)

The JWT XSRF check above only fires when the JWT arrives in a cookie and only after a request reaches the auth middleware. For browser-based applications it is recommended to additionally wrap the router with http.CrossOriginProtection (Go 1.25+), which checks the browser-set Sec-Fetch-Site header (with an Origin vs Host fallback for older clients) and rejects cross-origin state-changing requests at the HTTP layer before they reach any handler:

csrf := http.NewCrossOriginProtection()
_ = csrf.AddTrustedOrigin("https://app.example.com") // for cross-origin SPAs
csrf.AddInsecureBypassPattern("POST /auth/apple/")   // Apple Sign In uses form_post

mux := http.NewServeMux()
mux.Handle("/api/", authenticator.Auth(apiHandler))

log.Fatal(http.ListenAndServe(":8080", csrf.Handler(mux)))

This is the algorithm recommended by OWASP as a primary CSRF defence. Unlike SameSite=Lax, it distinguishes same-origin from same-site, so subdomain attacks are blocked. It composes with the JWT XSRF: the new middleware covers browser flows, the JWT XSRF still covers API clients sending the JWT-derived header.

Status

The library was originally extracted from the remark42 project. The code is in production use on multiple sites and has proven to be stable and reliable.

Version 1.x is stable and in maintenance mode. Version 2.x is now the actively developed branch, and we recommend using it for all new projects.