{"id":13570339,"url":"https://github.com/go-webauthn/webauthn","last_synced_at":"2026-04-10T03:27:58.465Z","repository":{"id":38444758,"uuid":"438441323","full_name":"go-webauthn/webauthn","owner":"go-webauthn","description":"Webauthn/FIDO2 library in golang","archived":false,"fork":false,"pushed_at":"2025-03-30T21:46:12.000Z","size":1148,"stargazers_count":918,"open_issues_count":21,"forks_count":88,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-30T22:26:47.564Z","etag":null,"topics":["ctap2","fido2","go","golang","passwordless","passwordless-authentication","security","webauthn"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-webauthn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-15T00:17:43.000Z","updated_at":"2025-03-30T21:46:14.000Z","dependencies_parsed_at":"2023-02-02T22:01:29.363Z","dependency_job_id":"5220fc87-de0b-4442-a103-44490b8bbc4b","html_url":"https://github.com/go-webauthn/webauthn","commit_stats":null,"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-webauthn%2Fwebauthn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-webauthn%2Fwebauthn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-webauthn%2Fwebauthn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-webauthn%2Fwebauthn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-webauthn","download_url":"https://codeload.github.com/go-webauthn/webauthn/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247134992,"owners_count":20889412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ctap2","fido2","go","golang","passwordless","passwordless-authentication","security","webauthn"],"created_at":"2024-08-01T14:00:51.215Z","updated_at":"2026-04-10T03:27:53.437Z","avatar_url":"https://github.com/go-webauthn.png","language":"Go","funding_links":[],"categories":["Go","Server Libraries"],"sub_categories":[],"readme":"# WebAuthn Library\r\n\r\n[![GoDoc](https://godoc.org/github.com/go-webauthn/webauthn?status.svg)](https://godoc.org/github.com/go-webauthn/webauthn)\r\n[![Go Report Card](https://goreportcard.com/badge/github.com/go-webauthn/webauthn)](https://goreportcard.com/report/github.com/go-webauthn/webauthn)\r\n\r\n\r\nThis library is meant to handle [Web Authentication](https://www.w3.org/TR/webauthn) for Go apps that wish to implement \r\na passwordless solution for users. This library conforms as much as possible to the guidelines and implementation\r\nprocedures outlined by the document.\r\n\r\n## Fork\r\n\r\nThis library is a hard fork of [github.com/duo-labs/webauthn] and is the natural successor to that library.\r\n\r\nSee the [migration](MIGRATION.md) guide for more information about how to migrate and the differences between the\r\nlibraries.\r\n\r\nIt is distributed under the same 3-Clause BSD license as the original fork, with the only amendment being the additional\r\n3-Clause BSD license attributing license rights to this repository.\r\n\r\n## Go Version Support Policy\r\n\r\nThis library; unless otherwise explicitly expressed; will officially support versions of go which are currently\r\nsupported by the go maintainers (usually 3 minor versions) with a brief transition time (usually 1 patch release of go,\r\nfor example if go 1.21.0 is released, we will likely still support go 1.17 until go 1.21.1 is released). These specific\r\nrules apply at the time of a published release.\r\n\r\nThis library in our opinion handles a critical element of security in a dependent project and we aim to avoid backwards\r\ncompatibility at the cost of security wherever possible. We also consider this especially important in a language like\r\ngo where their backwards compatibility when upgrading the compile tools is usually flawless.\r\n\r\nThis policy means that users who wish to build this with older versions of go may find there are features being used\r\nwhich are not available in that version. The current intentionally supported versions of go are as follows:\r\n\r\n- go 1.22\r\n- go 1.21\r\n- ~~go 1.20~~:\r\n  - Go 1.20 support has been removed due to the new toolchain directive and lack of support in Go 1.20. This directive\r\n    is unfortunately being used in dependent libraries and we'd opt for ensuring we can easily obtain potential fixes\r\n    to CVE's rather than backwards compatibility. A such we have lifted the version requirement and implemented the\r\n    toolchain directive in our module to reflect the intended toolchain.\r\n\r\n## Status\r\n\r\nThis library is still version 0, as per Semantic Versioning 2.0 rules there may be breaking changes without warning. \r\nWhile we strive to avoid such changes and strive to notify users they may be unavoidable.\r\n\r\n## Quickstart\r\n\r\n`go get github.com/go-webauthn/webauthn` and initialize it in your application with basic configuration values. \r\n\r\nMake sure your `user` model is able to handle the interface functions laid out in `webauthn/types.go`. This means also \r\nsupporting the storage and retrieval of the credential and authenticator structs in `webauthn/credential.go` and \r\n`webauthn/authenticator.go`, respectively.\r\n\r\n## Examples\r\n\r\nThe following examples show some basic use cases of the library. For consistency sake the following variables are used\r\nto denote specific things:\r\n\r\n- Variable `webAuthn`: the `webauthn.WebAuthn` instance you initialize elsewhere in your code\r\n- Variable `datastore`: the pseudocode backend service that stores your webauthn session data and users such as PostgreSQL \r\n- Variable `session`: the webauthn.SessionData object\r\n- Variable `user`: your webauthn.User implementation\r\n\r\nWe try to avoid using specific external libraries (excluding stdlib) where possible, and you'll need to adapt these\r\nexamples with this in mind.\r\n\r\n### Initialize the request handler\r\n\r\n```go\r\npackage example\r\n\r\nimport (\r\n\t\"fmt\"\r\n\r\n\t\"github.com/go-webauthn/webauthn/webauthn\"\r\n)\r\n\r\nvar (\r\n\twebAuthn *webauthn.WebAuthn\r\n\terr error\r\n)\r\n\r\n// Your initialization function\r\nfunc main() {\r\n\twconfig := \u0026webauthn.Config{\r\n\t\tRPDisplayName: \"Go Webauthn\", // Display Name for your site\r\n\t\tRPID: \"go-webauthn.local\", // Generally the FQDN for your site\r\n\t\tRPOrigins: []string{\"https://login.go-webauthn.local\"}, // The origin URLs allowed for WebAuthn requests\r\n\t}\r\n\t\r\n\tif webAuthn, err = webauthn.New(wconfig); err != nil {\r\n\t\tfmt.Println(err)\r\n\t}\r\n}\r\n```\r\n\r\n### Registering an account\r\n\r\n```go\r\npackage example\r\n\r\nfunc BeginRegistration(w http.ResponseWriter, r *http.Request) {\r\n\tuser := datastore.GetUser() // Find or create the new user  \r\n\toptions, session, err := webAuthn.BeginRegistration(user)\r\n\t// handle errors if present\r\n\t// store the sessionData values \r\n\tJSONResponse(w, options, http.StatusOK) // return the options generated\r\n\t// options.publicKey contain our registration options\r\n}\r\n\r\nfunc FinishRegistration(w http.ResponseWriter, r *http.Request) {\r\n\tuser := datastore.GetUser() // Get the user\r\n\t\r\n\t// Get the session data stored from the function above\r\n\tsession := datastore.GetSession()\r\n\t\t\r\n\tcredential, err := webAuthn.FinishRegistration(user, session, r)\r\n\tif err != nil {\r\n\t\t// Handle Error and return.\r\n\r\n\t\treturn\r\n\t}\r\n\t\r\n\t// If creation was successful, store the credential object\r\n\t// Pseudocode to add the user credential.\r\n\tuser.AddCredential(credential)\r\n\tdatastore.SaveUser(user)\r\n\r\n\tJSONResponse(w, \"Registration Success\", http.StatusOK) // Handle next steps\r\n}\r\n```\r\n\r\n### Logging into an account\r\n\r\n```go\r\npackage example\r\n\r\nfunc BeginLogin(w http.ResponseWriter, r *http.Request) {\r\n\tuser := datastore.GetUser() // Find the user\r\n\t\r\n\toptions, session, err := webAuthn.BeginLogin(user)\r\n\tif err != nil {\r\n\t\t// Handle Error and return.\r\n\r\n\t\treturn\r\n\t}\r\n\t\r\n\t// store the session values\r\n\tdatastore.SaveSession(session)\r\n\t\r\n\tJSONResponse(w, options, http.StatusOK) // return the options generated\r\n\t// options.publicKey contain our registration options\r\n}\r\n\r\nfunc FinishLogin(w http.ResponseWriter, r *http.Request) {\r\n\tuser := datastore.GetUser() // Get the user \r\n\t\r\n\t// Get the session data stored from the function above\r\n\tsession := datastore.GetSession()\r\n\t\r\n\tcredential, err := webAuthn.FinishLogin(user, session, r)\r\n\tif err != nil {\r\n\t\t// Handle Error and return.\r\n\r\n\t\treturn\r\n\t}\r\n\r\n\t// Handle credential.Authenticator.CloneWarning\r\n\r\n\t// If login was successful, update the credential object\r\n\t// Pseudocode to update the user credential.\r\n\tuser.UpdateCredential(credential)\r\n\tdatastore.SaveUser(user)\r\n\t\r\n\tJSONResponse(w, \"Login Success\", http.StatusOK)\r\n}\r\n```\r\n\r\n## Modifying Credential Options\r\n\r\nYou can modify the default credential creation options for registration and login by providing optional structs to the \r\n`BeginRegistration` and `BeginLogin` functions. \r\n\r\n### Registration modifiers\r\n\r\nYou can modify the registration options in the following ways:\r\n\r\n```go\r\npackage example\r\n\r\nimport (\r\n\t\"github.com/go-webauthn/webauthn/protocol\"\r\n\t\"github.com/go-webauthn/webauthn/webauthn\"\r\n)\r\n\r\nvar webAuthn webauthn.WebAuthn // init this in your init function\r\n\r\nfunc beginRegistration() {\r\n\t// Updating the AuthenticatorSelection options. \r\n\t// See the struct declarations for values\r\n\tauthSelect := protocol.AuthenticatorSelection{\r\n\t\tAuthenticatorAttachment: protocol.AuthenticatorAttachment(\"platform\"),\r\n\t\tRequireResidentKey: protocol.ResidentKeyNotRequired(),\r\n\t\tUserVerification: protocol.VerificationRequired,\r\n\t}\r\n\r\n\t// Updating the ConveyencePreference options. \r\n\t// See the struct declarations for values\r\n\tconveyancePref := protocol.PreferNoAttestation\r\n\r\n\tuser := datastore.GetUser() // Get the user  \r\n\topts, session, err := webAuthn.BeginRegistration(user, webauthn.WithAuthenticatorSelection(authSelect), webauthn.WithConveyancePreference(conveyancePref))\r\n\r\n\t// Handle next steps\r\n}\r\n```\r\n\r\n### Login modifiers\r\n\r\nYou can modify the login options to allow only certain credentials:\r\n\r\n```go\r\npackage example\r\n\r\nimport (\r\n\t\"github.com/go-webauthn/webauthn/protocol\"\r\n\t\"github.com/go-webauthn/webauthn/webauthn\"\r\n)\r\n\r\nvar webAuthn webauthn.WebAuthn // init this in your init function\r\n\r\nfunc beginLogin() {\r\n\t// Updating the AuthenticatorSelection options. \r\n\t// See the struct declarations for values\r\n\tallowList := make([]protocol.CredentialDescriptor, 1)\r\n\tallowList[0] = protocol.CredentialDescriptor{\r\n\t\tCredentialID: credentialToAllowID,\r\n\t\tType: protocol.CredentialType(\"public-key\"),\r\n\t}\r\n\r\n\tuser := datastore.GetUser() // Get the user  \r\n\r\n\topts, session, err := w.BeginLogin(user, webauthn.WithAllowedCredentials(allowList))\r\n\r\n\t// Handle next steps\r\n}\r\n```\r\n\r\n## Timeout Mechanics\r\n\r\nThe library by default does not enforce timeouts. However the default timeouts sent to the browser are taken from the\r\nspecification. You can override both of these behaviours however.\r\n\r\n```go\r\npackage example\r\n\r\nimport (\r\n\t\"fmt\"\r\n\t\"time\"\r\n\t\r\n\t\"github.com/go-webauthn/webauthn/protocol\"\r\n\t\"github.com/go-webauthn/webauthn/webauthn\"\r\n)\r\n\r\nfunc main() {\r\n\twconfig := \u0026webauthn.Config{\r\n\t\tRPDisplayName: \"Go Webauthn\",                               // Display Name for your site\r\n\t\tRPID:          \"go-webauthn.local\",                         // Generally the FQDN for your site\r\n\t\tRPOrigins:     []string{\"https://login.go-webauthn.local\"}, // The origin URLs allowed for WebAuthn requests\r\n\t\tTimeouts: webauthn.TimeoutsConfig{\r\n\t\t\tLogin: webauthn.TimeoutConfig{\r\n\t\t\t\tEnforce:    true, // Require the response from the client comes before the end of the timeout.\r\n\t\t\t\tTimeout:    time.Second * 60, // Standard timeout for login sessions.\r\n\t\t\t\tTimeoutUVD: time.Second * 60, // Timeout for login sessions which have user verification set to discouraged.\r\n\t\t\t},\r\n\t\t\tRegistration: webauthn.TimeoutConfig{\r\n\t\t\t\tEnforce:    true, // Require the response from the client comes before the end of the timeout.\r\n\t\t\t\tTimeout:    time.Second * 60, // Standard timeout for registration sessions.\r\n\t\t\t\tTimeoutUVD: time.Second * 60, // Timeout for login sessions which have user verification set to discouraged.\r\n\t\t\t},\r\n\t\t},\r\n\t}\r\n\t\r\n\twebAuthn, err := webauthn.New(wconfig)\r\n\tif err != nil {\r\n\t\tfmt.Println(err)\r\n\t}\r\n}\r\n```\r\n\r\n## Credential Record\r\n\r\nThe WebAuthn Level 3 specification describes the Credential Record which includes several required and optional elements\r\nthat you should store for. See [§ 4 Terminology](https://www.w3.org/TR/webauthn-3/#credential-record) for details.\r\n\r\nThis section describes this element. \r\n\r\nThe fields listed in the specification have corresponding fields in the [webauthn.Credential] struct. See the below\r\ntable for more information. We also include JSON mappings for those that wish to just store these values as JSON.\r\n\r\n|    Specification Field    |       Library Field        |         JSON Field         |                                           Notes                                           |\r\n|:-------------------------:|:--------------------------:|:--------------------------:|:-----------------------------------------------------------------------------------------:|\r\n|           type            |            N/A             |            N/A             |                       This field is always `publicKey` for WebAuthn                       |\r\n|            id             |             ID             |             id             |                                                                                           |\r\n|         publicKey         |         PublicKey          |         publicKey          |                                                                                           |\r\n|         signCount         |  Authenticator.SignCount   |  authenticator.signCount   |                                                                                           |\r\n|        transports         |         Transport          |         transport          |                                                                                           |\r\n|       uvInitialized       |     Flags.UserVerified     |     flags.userVerified     |                                                                                           |\r\n|      backupEligible       |    Flags.BackupEligible    |    flags.backupEligible    |                                                                                           |\r\n|        backupState        |     Flags.BackupState      |     flags.backupState      |                                                                                           |\r\n|     attestationObject     |     Attestation.Object     |     attestation.object     | This field is a composite of the attestationObject and the relevant values to validate it |\r\n| attestationClientDataJSON | Attestation.ClientDataJSON | attestation.clientDataJSON |                                                                                           |\r\n\r\n### Storage\r\n\r\nIt is also important to note that restoring the [webauthn.Credential] with the correct values will likely affect the\r\nvalidity of the [webauthn.Credential], i.e. if some values are not restored the [webauthn.Credential] may fail\r\nvalidation in this scenario.\r\n\r\n### Verification\r\n\r\nAs long as the [webauthn.Credential] struct has exactly the same values when restored the [Credential Verify] function \r\ncan be leveraged to verify the credential against the [metadata.Provider]. This can be either done during registration,\r\non every login, or with a audit schedule.\r\n\r\nIn addition to using the [Credential Verify] function the \r\n[webauthn.Config](https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#Config) can contain a provider which will\r\nprocess all registrations automatically.\r\n\r\nAt this time no tooling exists to verify the credential automatically outside the registration flow. Implementation of\r\nthis is considered domain logic and beyond the scope of what we provide documentation for; we just provide the necessary\r\ntooling to implement this yourself.\r\n\r\n## Acknowledgements\r\n\r\nWe graciously acknowledge the original authors of this library [github.com/duo-labs/webauthn] for their amazing\r\nimplementation. Without their amazing work this library could not exist.\r\n\r\n\r\n[github.com/duo-labs/webauthn]: https://github.com/duo-labs/webauthn\r\n[webauthn.Credential]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#Credential\r\n[metadata.Provider]: https://pkg.go.dev/github.com/go-webauthn/webauthn/metadata#Provider\r\n[Credential Verify]: https://pkg.go.dev/github.com/go-webauthn/webauthn/webauthn#Credential.Verify","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-webauthn%2Fwebauthn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-webauthn%2Fwebauthn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-webauthn%2Fwebauthn/lists"}