294b28d1a8
- Added docs/AUTH.md with authentication system documentation - Added server scripts (auto-deploy, backup, monitor, webhook-server) - Updated README with deployment info and project structure - Added gitignore for backup archives
279 lines
8.5 KiB
Markdown
279 lines
8.5 KiB
Markdown
# b0esche.cloud Authentication System
|
|
|
|
This document describes the complete passkey-first authentication and authorization system for b0esche.cloud.
|
|
|
|
## Overview
|
|
|
|
b0esche.cloud implements a modern, secure, username-only, passkey-first authentication system with comprehensive admin functionality and recovery options.
|
|
|
|
## Authentication Flow
|
|
|
|
### Primary Authentication: Passkeys (WebAuthn)
|
|
|
|
- **Username + Passkey Registration**: Users create an account with just a username and register a passkey
|
|
- **Passkey-First Login**: Primary authentication method using WebAuthn/FIDO2 standards
|
|
- **Device Support**: Works with Touch ID, Windows Hello, YubiKey, and other FIDO2 authenticators
|
|
- **Multiple Passkeys**: Users can register multiple devices for redundancy
|
|
|
|
### Fallback Options
|
|
|
|
- **Optional Password**: Users can add a password as a fallback authentication method
|
|
- **Recovery Codes**: 10 single-use recovery codes generated per user
|
|
- **Admin Recovery**: Admins can assist with account recovery if needed
|
|
|
|
## User Roles and Permissions
|
|
|
|
### Role Hierarchy
|
|
|
|
1. **superadmin** (Level 3): Full system access
|
|
- User management and role assignments
|
|
- Admin invitation system
|
|
- System configuration access
|
|
- All organization management
|
|
|
|
2. **admin** (Level 2): Administrative access
|
|
- Organization management
|
|
- User role promotion (within their orgs)
|
|
- Activity monitoring
|
|
- File management across organizations
|
|
|
|
3. **user** (Level 1): Standard user access
|
|
- Personal file management
|
|
- Organization membership
|
|
- Basic account settings
|
|
|
|
## Bootstrap Process
|
|
|
|
### Creating the First Administrator
|
|
|
|
The system includes a bootstrap utility to create the first superadmin user securely:
|
|
|
|
```bash
|
|
# Interactive mode (recommended for production)
|
|
./bin/bootstrap
|
|
|
|
# Environment variable mode (recommended for automation)
|
|
export BOOTSTRAP_ADMIN_USERNAME=admin
|
|
export BOOTSTRAP_ADMIN_PASSWORD=secure_password_123
|
|
./bin/bootstrap
|
|
```
|
|
|
|
#### Bootstrap Process
|
|
|
|
1. **Check Existing Admin**: Verifies no superadmin user already exists
|
|
2. **Secure Input**: Prompts for username and password (or reads from environment)
|
|
3. **Password Security**: Enforces minimum 8-character passwords
|
|
4. **Role Assignment**: Automatically assigns superadmin role
|
|
5. **Secure Storage**: Passwords are bcrypt-hashed before storage
|
|
|
|
#### Security Guidelines
|
|
|
|
- **Immediate Action**: Log in immediately after bootstrap to register a passkey
|
|
- **Passkey Priority**: Set up passkeys and consider removing the password
|
|
- **Recovery Setup**: Generate recovery codes during first login
|
|
- **Credential Rotation**: Never leave default credentials in production
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication Endpoints
|
|
|
|
```
|
|
POST /auth/passkey/register/start
|
|
POST /auth/passkey/register/verify
|
|
POST /auth/passkey/login/start
|
|
POST /auth/passkey/login/verify
|
|
```
|
|
|
|
### Device Management
|
|
|
|
```
|
|
GET /auth/passkey/devices # List user's passkeys
|
|
POST /auth/passkey/devices/add # Add new passkey
|
|
DELETE /auth/passkey/devices/{id} # Remove passkey
|
|
```
|
|
|
|
### Recovery System
|
|
|
|
```
|
|
POST /auth/recovery/codes/generate # Generate recovery codes
|
|
POST /auth/recovery/codes/use # Use recovery code
|
|
DELETE /auth/recovery/codes/revoke # Revoke all codes
|
|
```
|
|
|
|
### Admin Operations
|
|
|
|
```
|
|
GET /auth/admin/invitations # List invitations
|
|
POST /auth/admin/invitations # Create invitation
|
|
POST /auth/admin/invitations/accept # Accept invitation
|
|
DELETE /auth/admin/invitations/{id} # Revoke invitation
|
|
```
|
|
|
|
### Password Fallback
|
|
|
|
```
|
|
POST /auth/password/add # Add password to account
|
|
DELETE /auth/password/remove # Remove password from account
|
|
```
|
|
|
|
## Environment Configuration
|
|
|
|
```bash
|
|
# Server Configuration
|
|
SERVER_ADDR=:8080
|
|
DATABASE_URL=postgresql://user:pass@localhost/db
|
|
|
|
# WebAuthn Configuration
|
|
WEBAUTHN_RP_ID=www.b0esche.cloud
|
|
WEBAUTHN_RP_NAME=b0esche.cloud
|
|
WEBAUTHN_RP_ORIGIN=https://www.b0esche.cloud
|
|
|
|
# Security Configuration
|
|
JWT_SECRET=your_jwt_secret_key
|
|
PASSKEY_TIMEOUT=300000
|
|
RECOVERY_CODE_EXPIRY=86400
|
|
MAX_RECOVERY_CODES=10
|
|
```
|
|
|
|
## Security Features
|
|
|
|
### WebAuthn Security
|
|
|
|
- **FIDO2/WebAuthn Compliant**: Full compliance with WebAuthn Level 2
|
|
- **Origin Binding**: Credentials bound to specific domain
|
|
- **Challenge-Response**: Cryptographic challenge verification
|
|
- **Device Attestation**: Optional device verification
|
|
- **Public Key Crypto**: Asymmetric cryptography with private keys never leaving devices
|
|
|
|
### Account Security
|
|
|
|
- **Rate Limiting**: Built-in protection against brute force attacks
|
|
- **Session Management**: Secure HTTP-only sessions with configurable expiration
|
|
- **Audit Logging**: Comprehensive logging of all authentication and admin actions
|
|
- **Role-Based Access Control**: Hierarchical permission system
|
|
|
|
### Data Protection
|
|
|
|
- **Password Hashing**: bcrypt with automatic salt generation
|
|
- **Recovery Code Hashing**: Secure one-way hashing of recovery codes
|
|
- **No Plaintext Storage**: No sensitive data stored in plaintext
|
|
- **Input Validation**: Comprehensive input sanitization and validation
|
|
|
|
## Database Schema
|
|
|
|
The authentication system uses the following key tables:
|
|
|
|
- **users**: User accounts with role-based access control
|
|
- **roles**: Hierarchical role definitions
|
|
- **passkeys**: WebAuthn credential storage
|
|
- **recovery_codes**: One-time recovery codes
|
|
- **admin_invitations**: Secure admin invitation system
|
|
- **sessions**: Secure session management
|
|
|
|
## Development and Testing
|
|
|
|
### Running Locally
|
|
|
|
1. **Setup Database**: Ensure PostgreSQL is running with migrations applied
|
|
2. **Bootstrap Admin**: Run the bootstrap command to create first admin
|
|
3. **Start Server**: Run the API server with appropriate environment
|
|
4. **Test Authentication**: Use the Flutter app or API tests
|
|
|
|
### Testing WebAuthn
|
|
|
|
WebAuthn requires HTTPS in production browsers. For local testing:
|
|
|
|
```bash
|
|
# Use mkcert for local HTTPS
|
|
mkcert -install
|
|
mkcert localhost 127.0.0.1 ::1
|
|
|
|
# Set environment for local development
|
|
export WEBAUTHN_RP_ID=localhost
|
|
export WEBAUTHN_RP_ORIGIN=https://localhost:8080
|
|
```
|
|
|
|
## User Experience
|
|
|
|
### Signup Flow
|
|
|
|
1. **Username Selection**: User chooses a unique username
|
|
2. **Real-time Validation**: Immediate feedback on username availability
|
|
3. **Passkey Creation**: Browser prompts for passkey registration
|
|
4. **Account Creation**: Automatic account creation with passkey
|
|
|
|
### Login Flow
|
|
|
|
1. **Passkey Detection**: System shows available passkeys
|
|
2. **Biometric Prompt**: Browser authenticates with passkey
|
|
3. **Session Creation**: Secure session established
|
|
4. **Redirect**: User directed to dashboard
|
|
|
|
### Security Settings
|
|
|
|
Users can manage their security through the Settings > Security page:
|
|
|
|
- **Device Management**: View, add, remove, and label passkeys
|
|
- **Recovery Codes**: Generate new recovery codes
|
|
- **Password Options**: Add or remove password fallback
|
|
- **Account Recovery**: Secure account recovery options
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **WebAuthn Not Supported**: Use a modern browser (Chrome, Firefox, Safari, Edge)
|
|
2. **HTTPS Required**: WebAuthn requires HTTPS in production environments
|
|
3. **Device Compatibility**: Ensure devices support FIDO2/WebAuthn
|
|
4. **Database Connection**: Verify database connection and migrations
|
|
|
|
### Bootstrap Issues
|
|
|
|
1. **Permission Denied**: Ensure proper file permissions on bootstrap binary
|
|
2. **Database Connection**: Check DATABASE_URL configuration
|
|
3. **Port Conflicts**: Ensure database port is accessible
|
|
|
|
### Recovery Process
|
|
|
|
If a user loses access to all passkeys:
|
|
|
|
1. **Use Recovery Code**: Enter one of the 10 recovery codes
|
|
2. **Contact Admin**: Admins can assist with account recovery
|
|
3. **Re-register Passkey**: Set up new passkeys after recovery
|
|
4. **Generate New Recovery Codes**: Replace used recovery codes
|
|
|
|
## Monitoring and Maintenance
|
|
|
|
### Key Metrics
|
|
|
|
Monitor these metrics for system health:
|
|
|
|
- Authentication success/failure rates
|
|
- Passkey registration and usage patterns
|
|
- Recovery code usage frequency
|
|
- Admin action audit logs
|
|
- Session expiration and renewal rates
|
|
|
|
### Maintenance Tasks
|
|
|
|
Regular maintenance includes:
|
|
|
|
- Clean up expired sessions and recovery codes
|
|
- Review audit logs for suspicious activity
|
|
- Update role assignments as needed
|
|
- Monitor WebAuthn compatibility with browser updates
|
|
|
|
## Support and Documentation
|
|
|
|
For additional support:
|
|
|
|
- **Technical Issues**: Check application logs and database status
|
|
- **Security Concerns**: Review audit logs and user activity
|
|
- **Feature Requests**: Follow the contribution guidelines
|
|
- **Documentation Updates**: Keep this document current with system changes
|
|
|
|
---
|
|
|
|
**Last Updated**: January 2026
|
|
**Version**: 1.0
|
|
**Compatibility**: WebAuthn Level 2, FIDO2 |