Implementation Study: Comparing manual WebAuthn/FIDO2 implementation vs. commercial SaaS solutions
Open source, free to use for any purpose (including commercial). Built for learning, suitable for prototyping.
An interactive laboratory for analyzing passwordless authentication protocols, built as part of an IT Security course project. This POC demonstrates the shift from shared secrets (passwords) to asymmetric cryptography (passkeys) with transparent protocol visualization.
This project investigates Authenticator Assurance Level 2 (AAL2) authentication by implementing:
- Manual Protocol Mode: Direct WebAuthn API interaction with full protocol visibility
- Vendor Comparison Mode: Integration with Corbado's commercial passkey solution
- Live Protocol Tracing: Real-time visualization of cryptographic handshakes
- Forensic Analysis: Session replay and chain-of-custody validation
- Build vs. Buy Trade-offs: Compare transparency vs. convenience
- Security Auditing: Understand what happens during passkey registration/authentication
- Phishing Resistance: See origin-binding in action
- Replay Protection: Observe challenge-response mechanisms
- Python 3.9+
- Node.js 18+ (for Playwright tests)
- Modern browser with WebAuthn support (Chrome, Firefox, Safari, Edge)
-
Clone the repository
git clone https://github.com/dehlya/passkeys-poc.git cd passkeys-poc -
Set up Python environment
cd src python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt
-
Configure environment variables
cp .env.example .env # Edit .env with your settings # Generate SECRET_KEY: python -c "import secrets; print(secrets.token_hex(32))"
-
Run the application
python app.py
-
Access the lab
Open http://localhost:5000 in your browser
See SETUP_GUIDE.md for detailed instructions.
passkeys-poc/
├── README.md # This file - project overview
├── LICENSE # MIT License
├── SECURITY.md # Security policy
├── CONTRIBUTING.md # Contribution guidelines
├── SETUP_GUIDE.md # Detailed setup instructions
│
├── .github/
│ └── workflows/
│ ├── e2e.yml # E2E tests with Playwright
│ └── smoke.yml # Cross-platform smoke tests
│
├── tests/ # E2E test suite
│ └── webauthn.spec.js
│
├── src/ # Main application
├── README.md # App-specific documentation
├── app.py # Flask application & WebAuthn logic
├── config.py # Configuration management
├── requirements.txt # Python dependencies
├── .env.example # Environment template
├── templates/ # HTML templates
│ ├── base.html
│ ├── index.html
│ ├── login.html
│ ├── protected.html
│ ├── workflow.html
│ └── learn.html
└── static/ # Frontend assets
├── main.css
└── main.js
This project was developed as part of the 63-22 IT Security Lab curriculum to demonstrate:
- WebAuthn/FIDO2 Protocol: Deep dive into W3C standard
- Public Key Cryptography: Practical asymmetric authentication
- Security Trade-offs: Transparency vs. convenience analysis
- Threat Modeling: Phishing resistance, replay attacks, MITM
| Aspect | Manual Implementation | Vendor (Corbado) |
|---|---|---|
| Transparency | Full visibility | Black box |
| Control | Complete | Limited |
| Development Time | ~2-3 weeks | ~2-3 hours |
| Maintenance | Your responsibility | Vendor-managed |
| Audit Trail | Complete | Partial |
| Cost | Development time | Subscription |
- CSRF Protection: Token-based validation on state-changing endpoints
- CSP Headers: Content Security Policy enforcement
- Challenge Replay Protection: Single-use nonce verification
- Origin Binding: Prevents phishing attacks
- SQL Injection Prevention: Parameterized queries throughout
- Signature Counter: Detects cloned authenticators
- Session Security: HTTPOnly, SameSite cookies
This is an educational POC - Not production-ready. Missing:
- Rate limiting
- Comprehensive logging/monitoring
- Enterprise IAM integration
- HTTPS enforcement (use reverse proxy in production)
- Advanced threat detection
See SECURITY.md for more details.
This project includes comprehensive automated testing:
# Install test dependencies
npm install
# Run E2E tests
npm run test:e2eTests cover:
- Full registration flow with virtual authenticator
- Authentication with existing credentials
- Protocol trace visualization
- Protected route access control
Automated tests run on every push:
- E2E Tests: Full WebAuthn flows on macOS
- Cross-Platform: Smoke tests on Windows, Linux, macOS
- Multi-Python: Tests on Python 3.9, 3.11, 3.12
See .github/workflows/ for configuration.
- Flask 3.0: Web framework
- py_webauthn 2.0+: WebAuthn protocol implementation
- SQLite: Credential storage
- Corbado SDK: Vendor comparison
- Vanilla JavaScript: WebAuthn client API
- CSS3: Modern styling with design tokens
- Browser Web Crypto API: Native cryptography
- Playwright: End-to-end testing
- Register with Protocol Auditing mode
- View all cryptographic operations
- Inspect raw protocol payloads
- Switch to Corbado tab
- Notice the absence of protocol visibility
- Compare user experience
- Phishing Simulation: Try accessing via
http://127.0.0.1:5000instead oflocalhost. - Result: Authentication fails because the passkey is bound to
localhost(Origin Binding). - Try replaying old challenge (fails)
- Observe signature counter increments
This is an educational project. Contributions welcome for:
- Additional vendor comparisons
- Enhanced testing coverage
- Documentation improvements
- Security hardening suggestions
Please read CONTRIBUTING.md before submitting PRs.
This project is licensed under the MIT License - see the LICENSE file for details.
TL;DR: Free to use for any purpose, including commercial. Attribution appreciated but not required.
FOR EDUCATIONAL AND PROTOTYPING USE
This is a proof-of-concept implementation designed for learning and demonstration purposes. While it implements real security patterns, it is NOT intended for production deployment without significant security hardening, monitoring, and compliance validation.
Use at your own risk. The authors assume no liability for misuse or security vulnerabilities.
- WebAuthn Specification: W3C & FIDO Alliance
- py_webauthn Library: @duo-labs
- Corbado: Vendor comparison partner
- IT Security Lab: Course instructors and peers
For questions about this project, please open an issue on GitHub.
Project Link: https://github.com/dehlya/passkeys-poc
Built for IT Security education