gienielab/silverstripe-passkey-auth

A comprehensive passkey (WebAuthn) authentication module for SilverStripe with secure, passwordless authentication using biometrics, security keys, or device authentication.

v1.1 2025-08-11 11:22 UTC

Requires

• php: ^8.3
• silverstripe/framework: ^5.0 || ^6.0
• web-auth/cose-lib: ^4.0
• web-auth/webauthn-lib: ^4.0

Requires (Dev)

• phpunit/phpunit: ^9.5 || ^10.0
• silverstripe/standards: ^1.0
• squizlabs/php_codesniffer: ^3.7

BSD-3-Clause

• Priscilla

• security
• Authentication
• silverstripe
• Passwordless
• biometric
• FIDO2
• webauthn
• passkey

README

A comprehensive passkey (WebAuthn) authentication module for SilverStripe that provides secure, passwordless authentication using biometrics, security keys, or device authentication.

✨ Features

• 🔐 Enterprise Security: 6-layer security protection with comprehensive threat mitigation
• 👆 Multiple Authentication Methods: Fingerprint, face recognition, security keys
• 🔄 Dual Login System: Works alongside traditional password authentication
• 📱 Cross-Platform: Works on desktop and mobile devices
• 🛡️ Advanced Protection: Rate limiting, CSRF protection, bot filtering, comprehensive logging
• 🛠️ Admin Management: Full admin interface for credential management
• 👤 User Self-Service: Users can manage their own passkeys
• 🎨 Customizable Styling: YAML-based theming and modern CSS
• 🏢 Enterprise Ready: MFA compatibility, subsites support, performance optimized

📋 Requirements

• SilverStripe ^5.0 || ^6.0
• PHP ^8.3
• HTTPS enabled (required for WebAuthn)
• Modern browser with WebAuthn support

🚀 Quick Installation

1. Install via Composer

composer require gienielab/silverstripe-passkey-auth

2. Run Database Build

vendor/bin/sake dev/build flush=1

3. Configure Domains

Add to your .env file:

SS_ALLOWED_HOSTS="yourdomain.com,www.yourdomain.com"

4. Basic Configuration

Create app/_config/passkey-config.yml:

---
Name: passkey-config
---
GienieLab\PasskeyAuth\Service\PasskeyService:
  extensions:
    - GienieLab\PasskeyAuth\Extension\PasskeyHostExtension
  rp_name: 'Your Application Name'

That's it! 🎉 Your passkey authentication is ready to use.

📚 Documentation

Essential Guides

• 📖 Usage Guide - Complete user and admin guide
• 🔒 Security Guide - Multi-layer security implementation
• ⚙️ Configuration - Detailed configuration options
• 🎨 Theming & Customization - Styling and branding
• 📑 Full Documentation Index - All available documentation

Quick Links

• 🔧 Advanced Configuration - Performance, MFA, subsites
• 🏗️ Multiple Domains Setup - Complex domain configurations
• 🔍 Troubleshooting - Common issues and solutions

🎯 How It Works

For Users

1. Register: Log in with password, then register your passkey (fingerprint/face/security key)
2. Login: Next time, just click "Sign in with Passkey" and authenticate
3. Manage: Visit /passkey-management to add/remove passkeys

For Admins

• Overview: Visit /admin/passkey-credentials to manage all passkeys
• Configuration: Check /admin/passkey-hosts for domain setup
• Monitoring: Track usage and security across your organization

🔒 Security & Browser Support

Enterprise-Grade Security

The module implements 6 layers of security protection:

1. 🛡️ User-Agent Filtering - Blocks bots and automated attacks
2. ⚡ Rate Limiting - Prevents brute force attacks (5 req/hour default)
3. 📏 Request Size Limits - Stops payload attacks (1KB limit)
4. 🌐 Origin Validation - Prevents CSRF attacks
5. 🔑 CSRF Token Protection - Secures state-changing operations
6. 📊 Comprehensive Logging - Monitors all security events

See Security Guide for complete implementation details and testing.

HTTPS Required

Passkeys require HTTPS in production. Localhost and development domains are automatically allowed.

Browser Compatibility

Browser	Support	Notes
Chrome 67+	✅ Full	Best support
Firefox 60+	✅ Full	Good support
Safari 14+	✅ Full	iOS 14+ required
Edge 18+	✅ Full	Chromium-based

🛠️ Development

Prerequisites

• Node.js (v18+)
• Yarn
• PHP ^8.3

Building Assets

# Install dependencies
yarn install

# Production build
yarn build

# Development with watch
yarn watch

# Development server
yarn dev

Build Features

• Modern ES6+ Support: Babel transpilation
• SCSS Compilation: PostCSS optimization
• Code Splitting: Performance optimization
• Source Maps: Development debugging
• Hot Module Replacement: Instant feedback

Project Structure

├── _config/           # SilverStripe configuration
## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

See [Development Documentation](docs/USAGE.md#development--contribution) for detailed guidelines.

## 📄 License

This module is released under the MIT license. See [LICENSE](LICENSE) file for details.

## 🙏 Credits

Built with:
- [web-auth/webauthn-lib](https://github.com/web-auth/webauthn-lib) - WebAuthn server library
- [SilverStripe Framework](https://silverstripe.org) - CMS/Framework
- WebAuthn specification by [W3C](https://w3c.github.io/webauthn/)

## 🆘 Support

- **📖 Documentation**: [Complete documentation](docs/README.md)
- **🐛 Bug Reports**: [GitHub Issues](https://github.com/gienielab/silverstripe-passkey-auth/issues)
- **💬 Questions**: [SilverStripe Community](https://forum.silverstripe.org)
- **🔒 Security Issues**: Email maintainers directly

---

**Ready to get started?** Check out the [Usage Guide](docs/USAGE.md) for detailed instructions! 🚀