passkey-forwardauth

passkey-forwardauth is a WebAuthn/passkey authentication service for reverse proxies that use forward auth.

The service handles login, sessions, and auth checks for protected applications.

Scope

This project focuses on a small set of functions.

Included features:

• passkey login with WebAuthn discoverable credentials
• forward-auth check endpoint
• session cookies
• redirect allowlisting
• temporary bootstrap admin interface for user and credential enrollment
• optional one-time approval flow

Endpoints

Main service:

• GET /login
• POST /webauthn/login/begin
• POST /webauthn/login/finish
• POST /one-time/login/begin
• GET /one-time/login/status
• POST /one-time/login/approve
• GET /auth
• POST /logout

Bootstrap admin:

• GET /admin
• GET /api/library
• POST /api/users/add
• POST /api/users/delete
• POST /api/users/toggle
• POST /api/credentials/register/begin
• POST /api/credentials/register/finish
• POST /api/credentials/toggle
• POST /api/credentials/delete

How it works

1. The reverse proxy calls GET /auth.
2. When the session is missing or invalid, the proxy returns or redirects to GET /login?rd=....
3. The user completes WebAuthn login.
4. The service sets a session cookie.
5. Later GET /auth requests return 200 OK and X-Auth-User for valid sessions.

Configuration model

The service loads configuration from /etc/passkey-forwardauth/config.{yaml,yml,json,env}.

The service stores state in a JSON identity file. The file contains:

• RP binding (rp_id, rp_origin, cookie_domain)
• users
• registered WebAuthn credentials
• credential metadata
• counters and backup flags

Passkey private keys stay on the authenticator.

Example configuration

listen_addr: ""
listen_unix: "/run/passkey-forwardauth/passkey-forwardauth.sock"
listen_unix_mode: "0660"

cookie_name: "auth_session"
cookie_domain: ".example.com"

admin_cred_path: "/etc/passkey-forwardauth/secrets/identity.json"

proxy_verify_header: "X-Internal-Auth"
proxy_verify_value: "/etc/passkey-forwardauth/secrets/proxy_token"
trusted_proxy_cidrs:
  - "127.0.0.1/32"
  - "::1/128"

redirect_allowed_hosts:
  - "*.example.com"

rp_id: "auth.example.com"
rp_origin: "https://auth.example.com"
login_template: "/usr/share/passkey-forwardauth/templates/login.template"
approve_template: "/usr/share/passkey-forwardauth/templates/approve.template"
static_dir: "/usr/share/passkey-forwardauth/static"
session_ttl: "24h"
session_idle_ttl: "8h"

admin_template: "/usr/share/passkey-forwardauth/templates/admin.template"
bootstrap_listen_addr: "127.0.0.1:19091"
bootstrap_allow_remote: false
bootstrap_idle_timeout: "5m"
bootstrap_max_auth_failures: 3
bootstrap_static_dir: "/usr/share/passkey-forwardauth/static"

Example identity file

{
  "version": 1,
  "rp_id": "auth.example.com",
  "rp_origin": "https://auth.example.com",
  "cookie_domain": ".example.com",
  "users": []
}

Install

Download a package from GitHub Releases and install it:

sudo apt install ./passkey-forwardauth_0.2.0_amd64.deb
sudo systemctl daemon-reload

or:

sudo rpm -Uvh passkey-forwardauth-0.2.0-1.x86_64.rpm
sudo systemctl daemon-reload

Then edit the config and enable the service:

sudoedit /etc/passkey-forwardauth/config.yaml
sudo systemctl enable --now passkey-forwardauth.service

Release Builds

GitHub Actions uses GoReleaser to build Linux binaries plus .deb and .rpm packages for amd64 and arm64.

Create a GitHub release by pushing a version tag:

git tag v0.2.1
git push origin v0.2.1

The same release workflow can be run manually from GitHub Actions by entering an existing v* tag.

Package Layout

The packages install:

• /usr/bin/passkey-forwardauth
• /usr/bin/passkey-forwardauth-bootstrap
• /etc/passkey-forwardauth/config.yaml
• /etc/passkey-forwardauth/secrets/identity.json
• /lib/systemd/system/passkey-forwardauth.service on Debian packages
• /usr/lib/systemd/system/passkey-forwardauth.service on RPM packages
• /usr/share/passkey-forwardauth/templates/
• /usr/share/passkey-forwardauth/static/
• /usr/share/doc/passkey-forwardauth/examples/

Reverse proxy contract

Expected behavior:

• reverse proxy calls GET /auth
• reverse proxy sends a trusted internal verification header
• service returns 200 OK for authenticated sessions
• service returns 401 Unauthorized for unauthenticated requests
• service sets X-Auth-User on successful auth checks

Bootstrap admin

The bootstrap admin handles initial enrollment and maintenance.

Recommended usage:

• local listen address
• explicit enablement
• basic auth
• idle timeout
• shutdown after repeated auth failures

Recommended deployment:

• temporary use
• local or otherwise restricted access

Build From Source

go test ./...
go build ./cmd/passkey-forwardauth
go build ./cmd/passkey-forwardauth-bootstrap

License

Licensed under the Apache License 2.0. See LICENSE.