OTP Management
Configure and maintain the one-time password authentication system
The OTP (One-Time Password) authentication system provides passwordless login across all user types. This guide covers how the system works, security features, and maintenance tasks for administrators.
How OTP Authentication Works
When users sign in with a verification code:
- User enters their email address
- System generates a secure 6-digit code
- Code is sent via email
- User enters the code to verify identity
- System validates and creates authenticated session
Codes are single-use, time-limited, and cryptographically secure.
Security Features
Code Generation
Cryptographically secure: Codes are generated using secure random number generation, not predictable patterns.
Weak pattern exclusion: The system never generates easily-guessed codes like:
- Sequential: 123456, 654321
- Repeated: 111111, 222222, 333333
- Common: 000000, 999999
Hashed storage: Codes are hashed before storage. Plain-text codes are never saved in the database.
Rate Limiting
Request limits: Maximum 5 OTP requests per email per 5 minutes.
Resend cooldown: 60-second wait between resend requests.
Purpose: Prevents abuse and spam attacks.
Attempt Limits
Maximum attempts: 5 verification attempts per code.
Auto-lock: After 5 failed attempts, the code locks and cannot be used.
User action: User must request a new code to try again.
Time Limits
Code expiration: 10 minutes from generation.
Session tokens: Profile verification tokens expire after 10 minutes.
Purpose: Limits the window for potential attacks.
OTP Use Cases
The system uses OTP codes for:
Login Authentication
- All user types (Customers, Staff, Partners, Administrators)
- Alternative to password login
- Primary method for passwordless accounts
Registration Verification
- Customer registration email verification
- Partner registration email verification (when enabled)
- Ensures valid email addresses
Profile Updates
- Required for all profile changes
- Verifies user identity before saving
- Replaces "enter current password" verification
Database Storage
OTP codes are stored in the otp_codes table with:
Security tracking:
- Hashed code (not plain text)
- IP address of request
- User agent (browser/device)
- Attempt counter
Metadata:
- Purpose (login, registration, profile_update)
- Guard (member, staff, partner, admin)
- Expiration timestamp
- Verification status
Retention: Verified and expired codes are cleaned up automatically.
Maintenance Commands
Automatic Cleanup
The system includes a scheduled command to remove old OTP codes:
php artisan otp:cleanup
What it does:
- Removes verified codes older than 24 hours
- Removes expired codes older than 24 hours
- Keeps recent codes for security logging
Schedule: Should run hourly via cron/scheduler.
Add to scheduler:
// In app/Console/Kernel.php
$schedule->command('otp:cleanup')->hourly();
Manual Cleanup
To manually clean up OTP codes:
php artisan otp:cleanup
Run this if:
- The scheduled task isn't running
- You need to free database space immediately
- You're troubleshooting OTP issues
Monitoring OTP Activity
Activity Logs
All OTP events are logged in the activity log system:
- OTP code generation
- Successful verifications
- Failed verification attempts
- Rate limit violations
To view OTP activity:
- Navigate to Activity Logs
- Filter by category: "authentication"
- Look for OTP-related events
Security Monitoring
Watch for:
High failure rates: Many failed OTP verifications may indicate:
- User confusion (provide better instructions)
- Attack attempts (investigate IP addresses)
Rate limit hits: Frequent rate limiting may indicate:
- Spam/abuse attempts
- Email delivery issues causing repeated requests
Unusual patterns: Multiple OTP requests from same IP for different emails may indicate:
- Automated attacks
- Need for additional security measures
Configuration
OTP settings are configured in the application code:
| Setting | Value | Notes |
|---|---|---|
| Code length | 6 digits | Standard |
| Expiration time | 10 minutes | Security requirement |
| Maximum attempts | 5 per code | Prevents brute force |
| Rate limit | 5 requests per 5 minutes | Prevents spam |
| Resend cooldown | 60 seconds | Prevents abuse |
These are security-critical values and should not be changed without careful consideration.
Email Delivery
OTP codes are sent via the configured email system. Ensure:
SMTP is configured: Check email settings in administration.
Email queue is running: If using queues, ensure workers are active.
Delivery is reliable: Test email delivery regularly.
Spam filters: Verify OTP emails aren't being filtered.
Troubleshooting
Users Not Receiving Codes
Check email configuration: Verify SMTP settings are correct.
Check queue workers: If using queues, ensure they're running.
Check spam folders: Advise users to check spam/junk.
High Failure Rates
Review activity logs: Check for patterns in failed attempts.
Check code expiration: Ensure 10-minute window is sufficient.
Verify email delivery speed: Slow delivery may cause expiration.
Database Growth
Run cleanup command: Execute php artisan otp:cleanup
Verify scheduler is running: Check that Laravel scheduler runs every minute.
Best Practices
Run cleanup hourly: Keep the OTP table size manageable.
Monitor activity logs: Watch for suspicious patterns.
Test email delivery: Regularly verify OTP emails arrive promptly.
Educate users: Provide clear instructions on using OTP codes.
Secure email system: Ensure SMTP credentials are protected.
Related Topics
- Authentication Overview — All authentication options
- Passwordless Login — User login guide
- Activity Logs — Monitor OTP usage
- Security Monitoring — Detect suspicious activity