passkey-auth/IMPLEMENTATION.md

📋 Implementation Summary

What We've Built

✅ Complete Passkey Authentication System with email-based access control ✅ SQLite Database for persistent user storage ✅ Email Allowlist System for controlling who can register ✅ Kubernetes Integration with nginx ingress auth backend ✅ Modern Web UI for user registration and management ✅ Production-Ready Deployment with Docker and Kubernetes manifests

Key Features Implemented

🔐 Email-Based Authentication

• Users are identified by email addresses (not usernames)
• Configurable email allowlist for access control
• Environment variable support for email configuration

📧 Email Access Control Options

1. Open Mode: Empty allowlist allows any email
2. Restricted Mode: Only allowlisted emails can register
3. Combined Security: Allowlist + manual approval

🗄️ Database Architecture (SQLite)

-- Users table
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email TEXT UNIQUE NOT NULL,     -- Email as primary identifier
    display_name TEXT NOT NULL,
    approved BOOLEAN DEFAULT FALSE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Credentials table (WebAuthn keys)
CREATE TABLE credentials (
    id BLOB PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    public_key BLOB NOT NULL,
    attestation_type TEXT NOT NULL,
    aaguid BLOB,
    sign_count INTEGER DEFAULT 0,
    clone_warning BOOLEAN DEFAULT FALSE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

⚙️ Configuration Options

auth:
  session_secret: "your-secret-key"
  require_approval: true           # Admin approval required
  allowed_emails:                  # Email allowlist
    - "admin@company.com"
    - "engineering@company.com"

Or via environment variables:

export ALLOWED_EMAILS="admin@company.com,user1@company.com,user2@company.com"
export SESSION_SECRET="your-secure-session-secret"

Files Created/Modified

Core Application

• main.go - Application entry point
• internal/config/ - Configuration management with email allowlist
• internal/database/ - SQLite database layer with email-based users
• internal/auth/ - WebAuthn implementation
• internal/handlers/ - HTTP handlers with email validation

Web Interface

• web/index.html - Admin UI updated for email addresses

Deployment

• Dockerfile - Container build
• k8s/ - Kubernetes manifests
• docker-compose.yml - Local development
• scripts/ - Build and deployment scripts

Documentation

• README.md - Complete usage guide
• PRODUCTION.md - Production deployment guide
• config.example.yaml - Example configuration

How It Works

1. Email Validation: When a user tries to register, the system checks if their email is in the allowlist (if configured)
2. Database Storage: User data is stored in SQLite with email as the unique identifier
3. WebAuthn Integration: Passkey credentials are linked to the user record
4. Session Management: Authentication sessions use email-based identification
5. Nginx Integration: Auth headers include user email for downstream applications

Quick Start

# 1. Configure email allowlist
vim config.yaml  # Add your allowed emails

# 2. Start the service
./scripts/dev.sh

# 3. Register users at http://localhost:8080
# Only emails in the allowlist can register

# 4. Deploy to Kubernetes
./scripts/build.sh
./scripts/deploy.sh

Security Benefits

• No passwords stored - Only WebAuthn public keys
• Email-based access control - Restrict registration to specific domains/emails
• Phishing resistant - WebAuthn is tied to the domain
• MFA built-in - Passkeys require user presence and verification
• Session security - Secure cookie-based sessions

This implementation provides a complete, production-ready passkey authentication system with fine-grained email-based access control, perfect for enterprise environments where you need to restrict access to specific users.