OAuth2 Login

The oauth2 package implements the Authorization Code flow with PKCE and OIDC support. Four provider presets are built in: Google, GitHub, Facebook, and Zalo. Any other provider is configured as a plain ClientRegistration.

Import

import "github.com/thuongh2/go-security/oauth2"

Quick setup

// 1. Build client registrations from provider presets. Preset() supplies the
// endpoints, default scopes, and subject attribute; you supply the id,
// credentials, redirect URI, scopes (nil -> preset default), and auth method.
// The result is validated — a malformed registration is a construction error.
google, err := oauth2.NewRegistration(
    "google", oauth2.ProviderGoogle,
    os.Getenv("GOOGLE_CLIENT_ID"), os.Getenv("GOOGLE_CLIENT_SECRET"),
    "https://myapp.com/login/oauth2/code/google",
    nil, // nil -> preset default {openid, profile, email}
    oauth2.AuthMethodClientSecretBasic,
)
if err != nil {
    log.Fatal(err)
}

github, err := oauth2.NewRegistration(
    "github", oauth2.ProviderGitHub,
    os.Getenv("GITHUB_CLIENT_ID"), os.Getenv("GITHUB_CLIENT_SECRET"),
    "https://myapp.com/login/oauth2/code/github",
    nil, // nil -> preset default {read:user, user:email}
    oauth2.AuthMethodClientSecretBasic,
)
if err != nil {
    log.Fatal(err)
}

// 2. Put them in a repository.
repo, err := oauth2.NewInMemoryClientRegistrationRepository(google, github)
if err != nil {
    log.Fatal(err)
}

// 3. Configure the login callback. Repo and Store are required; everything
// else (token client, userinfo fetcher, authorities mapper, ID-token
// validator, cookie config) defaults to a secure construction.
loginCfg := oauth2.LoginConfig{
    Repo:  repo,
    Store: sessionStore,
}

// 4. Mount the two routes per registration.
authz := oauth2.NewAuthorizationRequestHandler(repo, sessionStore, session.DefaultCookieConfig())
mux := http.NewServeMux()
for _, reg := range repo.Registrations() {
    mux.Handle("/oauth2/authorization/"+reg.ID, authz.Handle(reg.ID))
    mux.Handle("/login/oauth2/code/"+reg.ID, oauth2.CallbackHandler(loginCfg, reg.ID))
}

The callback handler stores the principal in the session; subsequent requests are authenticated by the securityhttp.SessionAuthentication middleware. The callback route (/login/oauth2/code/*) is intentionally CSRF-exempt: the single-use, session-bound state parameter is the CSRF defense for the authorization-code flow. If you mount web/csrf, exclude that path — securityhttp does not add this exclusion automatically. The nonce check is only enforced when the authorization request set one (non-empty), and state is validated before the code exchange, closing an auth-code-injection window:

Provider presets

oauth2.Preset(t oauth2.ProviderType) returns the fixed endpoints, default scopes, and subject attribute for a known provider; oauth2.NewRegistration uses it internally to build a validated ClientRegistration.

Provider	`ProviderType`	OIDC	Subject attribute	Notes
Google	`ProviderGoogle`	Yes — ID token + JWKS	`sub`	default scopes `openid profile email`
GitHub	`ProviderGitHub`	No — GitHub has no OIDC endpoint	`id` (numeric)	forces `Accept: application/json` on the token request (GitHub returns form-encoded otherwise); resolves a verified primary email from `/user/emails` when the profile hides it
Facebook	`ProviderFacebook`	No	`id`	default scopes `public_profile email`
Zalo	`ProviderZalo`	No	`id`	endpoints and scopes only, no default scopes; confirm Zalo’s current v4 parameter contract before production use

NewRegistration only works for these four known providers — Preset has no entry for ProviderGeneric, so a custom provider is built as a plain ClientRegistration (see below).

Custom provider

Build the ClientRegistration directly. Scopes containing "openid" make it an OIDC registration (IsOIDC() returns true), which Validate() then requires a JWKSetURI and Issuer for:

reg := oauth2.ClientRegistration{
    ID:                "myidp",
    Provider:          oauth2.ProviderGeneric,
    ClientID:          "...",
    ClientSecret:      "...",
    AuthMethod:        oauth2.AuthMethodClientSecretPost,
    AuthorizationURI:  "https://idp.example.com/authorize",
    TokenURI:          "https://idp.example.com/token",
    UserInfoURI:       "https://idp.example.com/userinfo",
    JWKSetURI:         "https://idp.example.com/.well-known/jwks.json",
    Issuer:            "https://idp.example.com",
    RedirectURI:       "https://myapp.com/login/oauth2/code/myidp",
    Scopes:            []string{"openid", "profile", "email"},
    UserNameAttribute: "sub",
}
if err := reg.Validate(); err != nil {
    log.Fatal(err)
}
repo, err := oauth2.NewInMemoryClientRegistrationRepository(reg)

Drop "openid" (and JWKSetURI/Issuer) for a plain OAuth2 provider — the callback then calls UserInfoURI instead of validating an ID token. AllowInsecure: true permits http:// endpoints for localhost dev fixtures. Leave it false (the default) in production; every endpoint is otherwise required to be https://.

PKCE

PKCE (Proof Key for Code Exchange) is always enabled. A code_verifier is generated per authorization request and stored in the session. The code_challenge is sent in the authorization redirect as S256. No configuration is needed — PKCE cannot be disabled.

OIDC

A registration is OIDC when its Scopes include "openid" (ClientRegistration.IsOIDC()). For an OIDC registration the callback validates the ID token instead of calling the userinfo endpoint. ID token validation:

Signature verified against the provider’s JWKS
aud must match ClientID
exp must be present and in the future (required, not just checked if set)
iss must match the registration’s Issuer
nonce must match the value generated for that authorization request (ErrNonceMismatch otherwise)

State parameter

A single-use, session-bound state parameter is generated per authorization request. It is verified on callback and immediately invalidated, preventing CSRF attacks on the OAuth2 flow.

Errors

Failures are sentinel errors, matchable with errors.Is:

Error	Meaning
`ErrUnknownRegistration`	no registration matches the requested id
`ErrStateMismatch`	callback state didn’t match a session-stored in-flight request
`ErrInvalidRedirect`	the post-login redirect target wasn’t a safe relative path
`ErrTokenExchange`	the token endpoint exchange failed
`ErrUserInfo`	the userinfo request failed
`ErrIDToken`	id_token validation failed
`ErrNonceMismatch`	id_token nonce didn’t match the expected session-stored nonce
`ErrProviderError`	the authorization server returned an `error` callback parameter
`ErrInsecureEndpoint`	an endpoint URL wasn’t https (and `AllowInsecure` wasn’t set)
`ErrResponseTooLarge`	an outbound response exceeded the size cap

LoginConfig.OnFailure receives these (default: write a 401). The provider’s error_description is never reflected back to the client.

Granted authorities

By default every successful login is granted OAUTH2_USER plus one SCOPE_<x> authority per granted OAuth2 scope (oauth2.DefaultAuthoritiesMapper()). Supply LoginConfig.AuthoritiesMap to map provider attributes to your own roles:

loginCfg := oauth2.LoginConfig{
    Repo:  repo,
    Store: sessionStore,
    AuthoritiesMap: oauth2.AuthoritiesMapperFunc(func(
        reg oauth2.ClientRegistration, attrs map[string]any, scopes []string,
    ) []core.Authority {
        return core.Roles("USER")
    }),
}

Session principal

After a successful callback, the OAuth2 subject (e.g. "12345678" for Google) is stored as the session principal. On subsequent requests, SessionAuthentication calls UserService.LoadUser(subject). Implement UserService to synthesize a user from the subject if it doesn’t exist in your database, or create a row on first login:

func (s *myService) LoadUser(ctx context.Context, username string) (*authn.User, error) {
    u, err := s.db.FindBySubject(ctx, username)
    if errors.Is(err, sql.ErrNoRows) {
        // First login — create profile
        u = s.db.CreateFromOAuth2(ctx, username)
    }
    return &authn.User{
        Username:    u.Subject,
        Authorities: core.Roles("USER"),
    }, nil
}

AuthorizedClient

After a successful login, the access/refresh token pair is stored server-side, keyed by session and registration id, in an AuthorizedClientRepository — it is never placed on the principal, a cookie, or a log. Load it with the session belonging to the current request:

acRepo := oauth2.NewSessionAuthorizedClientRepository(sessionStore) // same store as LoginConfig.Store

func callGoogleAPI(w http.ResponseWriter, r *http.Request) {
    id, ok := session.ReadSessionCookie(r, cookie)
    if !ok {
        http.Error(w, "no session", http.StatusUnauthorized)
        return
    }
    sess, found, err := sessionStore.Get(r.Context(), id)
    if err != nil || !found {
        http.Error(w, "no session", http.StatusUnauthorized)
        return
    }
    client, ok, err := acRepo.Load(r.Context(), "google", sess)
    if err != nil || !ok {
        http.Error(w, "not authorized with google", http.StatusUnauthorized)
        return
    }

    httpClient := &http.Client{Timeout: 10 * time.Second}
    req, _ := http.NewRequestWithContext(r.Context(), http.MethodGet,
        "https://www.googleapis.com/oauth2/v3/userinfo", nil)
    req.Header.Set("Authorization", "Bearer "+client.AccessToken)
    resp, err := httpClient.Do(req)
    // ...
}

client.AccessExpired(time.Now()) reports whether the access token has expired (a zero expiry, i.e. unknown lifetime, is treated as not expired).

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Quick setup

Provider presets

Custom provider

PKCE

OIDC

State parameter

Errors

Granted authorities

Session principal

AuthorizedClient

​Import

​Quick setup

​Provider presets

​Custom provider

​PKCE

​OIDC

​State parameter

​Errors

​Granted authorities

​Session principal

​AuthorizedClient

Import

Quick setup

Provider presets

Custom provider

PKCE

OIDC

State parameter

Errors

Granted authorities

Session principal

AuthorizedClient