DOCSEARCHbyAlgolia
Submit Docs

go-webauthn/webauthn

repository·master·Indexed 23 days ago

https://github.com/go-webauthn/webauthn

A Go library for implementing Web Authentication (WebAuthn) to support multi-factor authentication, passwordless, or usernameless login flows. It provides tools for implementing the webauthn.User interface, managing webauthn.Credential storage, verifying credentials via metadata.Provider, and handling client data verification through CollectedClientData. The library supports various attestation formats (such as packed, tpm, and apple) and standardized extensions including appid, credProps, and largeBlob.

Tokens
2.2K
Snippets
1
Records
14
Agent score
30%

What's inside go-webauthn/webauthn

  1. Implement the webauthn.User interface

    master
    To use the library, your application's user model must implement the webauthn.User interface. This interface defines the methods required for the library to interact with your user data. Additionally, your storage layer must be able to store and retrieve the webauthn.Credential struct, which can be encoded (e.g., to JSON) for persistence.

  2. Handle Credential Flags using ProtocolValue

    master

    Because WebAuthn specification requirements for flags evolve, the library provides both individual flag fields and a raw ProtocolValue.

    Best Practice: To ensure resistance to breaking changes in the specification, you should store the raw ProtocolValue instead of individual flags. Use the individual flags only for compliance-related decisions in your application logic.

    • To retrieve the raw value: Use func (CredentialFlags) ProtocolValue.
    • To restore flags from a raw value: Use webauthn.NewCredentialFlags.

  3. Install the WebAuthn library

    master

    To add the WebAuthn library to your Go application, run the following command:

    go get github.com/go-webauthn/webauthn

    Note that this library is intended to be used with Go Toolchains as indicated by the toolchain directive in the go.mod file. The library officially supports the latest minor version of Go and provides best-effort support for versions currently supported by Go maintainers (typically the last 3 minor versions).

  4. Verify credentials using metadata.Provider

    master

    You can verify a webauthn.Credential against a metadata.Provider to ensure its validity. This can be performed during registration, during every login, or as part of a periodic audit schedule.

    To leverage this:

    1. Ensure the webauthn.Credential struct has exactly the same values when restored as it did during registration.
    2. Use the Credential Verify function.
    3. Alternatively, you can include a provider in your webauthn.Config to have all registrations processed automatically.

  5. Configure TopOriginVerificationMode for cross-origin validation

    master

    When validating WebAuthn requests from cross-origin iframes, you must specify a TopOriginVerificationMode to determine how the TopOrigin field in CollectedClientData is checked against your allowed origins.

    • TopOriginExplicitVerificationMode: Strictest. Only accepts the TopOrigin if it matches an entry in the allowed Top Origins list (rpTopOrigins). The standard rpOrigins list is ignored.
    • TopOriginImplicitVerificationMode: Accepts the TopOrigin only if it matches an entry in the allowed Origins list (rpOrigins). The rpTopOrigins list is ignored.
    • TopOriginAutoVerificationMode: Most permissive. Accepts the TopOrigin if it matches an entry in either the allowed Top Origins list OR the allowed Origins list (the union of both lists).
    • TopOriginDefaultVerificationMode: The zero value. This is not a valid mode for Verify and will return an error. High-level callers using webauthn.Config typically coerce this to TopOriginExplicitVerificationMode automatically.

  6. Understand the webauthn.Credential struct and storage

    master

    The webauthn.Credential struct represents the WebAuthn Level 3 Credential Record. It is critical that implementers carefully read the struct documentation to ensure all required and optional elements are correctly stored and restored. If values are not restored correctly, the credential may fail validation.

    Mapping Specification Fields to Library Fields

    Specification FieldLibrary FieldJSON FieldNotes
    typeN/AN/AAlways public-key
    idIDid
    publicKeyPublicKeypublicKey
    attestationFormatAttestationFormatattestationFormat
    N/AAttestationTypeattestationTypee.g., basic_full, basic_surrogate
    signCountAuthenticator.SignCountauthenticator.signCount
    transportsTransporttransport
    uvInitializedFlags.UserVerifiedflags.userVerified
    backupEligibleFlags.BackupEligibleflags.backupEligible
    backupStateFlags.BackupStateflags.backupState
    N/AAttestationattestationComposite object for validation
    attestationObjectAttestation.Objectattestation.object
    attestationClientDataJSONAttestation.ClientDataJSONattestation.clientDataJSON

  7. Deprecated and Removed WebAuthn Extensions

    master

    The following extensions have been deprecated or removed from the WebAuthn specification. While they may be technically present in the extensions map, this library does not provide official support for them. They are likely not supported by modern browsers or authenticators:

    • txAuthGeneric: Generic Transaction Authorization
    • authnSel: Authenticator Selection
    • exts: Supported Extensions
    • uvi: User Verification Index
    • loc: Location
    • uvm: User Verification Method
    • biometricPerfBounds: Biometric Authenticator Performance Bounds

  8. Supported WebAuthn Extensions

    master

    The library provides support for several standardized and specification-listed extensions. Note that some extensions require manual handling for registration or authentication.

    Standardized Extensions

    • appid: FIDO AppID Extension (Supported during Authentication)
    • appidExclude: FIDO AppID Exclusion Extension (Supported during Registration)
    • credProps: Credential Properties Extension (Supported during Registration)
    • largeBlob: Large Blob Storage Extension (Supported during Registration and Authentication)

    CTAP2 Extensions (Largely unsupported/Manual)

    These extensions are technically supported via the extensions map but may require manual implementation logic:

    • credProtect: Credential Protection
    • credBlob: Credential Blob
    • largeBlobKey: Large Blob Key
    • minPinLength: Minimum PIN Length
    • pinComplexityPolicy: PIN Complexity
    • hmac-secret: HMAC Secret
    • hmac-secret-mc: HMAC Secret MakeCredential
    • thirdPartyPayment: Third-Party Payment Authentication

  9. Supported Attestation Formats

    master

    The library supports the following WebAuthn attestation statement formats. Use these identifiers when handling attestation data during the registration process:

    • packed: Packed Attestation Statement Format
    • tpm: TPM Attestation Statement Format
    • android-key: Android Key Attestation Statement Format
    • android-safetynet: Android SafetyNet Attestation Statement Format
    • fido-u2f: FIDO U2F Attestation Statement Format
    • none: None Attestation Statement Format
    • apple: Apple Anonymous Attestation Format
    • compound: Compound Attestation Statement Format

  10. Normalize origins with FullyQualifiedOrigin

    master

    The FullyQualifiedOrigin function normalizes a raw origin string into the format (scheme)://(host)[:(port)] according to HTML specifications. It strips paths, queries, and user information.

    Special Case: If the input starts with android:apk-key-hash:, the function returns the string as-is without normalization.

  11. Verify WebAuthn client data with CollectedClientData.Verify

    master

    The CollectedClientData struct represents the contextual bindings of the WebAuthn Relying Party and the client. Use its Verify method to perform the security checks required during both credential registration and authentication assertion ceremonies.

    Verification Steps Performed:

    • Ceremony Type: Validates that the Type matches the expected CeremonyType (CreateCeremony for registration or AssertCeremony for authentication).
    • Challenge: Performs a constant-time comparison between the Challenge in the client data and the storedChallenge provided by your server.
    • Origin: Ensures the Origin is present in the provided rpOrigins list.
    • Cross-Origin/Top-Origin: If CrossOrigin is true, it validates the TopOrigin against the allowed origins based on the specified TopOriginVerificationMode.
    • Token Binding: Validates the TokenBinding status if present.

  12. Reference: CeremonyType constants

    master

    The CeremonyType defines the type of WebAuthn ceremony being performed to prevent signature confusion attacks.

    • CreateCeremony: Represents webauthn.create (used during credential registration).
    • AssertCeremony: Represents webauthn.get (used during authentication assertion).