Authentication System - Manager Overview
What is the Authentication System?
The MBPanel authentication system is the security foundation that controls who can access the platform and what they can do.
Key Capabilities
| Capability |
Description |
| User Registration |
Two paths: create new team (Door A) or join existing (Door B) |
| Multi-Tenancy |
Users belong to teams; access is scoped to team membership |
| Role-Based Access Control |
Flexible permission system with predefined and custom roles |
| Session Management |
Single active session per user with configurable timeouts |
| Device Security |
New device approval via email OTP |
| Suspicious Login Detection |
Geo-IP based alerts with approve/deny workflow |
| Email Workflows |
Verification, password reset, team invitations |
User Journey
New User Registration (Door A)
┌──────────────┐
│ 1. Sign Up │ User provides email, password, name
└──────┬───────┘
│
▼
┌──────────────┐
│ 2. Email │ Verification email sent
└──────┬───────┘
│
▼
┌──────────────┐
│ 3. Verify │ User clicks email link
└──────┬───────┘
│
▼
┌──────────────┐
│ 4. Login │ Two-step: credentials → team selection
└──────┬───────┘
│
▼
┌──────────────┐
│ 5. Access │ User can now access team resources
└──────────────┘
Team Invitation (Door B)
┌──────────────┐
│ 1. Invite │ Owner sends invitation email
└──────┬───────┘
│
▼
┌──────────────┐
│ 2. Register │ User creates account via invite link
└──────┬───────┘
│
▼
┌──────────────┐
│ 3. Access │ User joins team with assigned role
└──────────────┘
Security Features
Account Security
| Feature |
Purpose |
Status |
| Bcrypt Password Hashing |
Secure password storage |
✅ Implemented |
| Email Verification |
Prevent fake accounts |
✅ Implemented |
| Password Reset |
Self-service recovery |
✅ Implemented |
| Device Approval OTP |
Prevent unauthorized device access |
✅ Implemented |
| Suspicious Login Detection |
Alert on unusual access patterns |
✅ Implemented |
| Concurrent Login Control |
Single active session per user |
✅ Implemented |
Session Security
| Feature |
Purpose |
| Access Token (6 hour TTL) |
Short-lived stateless tokens |
| Refresh Token (7 day/1 day TTL) |
Longer-lived session renewal |
| Idle Timeout (60 min default) |
Auto-logout on inactivity |
| Token Blacklisting |
Immediate logout capability |
| CSRF Protection |
Prevent cross-site request forgery |
Compliance & Audit
| Feature |
Purpose |
| Login Activity Logging |
Audit trail of all access |
| Trusted Device Tracking |
Device history for security review |
| Session Revocation |
Admin can terminate sessions |
| Permission Audit |
Track who has what access |
Roles & Permissions
Default Roles
| Role |
Description |
Permissions |
| Owner |
Full control, including billing |
Wildcard (*) - all permissions |
| Manager |
Team management, no billing |
Team management, resource access |
| Developer |
Resource access only |
Create/edit resources within team |
Permission Categories
| Category |
Example Permissions |
| Team |
team.manage, team.invite, team.view |
| Sites |
site.create, site.edit, site.delete |
| Environments |
env.create, env.deploy, env.delete |
| Backups |
backup.create, backup.restore |
| Servers |
server.create, server.manage |
| Users |
user.manage |
| Billing |
billing.manage |
| System |
events.read, system.admin |
Operational Metrics
Key Metrics to Monitor
| Metric |
Description |
Target |
| Login Success Rate |
% of successful logins |
> 95% |
| Session Expiry Rate |
% of sessions that expire naturally |
> 80% |
| Device Approval Rate |
% of devices auto-approved vs. OTP |
Track trend |
| Suspicious Login Rate |
% of logins flagged as suspicious |
< 5% |
| Password Reset Rate |
% of users using password reset |
Track trend |
| Average Session Duration |
Time between login and logout |
Track usage |
Alerting Thresholds
| Metric |
Warning Threshold |
Critical Threshold |
| Failed login rate (per IP) |
> 10/hour |
> 20/hour |
| Suspicious login rate |
> 5% of logins |
> 10% of logins |
| Session errors |
> 1% of refreshes |
> 5% of refreshes |
| Email send failures |
> 5% |
> 10% |
Integration Points
External Services
| Service |
Purpose |
Criticality |
| Postmark |
Transactional emails |
High - OTP, alerts, verification |
| Virtuozzo |
Infrastructure API |
High - session management |
| Geo-IP API |
Suspicious login detection |
Medium - can degrade gracefully |
| Redis |
Session state, rate limiting |
High - required for auth |
| PostgreSQL |
User data, sessions |
High - required for auth |
Failure Modes
| Scenario |
Impact |
Mitigation |
| Postmark Down |
OTP emails delayed/sent |
Queue emails, retry with backoff |
| Redis Down |
Cannot issue new sessions |
Return 503, use circuit breaker |
| Geo-IP API Down |
No suspicious login detection |
Auto-approve login, log degradation |
| Virtuozzo Down |
Cannot refresh VZ sessions |
Use cached key, notify Owner |
Questions?
- How do I reset a user's password? Users can self-service via password reset. Admins can force password change through user management.
- How do I revoke a user's session? Set
revoked_at on the ActiveSession record. All tokens will be invalidated.
- How do I add a new permission? Seed the permission in the database, then assign to roles via the role management interface.
- What happens if Redis goes down? New sessions cannot be issued. Existing sessions may work until expiry. Return 503 with clear error.