Skip to main content

Linux Integration

SecTrail MFA adds multi-factor authentication to SSH, Sudo, Su, and Console access on Linux operating systems.

Supported Services​

The SecTrail MFA PAM module can enable MFA for the following services. You can select only the services where you want to enforce MFA:

🐧 SSH (Secure Shell)​

  • MFA for remote SSH connections
  • Combination with key-based authentication
  • MFA for SFTP, SCP access

👤 Console Login​

  • MFA for physical terminal logins
  • TTY console protection
  • KVM access control

⚙️ Sudo (Privilege Escalation)​

  • Add MFA to sudo commands
  • Additional security for root access
  • MFA requirement for critical commands

🔐 Su (Switch User)​

  • MFA when switching users with su command
  • Additional security when switching to root user
SERVICE SELECTION

During installation, you can choose which services will have MFA enabled. You can enforce MFA on all services or only on selected services (e.g., only SSH and sudo).

Configuration Steps​

SecTrail MFA Side​

  1. API Client: Create an Agent-type API client for API credentials required during PAM module installation
  2. Application Profile: Create an API-type application profile for Linux PAM factor configuration
  3. Authentication Methods: Add desired authentication methods (Push, SMS OTP, Soft OTP, etc.) to the application profile

Linux Side​

Install SecTrail MFA Pluggable Authentication Module (PAM) on the Linux system. This module adds MFA to SSH, Sudo, and Console access.

PAM Module Installation Wizard​

SecTrail MFA provides an interactive installation script. For installation:

# Run the installation script
sudo ./sectrail-mfa-installer-multi.sh
1. Installation Start​

When the script runs, system information is automatically detected:

SecTrail MFA PAM Installation Wizard
Multi-Platform Standalone Installer

System Information:
  OS: Linux
  Architecture: x86_64
  PAM library directory: /usr/lib64/security

✓ Files extracted
✓ Detected platform: linux-x86_64
✓ Found binary for your platform
✓ All required files present
2. API Server Configuration​

Enter SecTrail MFA server connection information:

Step 2: API Server Configuration

Enter your SecTrail MFA Server address (IP or domain)
Examples: 10.34.24.217, auth.example.com, sectrail.company.local
SecTrail MFA Server Address: [SecTrail MFA server address]
Client ID: [API Client ID]
Client Secret: [API Client Secret]
Request timeout (seconds) [10]:
Enable debug mode? [y/N]: n

API Connection Test: The script automatically tests the connection:

✓ OAuth token obtained successfully
  Token: eyJ0eXAiOiJKV1QiLCJh...
  Expires in: 43200s
3. Authentication Mode Selection​

Select the authentication mode for the PAM module:

Step 3: Authentication Mode

1) Primary Authentication Mode
   • SecTrail API handles password + OTP authentication
   • If API fails/rejects, authentication fails (no local fallback)

2) Fallback Mode
   • Try SecTrail API first, fallback to local if unavailable

3) Two-Factor Authentication (2FA) Mode (Recommended)
   • Local password (1st factor) + SecTrail OTP (2nd factor)
   • BOTH must succeed for authentication

Select authentication mode [1-3]: 3

Authentication Mode Details:

1) Primary Authentication Mode

  • SecTrail API handles password + OTP authentication
  • User enters: password, then OTP code
  • API validates both factors
  • If API fails/rejects, authentication fails (no local fallback)
  • PAM config: auth required pam_sectrail.so

2) Fallback Mode

  • Try SecTrail API (password + OTP) first, fallback to local if unavailable
  • User enters: password, then OTP code
  • If API rejects or times out, local password is checked
  • PAM config: auth sufficient pam_sectrail.so

3) Two-Factor Authentication (2FA) Mode (Recommended)

  • Local password (1st factor) + SecTrail OTP (2nd factor)
  • User enters: password (checked locally), then OTP code (checked by API)
  • BOTH must succeed for authentication
  • PAM config:
    auth requisite pam_unix.so
    auth required pam_sectrail.so

Recommended Mode: 2FA Mode (3) - Local password check + SecTrail MFA OTP

4. Service Selection​

Select which services should have MFA enabled:

Step 4: Service Selection

• Enable for SSH (sshd)? [Y/n]: Y
• Enable for sudo? [Y/n]: Y
• Enable for su? [y/N]: n
• Enable for console login? [y/N]: n

Service Descriptions:

  • SSH (sshd): Adds MFA to remote SSH connections
  • sudo: Adds MFA requirement to sudo commands
  • su: Requires MFA when switching to root user
  • console login: Adds MFA to physical console logins
5. Installation Summary​

Review and confirm the configuration summary:

Step 5: Installation Summary

Configuration:
  OAuth Token URL: https://10.34.24.217/oauth/token
  Auth API URL: https://10.34.24.217/api/auth/agent
  Client ID: ST-oydsjd
  Client Secret: 6N0zaq59wg***
  Token Cache: 3600s
  Timeout: 10s
  API Test: ✓ Passed

Authentication Mode:
  PAM Control: required

Services to configure:
  ✓ ssh
  ✓ sudo

Proceed with installation? [Y/n]: Y
6. Installation Complete​
Step 6: Installing...

Creating directories...
✓ PAM module installed to /usr/lib64/security/pam_sectrail.so
✓ Configuration file created at /etc/security/pam_sectrail.conf
✓ Log file created at /var/log/pam_sectrail.log

Configuring SSH...
✓ SSH configured

Configuring sudo...
✓ sudo configured

═══════════════════════════════════════════════════════════
✓ Installation Complete!
═══════════════════════════════════════════════════════════

Important Note: After installation completes, keep your current terminal session open and test in a new terminal session!

Post-Installation Testing​

After installation completes, be sure to test:

# Open a new terminal and test SSH
ssh user@localhost
Password: ********          # Enter your local password
SecTrail MFA Code: 123456   # Enter SecTrail MFA OTP code
# Sudo test
sudo whoami
[sudo] password for admin: ********    # Enter your local password
SecTrail MFA Code: 789012              # Enter SecTrail MFA OTP code
root

Backup and Log Files​

The installation script automatically creates backup files:

Backup files created:
  • /etc/pam.d/sshd.stpam-bak
  • /etc/pam.d/sudo.stpam-bak
  • /etc/pam.d/su.stpam-bak

Logs:
  • Main log: /var/log/pam_sectrail.log
  • System logs: journalctl -u ssh -u sudo

Uninstall​

To remove the module:

# Manually remove the PAM module
sudo rm /usr/lib64/security/pam_sectrail.so

# OR restore from backup files
sudo cp /etc/pam.d/sshd.stpam-bak /etc/pam.d/sshd
sudo cp /etc/pam.d/sudo.stpam-bak /etc/pam.d/sudo

Supported Authentication Methods​

Authentication methods that can be used in Linux SSH, Sudo, and Console integration:

  • LDAP Authentication: Authentication with Active Directory or LDAP server
  • Local Authentication: Authentication with SecTrail MFA's local user database
  • LDAP+OTP: Two-factor authentication with password + OTP on a single screen
  • Soft OTP: Time-based one-time password with mobile app (SecTrail Authenticator)
  • SMS OTP: One-time password sent via SMS
  • Mail OTP: One-time password sent via email
  • Push Notification: Approval via push notification on mobile app (SecTrail Authenticator)
  • Approved OTP: Authentication with pre-approved OTP codes

Audit Logging​

All Linux MFA operations are logged:

  • /var/log/auth.log (Debian/Ubuntu)
  • /var/log/secure (RHEL/CentOS)
  • Central logging to SecTrail MFA server
  • Syslog integration
WARNING

If you make an error in PAM configuration, you may not be able to log into the system. Always keep a root shell open or ensure you have console access.