github.com/egregors/passkey @v1.0.8

<h1>🔑 passkey</h1>

passkey is a Go library for implementing WebAuthn services

Table of Contents

• Table of Contents
• Features
• Installation
• Usage
  • Library Usage
    • Implement storages: UserStore and two SessionStore one for WebAuthn and one for general session
    • Create a new Passkey instance and mount the routes
    • Client-side
  • Example Application
• API
  • Middleware
• Development
  • Common tasks
  • Mocks
  • Troubleshooting
    • FAQ
• Contributing
• License

Features

• User Management: Handle user information and credentials.
• WebAuthn Integration: Easily integrate with WebAuthn for authentication.
• Session Management: Manage user sessions securely.
• Middleware Support: Middleware for authenticated routes.

[!NOTE] In general, this library is built on top of two open-source solutions: * Golang WebAuthn Library – https://github.com/go-webauthn/webauthn * JS/TS SimpleWebAuthn client – https://github.com/MasterKale/SimpleWebAuthn

Used in project:

Actual versions:

Installation

To get started, you need to have Go installed on your machine. If you don't have it installed, you can download it from here.

Install the library using go get:

go get github.com/egregors/passkey

Usage

Library Usage

To add a passkey service to your application, you need to do a few simple steps:

Implement storages: UserStore and two SessionStore one for WebAuthn and one for general session

package passkey

import "github.com/go-webauthn/webauthn/webauthn"

// UserStore is a persistent storage for users and credentials
type UserStore interface {
    Create(username string) (User, error)
    Update(User) error

    Get(userID []byte) (User, error)
    GetByName(username string) (User, error)
}

// SessionStore is a storage for session data
type SessionStore[T webauthn.SessionData | UserSessionData] interface {
    Create(data T) (string, error)
    Delete(token string)

    Get(token string) (*T, bool)
}

Your User model also should implement User interface:

package main

import "github.com/go-webauthn/webauthn/webauthn"

// User is a user with webauthn credentials
type User interface {
    webauthn.User
    PutCredential(webauthn.Credential)
}

This interface is an extension of the webauthn.User interface. It adds a PutCredential method that allows you to store a credential in the user object.

Create a new Passkey instance and mount the routes

The whole example is in _example directory.

package main

import (
    "embed"
    "fmt"
    "io/fs"
    "net/http"
    "net/url"
    "time"

    "github.com/go-webauthn/webauthn/webauthn"

    "github.com/egregors/passkey"
    "github.com/egregors/passkey/log"
)

//go:embed web/*
var webFiles embed.FS

const userKey passkey.AuthUserIDKey = "pkUser"

func main() {
    proto := getEnv("PROTO", "http")             // "http" | "https"
    sub := getEnv("SUB", "")                     // "" | "login."
    host := getEnv("HOST", "localhost")          // "localhost" | "example.com"
    originPort := getEnv("ORIGIN_PORT", ":8080") // ":8080" | "" if you use reverse proxy it should be the most "external" port
    serverPort := getEnv("SERVER_PORT", ":8080") // ":8080"

    origin := fmt.Sprintf("%s://%s%s%s", proto, sub, host, originPort)

    l := log.NewLogger()

    pkey, err := passkey.New(
        passkey.Config{
            WebauthnConfig: &webauthn.Config{
                RPDisplayName: "Passkey Example", // Display Name for your site
                RPID:          host,              // Generally the FQDN for your site
                RPOrigins:     []string{origin},  // The origin URLs allowed for WebAuthn
            },
            UserStore:        NewUserStore(),
            AuthSessionStore: NewSessionStore[webauthn.SessionData](),
            UserSessionStore: NewSessionStore[passkey.UserSessionData](),
        },
        passkey.WithLogger(l),
        passkey.WithUserSessionMaxAge(60*time.Minute),
        passkey.WithSessionCookieNamePrefix("passkeyDemo"),
        passkey.WithInsecureCookie(), // In order to support Safari on localhost. Do not use in production.
    )
    if err != nil {
        panic(err)
    }

    mux := http.NewServeMux()

    // mount the passkey routes
    pkey.MountRoutes(mux, "/api/")

    // public routes
    web, _ := fs.Sub(webFiles, "web")
    mux.Handle("/", http.FileServer(http.FS(web)))
    mux.HandleFunc("/logout", func(w http.ResponseWriter, r *http.Request) {
        pkey.Logout(w, r)
        http.Redirect(w, r, "/", http.StatusSeeOther)
    })

    // private routes
    privateMux := http.NewServeMux()
    privateMux.HandleFunc("/", privateHandler())

    // wrap the privateMux with the Auth middleware
    withAuth := pkey.Auth(
        userKey,
        nil,
        passkey.RedirectUnauthorized(url.URL{Path: "/"}),
    )
    mux.Handle("/private", withAuth(privateMux))

    // start the server
    l.Infof("Listening on %s\n", origin)
    if err := http.ListenAndServe(serverPort, mux); err != nil { //nolint:gosec
        panic(err)
    }
}

You can optionally provide a logger to the New function using the WithLogger option.

Full list of options:

Client-side

You need a client-side library that can be used to interact with the server-side library. In example app we use SimpleWebAuthn library (check _example/web directory).

Example Application

The library comes with an example application that demonstrates how to use it. To run the example application just run the following command:

# go run local example app on http://localhost:8080 (no ssl)
make run 

or

# run example app in docker container on https://localhost (with self-signed certificate)
make up 

API

Middleware

The library provides a middleware function that can be used to protect routes that require authentication.

Auth(userIDKey string, onSuccess, onFail http.HandlerFunc) func (next http.Handler) http.Handler

It takes key for context and two callback functions that are called when the user is authenticated or not. You can use the context key to retrieve the authenticated userID from the request context with passkey.UserIDFromCtx.

passkey contains a helper function:

You can use it to protect routes that require authentication:

package main

import (
    "net/url"

    "github.com/egregors/passkey"
)

func main() {
    pkey, err := passkey.New(...)
    check(err)

    withAuth := pkey.Auth(
        "pkUser",
        nil,
        passkey.RedirectUnauthorized(url.URL{Path: "/"}),
    )

    mux.Handle("/private", withAuth(privateMux))
}

Development

Common tasks

To common dev task just use make:

➜  passkey git:(main) make help
Usage: make [task]

task                 help
------               ----

lint                 Lint the files
test                 Run unittests
run                  Run example project
up                   Run example project with local SSL (self-signed certificate)
gen                  Generate mocks
update-go-deps       Updating Go dependencies

help                 Show help message

Mocks

Use mockery to generate mocks for interfaces.A

Troubleshooting

FAQ

Q: I'm getting an error "named cookie not present" when I try to interact with passkey running on localhost from macOS Safari.

A: This is a known issue with Safari and localhost. You can work around it by using the WithInsecureCookie option when creating a new Passkey instance. This will set the Secure flag on the session cookie to false.

Q: I'm getting an error "Error validating origin" when I try to interact with passkey.

A: This error occurs when the origin URL is not included in the RPOrigins list. Make sure that the origin URL is included in the RPOrigins list when creating a new Passkey instance.

Q: I'm getting an error "WebAuthn in not supported in this browser" when I try to interact with passkey on localhost from iOS Safari.

A: Mobile Safari no not store insecure cookies. To play around with the example app on iOS Safari, you should run in with self-signed certificate. Use make up to run the example app in docker container with self-signed certificate.

Contributing

Bug reports, bug fixes and new features are always welcome. Please open issues and submit pull requests for any new code.

License

This project is licensed under the MIT License - see the LICENSE file for details.