mirror of
https://github.com/wahyd4/passkey-auth.git
synced 2026-08-09 04:15:55 +10:00
junv
9427c36b8b
- Complete WebAuthn/FIDO2 authentication implementation - SQLite database with user and credential management - Email-based user identification with allowlist support - Admin approval workflow for new users - Session management with secure cookies - Docker containerization with Debian base for SQLite compatibility - Kubernetes deployment manifests with nginx ingress support - Web-based admin interface for user management - Comprehensive documentation and deployment guides - Standard open source project structure with CI/CD
123 lines
3.9 KiB
Markdown
123 lines
3.9 KiB
Markdown
# 📋 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)
|
|
```sql
|
|
-- 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
|
|
|
|
```yaml
|
|
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:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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.
|