PFVCluster/docs/TSYS-2FA-GUIDE.md

TSYS Two-Factor Authentication Implementation Guide

Overview

This guide provides complete instructions for implementing and managing two-factor authentication (2FA) on TSYS servers using Google Authenticator (TOTP).

What This Implementation Provides

Services Protected by 2FA

• SSH Access: Requires SSH key + 2FA token
• Cockpit Web Interface: Requires password + 2FA token
• Webmin Administration: Requires password + 2FA token (if installed)

Security Features

• Time-based One-Time Passwords (TOTP): Standard 6-digit codes
• Backup Codes: Emergency access codes
• Gradual Rollout: Optional nullok mode for phased deployment
• Configuration Backup: Automatic backup of all configs

Implementation Steps

Step 1: Run the 2FA Setup Script

# Navigate to the security modules directory
cd provisioning/Modules/Security

# Run the 2FA setup script as root
sudo bash secharden-2fa.sh

Step 2: Validate Installation

# Run 2FA validation tests
./Project-Tests/security/2fa-validation.sh

# Run specific 2FA security test
./Project-Tests/run-tests.sh security

Step 3: Setup Individual Users

For each user that needs 2FA access:

# Check setup instructions
cat /home/username/2fa-setup-instructions.txt

# Run user setup script
sudo /tmp/setup-2fa-username.sh

Step 4: Test 2FA Access

1. Test SSH access from another terminal
2. Test Cockpit access via web browser
3. Test Webmin access if installed

User Setup Process

Installing Authenticator Apps

Users need one of these apps on their phone:

• Google Authenticator (Android/iOS)
• Authy (Android/iOS)
• Microsoft Authenticator (Android/iOS)
• 1Password (with TOTP support)

Setting Up 2FA for a User

1. Run setup script:

   sudo /tmp/setup-2fa-username.sh
   

2. Follow prompts:

   • Answer "y" to update time-based token
   • Scan QR code with authenticator app
   • Save emergency backup codes securely
   • Answer "y" to remaining security questions

3. Test immediately:

   # Test SSH from another terminal
   ssh username@server-ip
   # You'll be prompted for 6-digit code
   

Configuration Details

SSH Configuration Changes

File: /etc/ssh/sshd_config

ChallengeResponseAuthentication yes
UsePAM yes
AuthenticationMethods publickey,keyboard-interactive

PAM Configuration

File: /etc/pam.d/sshd

auth required pam_google_authenticator.so nullok

Cockpit Configuration

File: /etc/cockpit/cockpit.conf

[WebService]
LoginTitle = TSYS Server Management
LoginTo = 300
RequireHost = true

[Session]
Banner = /etc/cockpit/issue.cockpit
IdleTimeout = 15

Webmin Configuration

File: /etc/webmin/miniserv.conf

twofactor_provider=totp
twofactor=1

Security Considerations

Gradual vs Strict Enforcement

Gradual Enforcement (Default)

• Uses nullok option in PAM
• Users without 2FA can still log in
• Allows phased rollout
• Good for initial deployment

Strict Enforcement

• Remove nullok from PAM configuration
• All users must have 2FA configured
• Immediate security enforcement
• Risk of lockout if misconfigured

Backup and Recovery

Emergency Access

• Backup codes: Generated during setup
• Root access: Can disable 2FA if needed
• Console access: Physical/virtual console bypasses SSH

Configuration Backup

• Automatic backup to /root/backup/2fa-TIMESTAMP/
• Includes all modified configuration files
• Can be restored if needed

Troubleshooting

Common Issues

1. User Cannot Generate QR Code

# Ensure qrencode is installed
sudo apt-get install qrencode

# Re-run user setup
sudo /tmp/setup-2fa-username.sh

2. SSH Connection Fails

# Check SSH service status
sudo systemctl status sshd

# Test SSH configuration
sudo sshd -t

# Check logs
sudo journalctl -u sshd -f

3. 2FA Code Not Accepted

• Check time synchronization on server and phone
• Verify app setup - rescan QR code if needed
• Try backup codes if available

4. Locked Out of Server

# Access via console (physical/virtual)
# Disable 2FA temporarily
sudo cp /root/backup/2fa-*/pam.d.bak/sshd /etc/pam.d/sshd
sudo systemctl restart sshd

Debug Commands

# Check 2FA status
./Project-Tests/security/2fa-validation.sh

# Check SSH configuration
sudo sshd -T | grep -E "(Challenge|PAM|Authentication)"

# Check PAM configuration
cat /etc/pam.d/sshd | grep google-authenticator

# Check user 2FA status
ls -la ~/.google_authenticator

Management and Maintenance

Adding New Users

1. Ensure user account exists
2. Run setup script for new user
3. Provide setup instructions
4. Test access

Removing User 2FA

# Remove user's 2FA configuration
sudo rm /home/username/.google_authenticator

# User will need to re-setup 2FA

Disabling 2FA System-Wide

# Restore original configurations
sudo cp /root/backup/2fa-*/sshd_config.bak /etc/ssh/sshd_config
sudo cp /root/backup/2fa-*/pam.d.bak/sshd /etc/pam.d/sshd
sudo systemctl restart sshd

Updating 2FA Configuration

# Re-run setup script
sudo bash secharden-2fa.sh

# Validate changes
./Project-Tests/security/2fa-validation.sh

Best Practices

Deployment Strategy

1. Test in non-production environment first
2. Enable gradual rollout (nullok) initially
3. Train users on 2FA setup process
4. Test emergency procedures before strict enforcement
5. Monitor logs for authentication issues

Security Recommendations

• Enforce strict mode after successful rollout
• Regular backup code rotation
• Monitor failed authentication attempts
• Document emergency procedures
• Regular security audits

User Training

• Provide clear instructions
• Demonstrate setup process
• Explain backup code importance
• Test login process with users
• Establish support procedures

Monitoring and Logging

Authentication Logs

# SSH authentication logs
sudo journalctl -u sshd | grep -i "authentication"

# PAM authentication logs
sudo journalctl | grep -i "pam_google_authenticator"

# Failed login attempts
sudo journalctl | grep -i "failed"

Security Monitoring

• Monitor for repeated failed 2FA attempts
• Alert on successful logins without 2FA (during gradual rollout)
• Track user 2FA setup completion
• Monitor for emergency access usage

Integration with Existing Systems

LDAP/Active Directory

• 2FA works with existing authentication systems
• Users still need local 2FA setup
• Consider centralized 2FA solutions for large deployments

Monitoring Systems

• LibreNMS: Will continue to work with SNMP
• Wazuh: Will log 2FA authentication events
• Cockpit: Enhanced with 2FA protection

Backup Systems

• Ensure backup procedures account for 2FA
• Test restore procedures with 2FA enabled
• Document emergency access procedures

Support and Resources

Files Created by Setup

• /tmp/setup-2fa-*.sh - User setup scripts
• /home/*/2fa-setup-instructions.txt - User instructions
• /root/backup/2fa-*/ - Configuration backups

Validation Tools

• ./Project-Tests/security/2fa-validation.sh - Complete 2FA validation
• ./Project-Tests/run-tests.sh security - Security test suite

Emergency Contacts

• System Administrator: [Contact Info]
• Security Team: [Contact Info]
• 24/7 Support: [Contact Info]

Compliance and Audit

Security Benefits

• Significantly reduces risk of unauthorized access
• Meets multi-factor authentication requirements
• Provides audit trail of authentication events
• Complies with security frameworks (NIST, ISO 27001)

Audit Trail

• All authentication attempts logged
• 2FA setup events recorded
• Configuration changes tracked
• Emergency access documented

---

Last Updated: July 14, 2025
Version: 1.0
Author: TSYS Security Team