Add header authentication

docs/pam-authentication.md

@@ -0,0 +1,242 @@
+# PAM/Local Authentication
+
+![PAM](images/flow-pam.svg)
+
+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:**
+```plaintext
+auth required pam_unix.so
+account required pam_unix.so
+```
+
+**LDAP authentication:**
+```plaintext
+auth required pam_ldap.so
+account required pam_ldap.so
+```
+
+**Active Directory (via Winbind):**
+```plaintext
+auth sufficient pam_winbind.so
+account sufficient pam_winbind.so
+```
+
+### 2. Gateway Configuration
+
+```yaml
+Server:
+  Authentication:
+    - local
+  AuthSocket: /tmp/rdpgw-auth.sock
+  BasicAuthTimeout: 5  # seconds
+Caps:
+  TokenAuth: false
+```
+
+### 3. Start Authentication Helper
+
+Run the `rdpgw-auth` helper program:
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```plaintext
+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:
+
+```yaml
+# 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:
+
+```yaml
+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`:
+
+```ini
+[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:
+
+```bash
+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
+
+```bash
+# 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`:
+
+```plaintext
+auth,authpriv.*                 /var/log/auth.log
+```
+
+Monitor authentication attempts:
+
+```bash
+tail -f /var/log/auth.log | grep rdpgw
+```