Skip to content

Authentication Methods

Configure how administrators and users authenticate to Mailborder, including passwords, two-factor authentication, and passwordless passkeys.

Overview

Mailborder V6 supports multiple authentication methods:

  1. Password Authentication - Traditional username/password
  2. TOTP 2FA - Time-based One-Time Passwords (Google Authenticator, Authy)
  3. Passkey/WebAuthn - Passwordless authentication with biometrics or security keys
  4. LDAP/Active Directory - Enterprise directory integration
  5. SSO - Single Sign-On (future)

Password Authentication

Password Policy

Configure password requirements for security.

Via Web Interface: System Settings → Security → Password Policy

Via Command Line:

# Minimum length
sudo mb-config set auth.password.min_length 12

# Require complexity
sudo mb-config set auth.password.require_uppercase true
sudo mb-config set auth.password.require_lowercase true
sudo mb-config set auth.password.require_number true
sudo mb-config set auth.password.require_special true

# Password expiration
sudo mb-config set auth.password.expiry_days 90

# Password history
sudo mb-config set auth.password.remember_count 5

# Maximum age before forced change
sudo mb-config set auth.password.max_age_days 180

Complexity Example:

With all complexity rules enabled, valid passwords: - MySecure2025!Pass - C0mplex#Passw0rd - Str0ng&P@ssword!

Invalid passwords: - password - no uppercase, no number, no special - Password123 - no special character - P@ss - too short

Password Hashing

Mailborder uses Argon2id for password hashing (industry best practice).

Algorithm: Argon2id Work Factor: Tunable for security vs performance

# Adjust work factor (higher = more secure but slower)
sudo mb-config set auth.password.argon2_memory 65536  # 64 MB
sudo mb-config set auth.password.argon2_time 3        # iterations
sudo mb-config set auth.password.argon2_parallelism 4 # threads

Legacy Password Upgrade:

Mailborder automatically upgrades legacy MD5+salt passwords to Argon2id on next successful login.

Change Password

Via Web Interface: Profile Menu → My Account → Change Password

Via Command Line:

# Change your own password (interactive)
sudo mb-admin-password

# Reset another user's password
sudo mb-admin-reset --email user@example.com

Force Password Change:

# Require password change on next login
sudo mb-admin-expire-password --email user@example.com

Two-Factor Authentication (2FA)

Add extra security layer with time-based one-time passwords.

Enable 2FA for User

Via Web Interface:

  1. Log in
  2. Navigate to Profile Menu → My Account → Security
  3. Click "Enable Two-Factor Authentication"
  4. Scan QR code with authenticator app
  5. Enter verification code
  6. Save backup codes

Via Command Line:

# Generate 2FA secret for user
sudo mb-2fa-enable --email admin@example.com

Outputs: - QR code (scan with app) - Secret key (manual entry) - Backup codes (save securely)

Supported Authenticator Apps

Free Apps: - Google Authenticator (iOS, Android) - Microsoft Authenticator (iOS, Android) - Authy (iOS, Android, Desktop) - 1Password (with TOTP support) - Bitwarden (with TOTP support)

Requirements: - Time-synchronized (critical!) - TOTP algorithm (Time-based OTP) - 30-second time step - 6-digit codes

Verify 2FA Code

After enabling, test code:

sudo mb-2fa-verify --email admin@example.com --code 123456

Disable 2FA

Via Web Interface: Profile Menu → My Account → Security → Disable 2FA

Via Command Line (Emergency):

# Disable if locked out
sudo mb-2fa-disable --email admin@example.com --force

Require 2FA

Force all administrators to use 2FA:

# Require for all admins
sudo mb-config set auth.require_2fa true

# Grace period (days until enforcement)
sudo mb-config set auth.2fa_grace_period 30

Users without 2FA are prompted to enable on next login.

Backup Codes

One-time recovery codes if device lost.

Generate Backup Codes:

sudo mb-2fa-backup-codes --email admin@example.com

Generates 10 single-use codes: 

1. ABC123-DEF456-GHI789
2. JKL012-MNO345-PQR678
3. STU901-VWX234-YZA567
...

Use Backup Code:

Enter backup code instead of TOTP when logging in. Code is consumed and cannot be reused.

Regenerate Codes:

# Invalidate old codes and generate new
sudo mb-2fa-backup-codes --email admin@example.com --regenerate

2FA Troubleshooting

Code Always Invalid:

Cause: Time synchronization issue

Solution: 

# On server
sudo timedatectl status
sudo timedatectl set-ntp true

# On phone
Check Settings → Date & Time → Automatic

Lost Authenticator Device:

Solution: 

# Use backup code to login
# Or admin can disable 2FA:
sudo mb-2fa-disable --email user@example.com --force

Code Accepted But Login Fails:

Cause: Session or cache issue

Solution: 

# Clear sessions
sudo redis-cli FLUSHDB

# Restart services
sudo systemctl restart mb-rpcd

Passkey / WebAuthn Authentication

Passwordless authentication using biometrics or security keys.

What Are Passkeys?

Passkeys use public-key cryptography for authentication:

  • No password - Nothing to remember or steal
  • Phishing-resistant - Can't be used on wrong site
  • Biometric - Fingerprint, Face ID, Windows Hello
  • Hardware keys - YubiKey, Titan Security Key
  • Platform authenticators - Built into device

Enable Passkey Support

System-wide:

sudo mb-config set auth.passkey.enabled true

Requirements: - HTTPS (required by WebAuthn spec) - Modern browser: - Chrome 90+ - Firefox 88+ - Safari 14+ - Edge 90+

Register Passkey

Via Web Interface:

  1. Log in with password
  2. Navigate to Profile Menu → My Account → Security
  3. Click "Add Passkey"
  4. Follow browser prompts:
  5. Touch fingerprint sensor
  6. Scan face
  7. Insert security key
  8. Use Windows Hello
  9. Name your passkey (e.g., "iPhone", "YubiKey")

Passkey Types:

Platform Authenticators: - Touch ID (Mac) - Face ID (iPhone, iPad) - Windows Hello - Android biometrics

Roaming Authenticators: - YubiKey - Titan Security Key - Feitian devices - Other FIDO2 keys

Login with Passkey

After registration:

  1. Navigate to login page
  2. Enter email/username
  3. Click "Continue"
  4. Browser prompts for passkey
  5. Authenticate (fingerprint, face, security key)
  6. Logged in!

No password needed!

Manage Passkeys

List User's Passkeys:

sudo mb-passkey-list --email admin@example.com

Output: 

Credential ID          Name         Device Type    Last Used
abc123def456...        iPhone       platform       2025-01-15
789ghi012jkl...        YubiKey      cross-platform 2025-01-14

Remove Passkey:

Via Web Interface: Profile Menu → My Account → Security → Remove next to passkey

Via Command Line: 

sudo mb-passkey-remove --email admin@example.com --credential-id abc123def456

Rename Passkey:

sudo mb-passkey-rename --email admin@example.com --credential-id abc123def456 --name "Work iPhone"

Passkey Configuration

Attestation:

# Require attestation (verify hardware authenticity)
sudo mb-config set auth.passkey.attestation required

# Or don't require (more compatible)
sudo mb-config set auth.passkey.attestation none

User Verification:

# Require user verification (PIN, biometric)
sudo mb-config set auth.passkey.user_verification required

# Or discouraged (less secure but more compatible)
sudo mb-config set auth.passkey.user_verification preferred

Authenticator Attachment:

# Allow any authenticator type
sudo mb-config set auth.passkey.authenticator_attachment any

# Platform authenticators only (built-in)
sudo mb-config set auth.passkey.authenticator_attachment platform

# Cross-platform only (removable keys)
sudo mb-config set auth.passkey.authenticator_attachment cross-platform

Passkey Backup and Sync

Apple Devices: - Passkeys sync via iCloud Keychain - Available on all your Apple devices

Google Devices: - Passkeys sync via Google Password Manager - Available on all your Android devices

Security Keys: - Hardware keys don't sync - Must register each key separately

Passkey Troubleshooting

Browser Doesn't Prompt:

Cause: Browser doesn't support WebAuthn

Solution: Update browser to latest version

"Not Allowed" Error:

Causes: - Not HTTPS - User cancelled - Timeout

Solution: Ensure HTTPS, try again

Passkey Doesn't Work After Setup:

Cause: Credential ID mismatch or database issue

Solution: 

# Check database
sudo mysql mailborder -e "SELECT * FROM users_admin_credentials WHERE userId = 1;"

# Re-register passkey

LDAP / Active Directory Integration

Authenticate users against enterprise directory.

Enable LDAP Authentication

sudo mb-config set auth.ldap.enabled true
sudo mb-config set auth.ldap.server "ldap.example.com"
sudo mb-config set auth.ldap.port 389
sudo mb-config set auth.ldap.use_tls true

LDAP Configuration

Base DN: 

sudo mb-config set auth.ldap.base_dn "dc=example,dc=com"

Bind DN (for searches): 

sudo mb-config set auth.ldap.bind_dn "cn=mailborder,ou=services,dc=example,dc=com"
sudo mb-config set auth.ldap.bind_password "SecureBindPassword"

User Filter: 

# Search filter to find users
sudo mb-config set auth.ldap.user_filter "(uid=%s)"

# For Active Directory
sudo mb-config set auth.ldap.user_filter "(sAMAccountName=%s)"

# Search by email
sudo mb-config set auth.ldap.user_filter "(mail=%s)"

Group Filter (Optional):

Only allow specific groups:

sudo mb-config set auth.ldap.group_filter "(memberOf=cn=mailborder-admins,ou=groups,dc=example,dc=com)"

LDAP Connection Security

STARTTLS: 

sudo mb-config set auth.ldap.use_tls true
sudo mb-config set auth.ldap.port 389

LDAPS (TLS from start): 

sudo mb-config set auth.ldap.use_ssl true
sudo mb-config set auth.ldap.port 636

Certificate Verification: 

# Verify server certificate (recommended)
sudo mb-config set auth.ldap.verify_cert true

# Or skip verification (for self-signed certs)
sudo mb-config set auth.ldap.verify_cert false

Test LDAP Connection

# Test LDAP configuration
sudo mb-test-ldap --username john.doe

# With verbose output
sudo mb-test-ldap --username john.doe --verbose

Expected output: 

[OK] Connected to ldap.example.com:389
[OK] TLS negotiation successful
[OK] Bind successful
[OK] User found: cn=John Doe,ou=users,dc=example,dc=com
[OK] Group membership verified
[OK] Authentication successful

LDAP authentication working correctly!

LDAP Sync

Sync user accounts from LDAP:

# Import all users
sudo mb-ldap-sync

# Dry run (show what would be imported)
sudo mb-ldap-sync --dry-run

# Sync specific group
sudo mb-ldap-sync --group "cn=mailborder-admins,ou=groups,dc=example,dc=com"

LDAP Attribute Mapping

Map LDAP attributes to Mailborder fields:

sudo mb-config set auth.ldap.attr.username "uid"
sudo mb-config set auth.ldap.attr.email "mail"
sudo mb-config set auth.ldap.attr.firstname "givenName"
sudo mb-config set auth.ldap.attr.lastname "sn"
sudo mb-config set auth.ldap.attr.phone "telephoneNumber"

Active Directory Specific

For Microsoft Active Directory:

sudo mb-config set auth.ldap.server "dc01.example.com"
sudo mb-config set auth.ldap.port 389
sudo mb-config set auth.ldap.use_tls true
sudo mb-config set auth.ldap.base_dn "dc=example,dc=com"
sudo mb-config set auth.ldap.user_filter "(sAMAccountName=%s)"
sudo mb-config set auth.ldap.bind_dn "mailborder@example.com"
sudo mb-config set auth.ldap.attr.username "sAMAccountName"
sudo mb-config set auth.ldap.attr.email "mail"

Session Management

Session Settings

Session Timeout:

# Inactivity timeout (seconds)
sudo mb-config set auth.session.timeout 1800  # 30 minutes

# Maximum session duration (seconds)
sudo mb-config set auth.session.max_duration 28800  # 8 hours

Session Storage:

# Use Redis for sessions (recommended for clustering)
sudo mb-config set auth.session.storage redis

# Or use PHP file-based sessions (default)
sudo mb-config set auth.session.storage files

Session Security:

# Regenerate session ID on login
sudo mb-config set auth.session.regenerate_on_login true

# Bind session to IP address
sudo mb-config set auth.session.bind_to_ip true

# Bind session to User-Agent
sudo mb-config set auth.session.bind_to_ua true

Trusted Devices

"Remember Me" functionality using secure cookies.

Enable: 

sudo mb-config set auth.trusted_devices.enabled true

# Cookie expiration (seconds)
sudo mb-config set auth.trusted_devices.duration 2592000  # 30 days

List User's Trusted Devices:

sudo mb-trusted-devices-list --email admin@example.com

Revoke Trusted Device:

Via Web Interface: Profile Menu → My Account → Security → Trusted Devices

Via Command Line: 

sudo mb-trusted-devices-revoke --email admin@example.com --device-id abc123

Account Lockout

Prevent brute-force attacks.

Enable Account Lockout

# Enable lockout
sudo mb-config set auth.lockout.enabled true

# Failed attempts before lockout
sudo mb-config set auth.lockout.max_attempts 5

# Lockout duration (seconds)
sudo mb-config set auth.lockout.duration 900  # 15 minutes

# Reset counter after successful login
sudo mb-config set auth.lockout.reset_on_success true

Unlock Account

Automatic: After lockout duration expires

Manual: 

sudo mb-admin-unlock --email user@example.com

View Locked Accounts: 

sudo mb-admin-list --locked

IP Whitelisting

Restrict admin access to specific IP addresses.

Enable IP Restriction

sudo mb-config set auth.ip_restrict.enabled true

Add Allowed IP

# Single IP
sudo mb-ip-whitelist add 203.0.113.10

# CIDR range
sudo mb-ip-whitelist add 203.0.113.0/24

# IP range
sudo mb-ip-whitelist add 203.0.113.10-203.0.113.20

List Allowed IPs

sudo mb-ip-whitelist list

Remove IP

sudo mb-ip-whitelist remove 203.0.113.10

Per-User IP Restrictions

Different IPs for different users:

sudo mb-ip-restrict --email admin@example.com --add 203.0.113.10
sudo mb-ip-restrict --email remote-admin@example.com --add 198.51.100.50

Audit Logging

Track authentication events.

Enable Auth Logging

sudo mb-config set auth.audit.enabled true

# Log level (info, warning, error)
sudo mb-config set auth.audit.level info

# Retention (days)
sudo mb-config set auth.audit.retention 180

View Auth Logs

# Recent logins
sudo mb-audit-log --type login --recent

# Failed logins
sudo mb-audit-log --type failed-login --since "24 hours ago"

# By user
sudo mb-audit-log --user admin@example.com --since "7 days ago"

# Export to CSV
sudo mb-audit-log --export csv > auth-log.csv

Log Events

Logged events: - Successful login - Failed login - Account lockout - Password change - 2FA enable/disable - Passkey register/remove - Session created/destroyed - Trusted device added/removed

API Authentication

For programmatic access.

API Key Authentication

Generate API Key:

sudo mb-api-key-generate --email admin@example.com --name "Monitoring Script"

Returns: 

API Key: mbv6_abc123def456ghi789jkl012mno345pqr678
Secret:  s_xyz789uvw456rst123opq098lmn765kji432

Store these securely! Secret cannot be retrieved again.

Use API Key:

curl -H "X-API-Key: mbv6_abc123..." -H "X-API-Secret: s_xyz789..." \
  https://mailborder.example.com/api/v1/stats

List API Keys:

sudo mb-api-key-list --email admin@example.com

Revoke API Key:

sudo mb-api-key-revoke --key mbv6_abc123def456ghi789jkl012mno345pqr678

Next Steps