Documentation
¶
Overview ¶
Package webauthn wraps go-webauthn/webauthn to provide WebAuthn/FIDO2 passkey ceremony helpers. It imports the core auth package for types but never the reverse.
Index ¶
- Constants
- Variables
- func BeginConditionalLogin(wa *gowebauthn.WebAuthn) (*protocol.CredentialAssertion, *gowebauthn.SessionData, error)
- func BeginLogin(wa *gowebauthn.WebAuthn) (*protocol.CredentialAssertion, *gowebauthn.SessionData, error)
- func BeginRegistration(wa *gowebauthn.WebAuthn, user *User) (*protocol.CredentialCreation, *gowebauthn.SessionData, error)
- func CompleteLogin(ctx context.Context, wa *gowebauthn.WebAuthn, store Store, ...) (*auth.User, *gowebauthn.Credential, error)
- func CredentialFromAPI(c *auth.PasskeyCredential) gowebauthn.Credential
- func CredentialToAPI(c *gowebauthn.Credential, userID int64, name string) *auth.PasskeyCredential
- func FinishLogin(wa *gowebauthn.WebAuthn, sessionData *gowebauthn.SessionData, ...) (gowebauthn.User, *gowebauthn.Credential, error)
- func FinishRegistration(wa *gowebauthn.WebAuthn, user *User, sessionData *gowebauthn.SessionData, ...) (*gowebauthn.Credential, error)
- func New(rp RPConfig) (*gowebauthn.WebAuthn, error)
- func PasskeyFriendlyName(aaguid []byte, existingNames []string) string
- type AAGUIDEntry
- type RPConfig
- type Store
- type User
Constants ¶
const CeremonyTimeout = 5 * time.Minute
CeremonyTimeout is the maximum duration a user has to complete an auth ceremony.
Variables ¶
var ErrNotDiscoverable = errors.New("auth/webauthn: authenticator did not create a discoverable credential")
ErrNotDiscoverable reports a registration whose client stated the new credential is not client-side discoverable. Matchable with errors.Is so a caller can tell it apart from a verification failure and tell the user their authenticator cannot store a passkey.
var KnownAAGUIDs = []AAGUIDEntry{
{"ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4", "Google Password Manager"},
{aaguidChromeOnMac, credNameChromeOnMac},
{"08987058-cadc-4b81-b6e1-30de50dcbe96", credNameWindowsHello},
{"9ddd1817-af5a-4672-a2b9-3e3dd95000a9", credNameWindowsHello},
{"6028b017-b1d4-4c02-b4b3-afcdafc96bb2", credNameWindowsHello},
{"dd4ec289-e01d-41c9-bb89-70fa845d4bf2", "iCloud Keychain"},
{"fbfc3007-154e-4ecc-8c0b-6e020557d7bd", "iCloud Keychain"},
{"d548826e-79b4-db40-a3d8-11116f7e8349", "Bitwarden"},
{"b5397723-31d4-4c13-b037-37be46e30e9e", "1Password"},
{"bada5566-a7aa-401f-bd96-45619a55120d", "1Password"},
{"2fc0579f-8113-47ea-b116-bb5a8db9202a", "YubiKey 5"},
{"fa2b99dc-9e39-4257-8f92-4a30d23c4118", "YubiKey 5 NFC"},
}
KnownAAGUIDs is the registry of known authenticator AAGUIDs.
Functions ¶
func BeginConditionalLogin ¶
func BeginConditionalLogin(wa *gowebauthn.WebAuthn) (*protocol.CredentialAssertion, *gowebauthn.SessionData, error)
BeginConditionalLogin starts a WebAuthn assertion ceremony with conditional mediation, enabling browser autofill UI for passkeys.
func BeginLogin ¶
func BeginLogin(wa *gowebauthn.WebAuthn) (*protocol.CredentialAssertion, *gowebauthn.SessionData, error)
BeginLogin starts a WebAuthn assertion ceremony (discoverable login).
func BeginRegistration ¶
func BeginRegistration(wa *gowebauthn.WebAuthn, user *User) (*protocol.CredentialCreation, *gowebauthn.SessionData, error)
BeginRegistration starts a WebAuthn registration ceremony.
The credential parameters offer the three ML-DSA parameter sets ahead of EdDSA, ES256 and RS256, so an authenticator that implements a post-quantum algorithm produces a post-quantum credential and every authenticator in current use still registers on a classical one. Verifying an ML-DSA signature needs Go 1.27, which this module already requires.
func CompleteLogin ¶
func CompleteLogin(ctx context.Context, wa *gowebauthn.WebAuthn, store Store, sessionData *gowebauthn.SessionData, r *http.Request) (*auth.User, *gowebauthn.Credential, error)
CompleteLogin completes a discoverable (passkey) login ceremony against the store: it resolves the asserting user and registered credentials from the assertion's user handle, verifies the assertion response, and persists the post-login credential custody (sign count and authenticator flags, the cloned-authenticator detection state). It composes FinishLogin with a store-backed user finder; a consumer needing a custom finder or custody policy uses FinishLogin directly.
The custody write is best-effort: a store failure is logged at Warn and does not fail the login (sign-count bookkeeping is clone *detection*, not part of assertion verification). The returned user is the account as stored — the caller owns account-status policy and MUST check User.Enabled (and any app-specific state) before creating a session. A ceremony failure caused by a credential deleted server-side surfaces as a wrapped protocol.ErrorUnknownCredential, matchable with errors.As so callers can signal the client to forget the stale passkey.
func CredentialFromAPI ¶
func CredentialFromAPI(c *auth.PasskeyCredential) gowebauthn.Credential
CredentialFromAPI converts a PasskeyCredential to a gowebauthn.Credential (the inverse of CredentialToAPI).
func CredentialToAPI ¶
func CredentialToAPI(c *gowebauthn.Credential, userID int64, name string) *auth.PasskeyCredential
CredentialToAPI converts a gowebauthn.Credential to a PasskeyCredential.
func FinishLogin ¶
func FinishLogin(wa *gowebauthn.WebAuthn, sessionData *gowebauthn.SessionData, response *http.Request, userFinder func(rawID, userHandle []byte) (gowebauthn.User, error)) (gowebauthn.User, *gowebauthn.Credential, error)
FinishLogin completes a WebAuthn assertion ceremony (discoverable login).
func FinishRegistration ¶
func FinishRegistration(wa *gowebauthn.WebAuthn, user *User, sessionData *gowebauthn.SessionData, response *http.Request) (*gowebauthn.Credential, error)
FinishRegistration completes a WebAuthn registration ceremony.
A credential the client reports as non-discoverable is rejected with ErrNotDiscoverable instead of being returned for storage. BeginLogin and BeginConditionalLogin are discoverable ceremonies, so such a credential can never complete a login: storing it gives the user a passkey in their list that fails every time they select it. The check reads the typed credProps output BeginRegistration requests, and an authenticator that reports nothing is accepted, because absence is not a denial.
func New ¶
func New(rp RPConfig) (*gowebauthn.WebAuthn, error)
New creates a configured gowebauthn.WebAuthn instance for the given relying party. An RPConfig with an empty ID is rejected here with an error naming the field: upstream go-webauthn constructs successfully without an RP ID and then fails every ceremony with an RP-hash mismatch, which defeats this wrapper's purpose of making the relying party legible at construction.
func PasskeyFriendlyName ¶
PasskeyFriendlyName returns a display-only, human-friendly label for a newly registered passkey, chosen so it does not duplicate any entry in existingNames (the user's current passkey labels). A known authenticator (matched by AAGUID) gets its bare registry name for the first of its kind (e.g. "Chrome on Mac") and a numbered name for each subsequent one ("Chrome on Mac 2", ...); an unknown authenticator is always numbered ("Passkey 1", "Passkey 2", ...). The numeric suffix is one past the highest already in use, so deleting a passkey that leaves a numbering gap never yields a duplicate label.
Types ¶
type AAGUIDEntry ¶
AAGUIDEntry maps an authenticator AAGUID to a friendly name.
type RPConfig ¶
type RPConfig struct {
// ID is the relying party identifier, an effective domain
// (e.g. "example.com").
ID string
// DisplayName is the human-readable relying party name shown by
// authenticators.
DisplayName string
// Origins are the allowed browser origins for ceremonies
// (e.g. "https://example.com").
Origins []string
}
RPConfig identifies the relying party that a New-constructed gowebauthn.WebAuthn serves. The ID and display name would otherwise sit as adjacent same-typed string parameters, where a silent swap ships a broken RP ID; the field names make each value's role explicit at the call site.
type Store ¶
type Store interface {
PasskeysByUserID(ctx context.Context, userID int64) ([]auth.PasskeyCredential, error)
UpdatePasskeyAfterLogin(ctx context.Context, credID []byte, signCount uint32, flags auth.PasskeyFlags) error
UserByID(ctx context.Context, id int64) (user *auth.User, found bool, err error)
}
Store is the narrow store interface consumed by CompleteLogin: user and credential lookup to resolve the asserting account from its user handle, and the post-login credential-custody write. A storage layer implementing auth.UserStore and auth.PasskeyStore satisfies it. Consumers composing the lower-level ceremony helpers (BeginLogin, FinishLogin) with their own user finder do not need it.
type User ¶
type User struct {
AuthUser *auth.User
Credentials []auth.PasskeyCredential
}
User adapts auth.User + credentials to the gowebauthn.User interface.
func (*User) WebAuthnCredentials ¶
func (u *User) WebAuthnCredentials() []gowebauthn.Credential
WebAuthnCredentials converts the stored credentials to gowebauthn.Credential.
func (*User) WebAuthnDisplayName ¶
WebAuthnDisplayName returns the display name, falling back to username.
func (*User) WebAuthnID ¶
WebAuthnID encodes the user ID as a binary varint.