webauthn

package
v4.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 27, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

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

View Source
const CeremonyTimeout = 5 * time.Minute

CeremonyTimeout is the maximum duration a user has to complete an auth ceremony.

Variables

View Source
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.

View Source
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

BeginConditionalLogin starts a WebAuthn assertion ceremony with conditional mediation, enabling browser autofill UI for passkeys.

func BeginLogin

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

func PasskeyFriendlyName(aaguid []byte, existingNames []string) string

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

type AAGUIDEntry struct {
	UUID string
	Name string
}

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 NewUser

func NewUser(user *auth.User, creds []auth.PasskeyCredential) (*User, error)

NewUser returns a User with the given user and credentials.

func (*User) WebAuthnCredentials

func (u *User) WebAuthnCredentials() []gowebauthn.Credential

WebAuthnCredentials converts the stored credentials to gowebauthn.Credential.

func (*User) WebAuthnDisplayName

func (u *User) WebAuthnDisplayName() string

WebAuthnDisplayName returns the display name, falling back to username.

func (*User) WebAuthnID

func (u *User) WebAuthnID() []byte

WebAuthnID encodes the user ID as a binary varint.

func (*User) WebAuthnName

func (u *User) WebAuthnName() string

WebAuthnName returns the username.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL