rdpgw/docs/pam-authentication.md

PAM/Local Authentication

RDPGW supports PAM (Pluggable Authentication Modules) for authentication against local accounts, LDAP, Active Directory, and other PAM-supported systems.

Important Notes

⚠️ Client Limitation: The default Windows client mstsc does not support basic authentication. Use alternative clients or switch to OpenID Connect, Kerberos, or NTLM authentication.

⚠️ Container Considerations: Using PAM for passwd authentication within containers is not recommended. Use OpenID Connect or Kerberos instead. For LDAP/AD authentication, PAM works well in containers.

Architecture

PAM authentication uses a privilege separation model with the rdpgw-auth helper program:

• rdpgw - Main gateway (runs as unprivileged user)
• rdpgw-auth - Authentication helper (runs as root or setuid)
• Communication via Unix socket

Configuration

1. PAM Service Configuration

Create /etc/pam.d/rdpgw for the authentication service:

Local passwd authentication:

auth required pam_unix.so
account required pam_unix.so

LDAP authentication:

auth required pam_ldap.so
account required pam_ldap.so

Active Directory (via Winbind):

auth sufficient pam_winbind.so
account sufficient pam_winbind.so

2. Gateway Configuration

Server:
  Authentication:
    - local
  AuthSocket: /tmp/rdpgw-auth.sock
  BasicAuthTimeout: 5  # seconds
Caps:
  TokenAuth: false

3. Start Authentication Helper

Run the rdpgw-auth helper program:

# Basic usage
./rdpgw-auth -n rdpgw -s /tmp/rdpgw-auth.sock

# With custom PAM service name
./rdpgw-auth -n custom-service -s /tmp/rdpgw-auth.sock

# Run as systemd service
systemctl start rdpgw-auth

Authentication Flow

1. Client connects to gateway with username/password
2. Gateway forwards credentials to rdpgw-auth via socket
3. rdpgw-auth validates credentials using PAM
4. Gateway generates session tokens on successful authentication
5. Client connects directly using authenticated session

PAM Module Examples

LDAP Integration

Install and configure LDAP PAM module:

# Install LDAP PAM module
sudo apt-get install libpam-ldap

# Configure /etc/pam_ldap.conf
host ldap.example.com
base dc=example,dc=com
binddn cn=readonly,dc=example,dc=com
bindpw secret

Active Directory Integration

Configure Winbind PAM module:

# Install Winbind
sudo apt-get install winbind libpam-winbind

# Configure /etc/samba/smb.conf
[global]
security = ads
realm = EXAMPLE.COM
workgroup = EXAMPLE

Two-Factor Authentication

Integrate with TOTP/HOTP using pam_oath:

auth required pam_oath.so usersfile=/etc/users.oath
auth required pam_unix.so
account required pam_unix.so

Container Deployment

Option 1: External Helper

Run rdpgw-auth on the host and mount socket:

# docker-compose.yml
services:
  rdpgw:
    image: rdpgw
    volumes:
      - /tmp/rdpgw-auth.sock:/tmp/rdpgw-auth.sock

Option 2: Privileged Container

Mount PAM configuration and user databases:

services:
  rdpgw:
    image: rdpgw
    privileged: true
    volumes:
      - /etc/passwd:/etc/passwd:ro
      - /etc/shadow:/etc/shadow:ro
      - /etc/pam.d:/etc/pam.d:ro

Systemd Service

Create /etc/systemd/system/rdpgw-auth.service:

[Unit]
Description=RDPGW Authentication Helper
After=network.target

[Service]
Type=simple
User=root
ExecStart=/usr/local/bin/rdpgw-auth -n rdpgw -s /tmp/rdpgw-auth.sock
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable rdpgw-auth
sudo systemctl start rdpgw-auth

Compatible Clients

Since mstsc doesn't support basic authentication, use these alternatives:

Windows

• Remote Desktop Connection Manager (RDCMan)
• mRemoteNG
• Royal TS/TSX

Linux

• Remmina
• FreeRDP (with basic auth support)
• KRDC

macOS

• Microsoft Remote Desktop (from App Store)
• Royal TSX

Security Considerations

• Run rdpgw-auth with minimal privileges
• Secure the Unix socket with appropriate permissions
• Use strong PAM configurations (account lockout, password complexity)
• Enable logging for authentication events
• Consider rate limiting for brute force protection
• Use encrypted connections (TLS) for the gateway

Troubleshooting

Common Issues

1. Socket Permission Denied: Check socket permissions and ownership
2. PAM Authentication Failed: Verify PAM configuration and user credentials
3. Helper Not Running: Ensure rdpgw-auth is running and accessible

Debug Commands

# Test PAM configuration
pamtester rdpgw username authenticate

# Check socket
ls -la /tmp/rdpgw-auth.sock

# Verify helper process
ps aux | grep rdpgw-auth

# Test authentication manually
echo "username:password" | nc -U /tmp/rdpgw-auth.sock

Log Analysis

Enable PAM logging in /etc/rsyslog.conf:

auth,authpriv.*                 /var/log/auth.log

Monitor authentication attempts:

tail -f /var/log/auth.log | grep rdpgw