Authentication Providers

The authn package provides the Manager that fans out to a list of Provider implementations, plus every credential-specific provider: password, bearer token, API key, HMAC-signed requests, OAuth2 login, TOTP, magic link, passkey, and multi-factor orchestration.

Import

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

Manager

manager := authn.NewManager([]authn.Provider{
    authn.NewPasswordProvider(users, encoder),
    authn.NewBearerTokenProvider(tokenAuth),
    authn.NewAPIKeyProvider(apiKeyService),
}, authn.WithPublisher(publisher))

Manager.Authenticate(ctx, token) iterates providers in order, calls the first one where Supports(token) returns true, and returns the authenticated token or an error wrapping core.ErrProviderNotFound.

Manager options

Option	Description
`authn.WithPublisher(p)`	Attach an `event.Publisher` for success/failure hooks. Unset defaults to `event.NopPublisher` (discards events).

User

User is the UserDetails equivalent — the result of UserService.LoadUser.

type User struct {
    Username           string
    PasswordHash       string
    Authorities        []core.Authority
    Disabled           bool
    Locked             bool
    AccountExpired     bool
    CredentialsExpired bool
}

Three status checks are available:

user.CheckPreAuth() — disabled, then expired-account, then locked. Run before a password/credential is examined.
user.CheckPostAuth() — expired-credentials. Run only after a correct credential.
user.Check() — the combination of both, for callers that just want a single status gate (used by APIKeyProvider, HMACProvider, and MagicLinkProvider).

PasswordProvider calls CheckPreAuth/CheckPostAuth directly rather than Check(), so status is enforced on the correct side of the password comparison (pre-auth checks gate access regardless of the password; the credentials-expired check only fires once the password has matched).

UserService

type UserService interface {
    LoadUser(ctx context.Context, username string) (*User, error)
}

Return authn.ErrUserNotFound when the username is not in your store. PasswordProvider performs a dummy hash comparison on ErrUserNotFound (using the same KDF as a real match) to prevent username-enumeration timing attacks.

InMemoryUserService

Useful for tests and playgrounds. It takes no constructor arguments; users are added afterwards with Add, which takes a User value (not a pointer):

hash, _ := encoder.Encode("s3cret")

users := authn.NewInMemoryUserService()
users.Add(authn.User{
    Username:     "alice",
    PasswordHash: hash,
    Authorities:  core.Roles("USER"),
})

Providers

PasswordProvider

Username + password authentication with KDF verification.

authn.NewPasswordProvider(users, encoder)

Pre-auth checks: Disabled, AccountExpired, Locked
Post-auth check: CredentialsExpired
Timing equalization: performs a dummy password comparison (with the configured encoder) when the user is not found, so response time does not reveal whether a username exists

BearerTokenProvider

Validates a raw bearer token by delegating to a TokenAuthenticator:

type TokenAuthenticator interface {
    Authenticate(ctx context.Context, token string) (core.Authentication, error)
}

authn.NewBearerTokenProvider(tokenAuth)

*resource.BearerTokenAuthenticator (JWT) and *resource.IntrospectionAuthenticator (opaque tokens) both satisfy TokenAuthenticator — see resource-server. authn.NewBearerAuthenticationToken(token) builds the request token manually if you want to route a raw bearer token through Manager.Authenticate yourself instead of using a resource-server middleware.

APIKeyProvider

Authenticates a raw API key against an APIKeyService:

type APIKeyService interface {
    LoadByAPIKey(ctx context.Context, key string) (*User, error)
}

authn.NewAPIKeyProvider(apiKeyService)

The provider itself has no header-extraction option; wrap it in web/middleware.APIKeyAuth to read the key off a request:

mw.APIKeyAuth(manager, mw.DefaultAPIKeyExtractor) // X-API-Key header, then ?api_key=

authn.NewAPIKeyToken(key) builds the request token manually if you are not using the middleware.

HMACProvider

Validates HMAC-signed requests (timestamp + method + path + body hash) against a key store:

type HMACSignatureConfig struct {
    Keys            SigningKeyStore // required
    TimestampWindow time.Duration   // default 5 minutes
    UserService     UserService     // optional: resolve authorities by keyID
}

authn.NewHMACProvider(authn.HMACSignatureConfig{
    Keys: signingKeyStore,
})

SigningKeyStore resolves a shared secret by key ID; NewInMemorySigningKeyStore()

Add(keyID, secret) covers tests and small deployments. To authenticate real requests, mount web/middleware.HMACSignatureAuth(manager), which parses the Authorization: HMAC keyId=...,ts=...,nonce=...,sig=... header, hashes the body, and builds the token via authn.CanonicalHMACRequest + authn.NewHMACSignatureToken for you.

OAuth2LoginProvider

Adapts a completed OAuth2/OIDC exchange to authn.Provider so it can run through the same Manager as other credential types:

type OAuth2Completer interface {
    Complete(ctx context.Context, registrationID string) (core.Authentication, error)
}

authn.NewOAuth2LoginProvider(completer)

You supply the OAuth2Completer. authn.NewOAuth2LoginToken(registrationID) builds the request token. Note that the built-in oauth2 package’s own login callback (see oauth2) creates its session directly and does not route through this provider — use OAuth2LoginProvider only if you want OAuth2 completion to flow through a shared authn.Manager alongside other providers.

TOTPProvider

Validates time-based one-time passwords (RFC 6238) as a second factor:

type TOTPService interface {
    GetTOTPSecret(ctx context.Context, username string) (*TOTPSecret, error)
}

totpProvider := authn.NewTOTPProvider(totpService,
    authn.TOTPWithWindow(1),          // default: 1 step either side, tolerates clock drift
    authn.TOTPWithUserService(users), // optional: attach Authorities to the result
    authn.TOTPWithClock(time.Now),    // optional: inject a clock, useful in tests
)

Enrollment helpers (no HTTP wrapper — call these directly):

secret, _ := authn.GenerateTOTPSecret() // 20 random bytes, base32
enrollURL := authn.TOTPEnrollmentURL("MyApp", "alice", secret, 6, 30) // otpauth:// URI for a QR code

Authenticate with authn.NewOTPToken(username, code) against the Manager (or the TOTPProvider directly).

MagicLinkProvider

Validates single-use, expiring tokens for passwordless email/SMS login:

type MagicLinkStore interface {
    Create(ctx context.Context, identifier string, ttl time.Duration) (token string, err error)
    Validate(ctx context.Context, token string) (identifier string, err error)
    Consume(ctx context.Context, token string) error
}

type MagicLinkSender interface {
    Send(ctx context.Context, identifier, magicLinkURL string) error
}

store := authn.NewMemoryMagicLinkStore() // in-memory MagicLinkStore

magicLinkProvider := authn.NewMagicLinkProvider(store,
    authn.MagicLinkWithUserService(users), // optional: load full User + check status
)

MemoryMagicLinkStore implements Create/Validate/Consume with a 32-byte random base64url token and no background goroutine — call DeleteExpired() yourself for GC. authn.NewMagicLinkToken(token) builds the request token; see login for the HTTP request/verify handlers built on top of this provider.

PasskeyProvider

Validates WebAuthn assertions (sign-in only — registration is a separate ceremony, not an authentication act) by delegating to a PasskeyAuthenticator you implement, typically wrapping github.com/go-webauthn/webauthn:

type PasskeyAuthenticator interface {
    BeginAssertion(ctx context.Context, userHandle []byte) (optionsJSON []byte, err error)
    FinishAssertion(ctx context.Context, assertionResponse []byte) (core.Authentication, error)
    BeginRegistration(ctx context.Context, userHandle []byte, userName string) (optionsJSON []byte, err error)
    FinishRegistration(ctx context.Context, userHandle []byte, registrationResponse []byte) (*PasskeyCredential, error)
}

authn.NewPasskeyProvider(webAuthnAuthenticator)

PasskeyCredential is the persisted representation of a registered credential your PasskeyAuthenticator implementation reads and writes:

type PasskeyCredential struct {
    ID         []byte
    PublicKey  []byte
    UserHandle []byte
    UserName   string
    SignCount  uint32
    AAGUID     []byte
    Transports []string
    CreatedAt  time.Time
}

Two supporting interfaces are exported for your PasskeyAuthenticator implementation to use for storage — this package defines no concrete implementation, keeping it stdlib-only:

type PasskeyRepository interface {
    GetCredential(ctx context.Context, credentialID []byte) (*PasskeyCredential, error)
    UpdateSignCount(ctx context.Context, credentialID []byte, signCount uint32) error
    GetUserCredentials(ctx context.Context, userHandle []byte) ([]*PasskeyCredential, error)
    SaveCredential(ctx context.Context, cred *PasskeyCredential) error
    DeleteCredential(ctx context.Context, credentialID []byte) error
}

type PasskeyChallengeStore interface {
    IssueChallenge(ctx context.Context, sessionKey string) (challenge []byte, err error)
    VerifyChallenge(ctx context.Context, sessionKey string, challenge []byte) (bool, error)
    ConsumeChallenge(ctx context.Context, sessionKey string) error
}

authn.NewPasskeyToken(credID, authData, clientDataJSON, sig, userHandle) builds the assertion request token; web/auth provides the HTTP handlers (see login).

MFAManager

Orchestrates a two-step (primary + second-factor) login. It is a standalone orchestrator, not a Provider — it sits above the Manager, taking an already-authenticated primary result and gating it on one or more MFAFactors.

type MFAManagerConfig struct {
    Store    MFAStore          // required
    Factors  map[string]MFAFactor // required
    Policy   MFAPolicy         // required
    StateTTL time.Duration     // default 10 minutes
}

mfaManager := authn.NewMFAManager(authn.MFAManagerConfig{
    Store:   authn.NewMemoryMFAStore(),
    Factors: map[string]authn.MFAFactor{"totp": totpFactor},
    Policy:  authn.NewFixedMFAPolicy("totp"),
})

MFAFactor is the interface you implement per second-factor type; it can delegate straight to TOTPProvider:

type MFAFactor interface {
    FactorID() string
    Supports(auth core.Authentication) bool
    Authenticate(ctx context.Context, primaryAuth core.Authentication, token *authn.MFASecondFactorToken) (core.Authentication, error)
}

type totpFactor struct{ provider *authn.TOTPProvider }

func (f *totpFactor) FactorID() string { return "totp" }
func (f *totpFactor) Supports(_ core.Authentication) bool { return true }
func (f *totpFactor) Authenticate(ctx context.Context, primary core.Authentication, tok *authn.MFASecondFactorToken) (core.Authentication, error) {
    return f.provider.Authenticate(ctx, authn.NewOTPToken(primary.Name(), tok.Credential))
}

MFAPolicy.RequiredFactors decides which factor IDs a given principal must complete; FixedMFAPolicy (via NewFixedMFAPolicy(ids...)) applies the same list to everyone. Flow:

partial, err := mfaManager.BeginMFA(ctx, sessionID, primaryAuth) // after primary auth succeeds
if err != nil {
    // policy misconfigured — no required factors
}
sessionID = partial.SessionID // persist alongside the session

// ... client submits its second-factor code ...

result, err := mfaManager.CompleteMFA(ctx, authn.NewMFASecondFactorToken(sessionID, "totp", code))
if err != nil {
    // bad code, unknown session, or unknown factor type
} else if result.Authenticated() {
    // fully authenticated
}

pending, err := mfaManager.IsPendingMFA(ctx, sessionID)
if err == nil && pending {
    // still waiting on a second factor
}

CompleteMFA returns a *PartialMFAToken (not yet Authenticated()) when more factors remain, or the final authenticated token once all required factors are satisfied. MemoryMFAStore is the in-process MFAStore implementation with TTL expiry. See login for the HTTP handlers built on top of MFAManager.

Error sentinels

Error	Meaning
`authn.ErrUserNotFound`	`UserService.LoadUser` returned no row
`authn.ErrTOTPSecretNotFound`	`TOTPService.GetTOTPSecret` returned no row
`authn.ErrMagicLinkNotFound` / `ErrMagicLinkExpired` / `ErrMagicLinkUsed`	Magic-link token invalid, expired, or already consumed
`authn.ErrMFASessionNotFound` / `ErrMFASessionExpired`	No pending MFA state for the given session
`authn.ErrPasskeyChallengeMismatch`	WebAuthn challenge did not match the session
`authn.ErrCredentialNotFound`	`PasskeyRepository` has no credential for the given ID

Other errors (wrong password, account locked) are core.* sentinels.

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Authentication Providers

Import

Manager

Manager options

User

UserService

InMemoryUserService

Providers

PasswordProvider

BearerTokenProvider

APIKeyProvider

HMACProvider

OAuth2LoginProvider

TOTPProvider

MagicLinkProvider

PasskeyProvider

MFAManager

Error sentinels

​Import

​Manager

​Manager options

​User

​UserService

​InMemoryUserService

​Providers

​PasswordProvider

​BearerTokenProvider

​APIKeyProvider

​HMACProvider

​OAuth2LoginProvider

​TOTPProvider

​MagicLinkProvider

​PasskeyProvider

​MFAManager

​Error sentinels

Import

Manager

Manager options

User

UserService

InMemoryUserService

Providers

PasswordProvider

BearerTokenProvider

APIKeyProvider

HMACProvider

OAuth2LoginProvider

TOTPProvider

MagicLinkProvider

PasskeyProvider

MFAManager

Error sentinels