KNEL/PFVCluster
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: migrate all documentation to Discourse wiki topics

Browse Source 
All knowledge docs (architecture, runbooks, references, audits, policies)
have been migrated to community.turnsys.com as wiki topics in the VP
TechOps category. Discourse is now the canonical source of truth for
documentation; git edit history no longer serves as the doc changelog.

37 .md files converted to short pointers linking to their Discourse
topics. AGENTS.md updated with new documentation workflow policy.
Code (scripts, configs, playbooks) remains authoritative in git.
This commit is contained in:
reachableceo
2026-08-06 14:08:34 -05:00
parent d6988bb35f
commit 88faf35ec3
37 changed files with 378 additions and 8239 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/server-build/TSYS-2FA-GUIDE.md
+10 -329
View File
@@ -1,329 +1,10 @@
# 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
```bash
# 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
```bash
# 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:
```bash
# 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:**
```bash
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:**
```bash
# 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
```bash
# Ensure qrencode is installed
sudo apt-get install qrencode
# Re-run user setup
sudo /tmp/setup-2fa-username.sh
```
#### 2. SSH Connection Fails
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Remove user's 2FA configuration
sudo rm /home/username/.google_authenticator
# User will need to re-setup 2FA
```
### Disabling 2FA System-Wide
```bash
# 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
```bash
# 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
```bash
# 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
# docs/server-build/TSYS-2FA-GUIDE.md
> **Documentation moved to Discourse — the canonical source of truth.**
>
> **End-user guide for 2FA setup**
>
> **Read it here:** https://community.turnsys.com/t/303
>
> *Migrated 2026-08-06. This file is kept as a pointer for git-browsing context.
> Do not update content here — edit the Discourse wiki topic instead.*