OpenSSH PAM Integration Guide

Introduction

Pluggable Authentication Modules (PAM) provide a flexible framework for authentication in Linux systems. When integrated with OpenSSH, PAM allows for advanced authentication methods beyond standard password or key-based authentication. This guide will walk you through the process of implementing PAM with OpenSSH to enhance your system’s security.

Understanding PAM

PAM separates authentication tasks into four management groups:

1. Authentication (auth): Verifies user identity
2. Account: Checks if the account is valid and allowed to access the service
3. Password: Handles password updates
4. Session: Manages actions at the beginning and end of a session

Each module is associated with one of these groups and can be configured to work together to create a flexible authentication system.

Prerequisites

• A Linux system with administrative access
• OpenSSH version 4.3 or higher
• Basic understanding of Linux system administration

Step 1: Ensure PAM Support is Enabled in OpenSSH

First, check if your OpenSSH installation has PAM support:

ssh -V

The version should be 4.3 or higher. Next, check if PAM is enabled in your SSH configuration:

grep -i "UsePAM" /etc/ssh/sshd_config

If PAM is not enabled, edit /etc/ssh/sshd_config and set:

UsePAM yes

Step 2: Understanding the PAM Configuration Files

PAM configuration files are stored in /etc/pam.d/. The configuration file for SSH is typically named /etc/pam.d/sshd.

Additional PAM configuration files may be found in /etc/security/.

Step 3: Basic PAM Configuration for SSH

A typical PAM configuration for SSH includes the following components:

1. Open /etc/pam.d/sshd in your preferred text editor
2. Make sure it includes the necessary modules for authentication, account, password, and session management

A basic configuration might look like:

# PAM configuration for SSH
# Authentication modules
auth       required     pam_unix.so

# Account management
account    required     pam_unix.so

# Password management
password   required     pam_unix.so

# Session management
session    required     pam_unix.so

This basic configuration uses the standard Unix authentication method.

Step 4: Configure SSH to Work with PAM

Edit /etc/ssh/sshd_config to set the following parameters:

# Enable PAM
UsePAM yes

# Configure authentication methods
# Choose the appropriate options based on your requirements:

# Allow password authentication (PAM will handle it)
PasswordAuthentication yes

# For challenge-response authentication (like OTP)
ChallengeResponseAuthentication yes

# If you want to use key-based authentication along with PAM
PubkeyAuthentication yes

# If you want to require both public key and PAM authentication
AuthenticationMethods publickey,keyboard-interactive

Step 5: Advanced PAM Configurations

5.1. Implementing Two-Factor Authentication

To implement 2FA using Google Authenticator:

1. Install the required package:

   # Debian/Ubuntu
   apt-get install libpam-google-authenticator
      
   # Red Hat/CentOS
   yum install google-authenticator
   

2. Configure PAM by editing /etc/pam.d/sshd:

   # Add this line for 2FA
   auth required pam_google_authenticator.so nullok
   

   The nullok parameter allows users without a configured authenticator to still log in.

3. Configure SSH by editing /etc/ssh/sshd_config:

   ChallengeResponseAuthentication yes
   AuthenticationMethods publickey,keyboard-interactive
   

4. Have users run the google-authenticator command to set up their tokens.

5.2. Restricting Access by User or Group

You can use pam_listfile.so to create allow/deny lists:

1. Create a file for your user list, e.g., /etc/ssh/ssh.allow or /etc/ssh/ssh.deny
2. Add usernames to the file, one per line

3. Configure PAM by adding to /etc/pam.d/sshd:

   # Deny users in the list
   auth required pam_listfile.so item=user sense=deny file=/etc/ssh/ssh.deny onerr=succeed
      
   # Or allow only users in the list
   auth required pam_listfile.so item=user sense=allow file=/etc/ssh/ssh.allow onerr=fail
   

5.3. Time-based Access Restrictions

Use pam_time.so to restrict access based on time:

1. Edit /etc/security/time.conf to add time-based rules
2. Add to /etc/pam.d/sshd:

   account required pam_time.so
   

5.4. Resource Limits

Control user resource limits with pam_limits.so:

1. Configure limits in /etc/security/limits.conf
2. Add to /etc/pam.d/sshd:

   session required pam_limits.so
   

Step 6: Testing Your Configuration

Before fully implementing your changes:

1. Keep a root session open in another terminal
2. Make your changes to the configuration files
3. Restart the SSH service:

   systemctl restart sshd
   

4. Test your configuration by attempting to log in from a new session

Step 7: Troubleshooting

If you encounter issues:

1. Check the system logs for error messages:

   tail -f /var/log/auth.log   # Debian/Ubuntu
   tail -f /var/log/secure     # Red Hat/CentOS
   

2. Temporarily disable PAM authentication for SSH if needed:

   UsePAM no
   PasswordAuthentication yes
   

3. Restart SSH and revert to a working configuration

Security Considerations

1. Always maintain an open session when making changes to SSH or PAM configuration
2. Implement changes incrementally and test thoroughly
3. Be cautious with onerr=succeed as it could allow access if the module fails
4. Remember that key-based authentication might bypass PAM auth modules unless explicitly configured
5. Ensure your PAM configuration files have proper permissions

Conclusion

PAM provides powerful flexibility for securing SSH access to your systems. With proper configuration, you can implement multi-factor authentication, access control, and other security enhancements. Always implement changes carefully and test thoroughly to avoid being locked out of your system.

References

For more information, refer to:

• The PAM Administrator’s Guide
• Manual pages: man pam, man pam.conf, man sshd_config
• Your distribution’s documentation on PAM and SSH