PasskeyAuth

A minimal FastAPI WebAuthn server with WebSocket support for passkey registration. This project demonstrates WebAuthn registration flow with Resident Keys (discoverable credentials) using modern Python tooling.

Features

  • 🔐 WebAuthn registration with Resident Keys support
  • 🔌 WebSocket-based communication for real-time interaction
  • 🚀 Modern Python packaging with pyproject.toml
  • 🎨 Clean, responsive HTML interface using @simplewebauthn/browser
  • 📦 No database required - challenges stored locally per connection
  • 🛠️ Development tools: ruff for linting and formatting
  • 🧹 Clean architecture with local challenge management

Requirements

  • Python 3.9+
  • A WebAuthn-compatible authenticator (security key, biometric device, etc.)

Quick Start

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone/navigate to the project directory
cd passkeyauth

# Install dependencies and run
uv run passkeyauth.main:main

Using pip

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate.fish  # or venv/bin/activate for bash

# Install the package in development mode
pip install -e ".[dev]"

# Run the server
python -m passkeyauth.main

Using hatch

# Install hatch if you haven't already
pip install hatch

# Run the development server
hatch run python -m passkeyauth.main

Usage

  1. Start the server using one of the methods above
  2. Open your browser to http://localhost:8000
  3. Enter a username (or use the default)
  4. Click "Register Passkey"
  5. Follow your authenticator's prompts to create a passkey

The WebSocket connection will show real-time status updates as you progress through the registration flow.

Development

Code Quality

# Run linting and formatting with ruff
uv run ruff check .
uv run ruff format .

# Or with hatch
hatch run ruff check .
hatch run ruff format .

Project Structure

passkeyauth/
├── passkeyauth/
│   ├── __init__.py
│   └── main.py          # FastAPI server with WebSocket support
├── static/
│   └── index.html       # Frontend interface
├── pyproject.toml       # Modern Python packaging configuration
└── README.md

Technical Details

WebAuthn Configuration

  • Relying Party ID: localhost (for development)
  • Resident Keys: Required (enables discoverable credentials)
  • User Verification: Preferred
  • Supported Algorithms: ECDSA-SHA256, RSASSA-PKCS1-v1_5-SHA256

WebSocket Message Flow

  1. Client connects to /ws/{client_id}
  2. Client sends registration_challenge message
  3. Server responds with registration_challenge_response
  4. Client completes WebAuthn ceremony and sends registration_response
  5. Server verifies and responds with registration_success or error

Security Notes

  • This is a minimal demo - challenges are stored locally per WebSocket connection
  • For production use, implement proper user storage and session management
  • Consider using Redis or similar for challenge storage in production with multiple server instances
  • Ensure HTTPS in production environments

License

MIT License - feel free to use this as a starting point for your own WebAuthn implementations!

Description
No description provided
Readme 2.3 MiB
Languages
Python 46.5%
JavaScript 38.3%
HTML 11.2%
CSS 4%