OAuth2 / social login#

Zero-config OAuth2 / OpenID Connect login under middlewares/oauth2. Four providers work out of the box — Google, GitHub, Microsoft, Discord — with PKCE, CSRF-protected state, signed HttpOnly cookies (or JWT sessions), and transparent token refresh. Only ClientID and ClientSecret are required.

package main

import (
	"github.com/nelthaarion/breeze/v2"
	"github.com/nelthaarion/breeze/v2/middlewares/oauth2"
)

func main() {
	app := breeze.New()

	cfg := oauth2.Config{
		Provider:     oauth2.Google,
		ClientID:     "your-client-id",
		ClientSecret: "your-client-secret",
		BaseURL:      "https://app.example.com",
		CookieSecret: "a-long-random-secret",
	}

	app.Router.Handle(breeze.GET, "/auth/google", oauth2.Login(cfg))
	app.Router.Handle(breeze.GET, "/auth/google/callback", oauth2.Callback(cfg))
	app.Router.Handle(breeze.GET, "/auth/logout", oauth2.Logout(cfg))
	app.Router.Handle(breeze.GET, "/dashboard", dashboard, oauth2.Auth(cfg))

	app.Listen(":3000")
}

func dashboard(ctx *breeze.Context) error {
	user := oauth2.CurrentUser(ctx) // *oauth2.User
	return ctx.JSON(user)
}

Middlewares#

Refresh layers before Auth on protected routes that need fresh access tokens:

app.Router.Handle(breeze.GET, "/dashboard", dashboard,
	oauth2.Refresh(cfg),
	oauth2.Auth(cfg),
)

Reading the user#

From any handler that ran after Auth, Optional, or Callback:

user := oauth2.CurrentUser(ctx)   // *User or nil
tok  := oauth2.CurrentToken(ctx)  // *Token or nil
if oauth2.IsAuthenticated(ctx) {
	// ...
}

UserFrom / TokenFrom are short aliases. The normalized User is provider-independent:

type User struct {
	ID       string   // stable provider id (Google sub, GitHub numeric id, ...)
	Email    string
	Name     string
	Username string
	Avatar   string   // URL
	Provider Provider
}

Sessions#

Two modes, selected by Config.SessionMode:

• SessionModeCookie (default) — user + token serialized into a signed, HttpOnly cookie. Tamper-proof (HMAC), stateless server-side.
• SessionModeJWT — an HS256 JWT carrying the claims, stored in the cookie. The algorithm is pinned to prevent alg=none / confusion attacks.

Every write rotates the session (a new JWT jti or a freshly signed blob), so a pre-login cookie cannot be reused post-login.

Security#

• PKCE (S256) on by default for every provider.
• CSRF — state lives in a signed, short-lived, single-use cookie, compared in constant time; the flow cookie is cleared on callback.
• Open-redirect guard — ?redirect= overrides accept same-site paths only.
• HttpOnly + Secure + SameSite=Lax cookies. Secure auto-enables for https:// BaseURLs and can be forced.
• Bounded provider calls — every outbound token/userinfo request runs under a timeout so a slow provider cannot pin a worker.

Configuration#

Diagnostics#

The oauth2 probe reports through GET /dashboard/api/diagnostics?subsystem=oauth2. See Diagnostics.