Add header authentication

2026-03-28 23:06:34 +00:00 · 2025-09-18 22:35:40 +02:00
parent fee421beba
commit 75a7ca62a9
11 changed files with 1392 additions and 127 deletions
--- a/docs/kerberos-authentication.md
+++ b/docs/kerberos-authentication.md
@@ -0,0 +1,156 @@
+# Kerberos Authentication
+
+![Kerberos](images/flow-kerberos.svg)
+
+RDPGW supports Kerberos authentication via SPNEGO for seamless integration with Active Directory and other Kerberos environments.
+
+## Important Notes
+
+**⚠️ DNS Requirements**: Kerberos is heavily reliant on DNS (forward and reverse). Ensure your DNS is properly configured.
+
+**⚠️ Error Messages**: Kerberos errors are not always descriptive. This documentation provides configuration guidance, but detailed Kerberos troubleshooting is beyond scope.
+
+## Prerequisites
+
+- Valid Kerberos environment (KDC/Active Directory)
+- Proper DNS configuration (forward and reverse lookups)
+- Service principal for the gateway
+- Keytab file with appropriate permissions
+
+## Configuration
+
+### 1. Create Service Principal
+
+Create a service principal for the gateway in your Kerberos realm:
+
+```bash
+# Active Directory
+setspn -A HTTP/rdpgw.example.com@YOUR.REALM service-account
+
+# MIT Kerberos
+kadmin.local -q "addprinc -randkey HTTP/rdpgw.example.com@YOUR.REALM"
+```
+
+### 2. Generate Keytab
+
+Use `ktutil` or similar tool to create a keytab file:
+
+```bash
+ktutil
+addent -password -p HTTP/rdpgw.example.com@YOUR.REALM -k 1 -e aes256-cts-hmac-sha1-96
+wkt rdpgw.keytab
+quit
+```
+
+Place the keytab file in a secure location and ensure it's only readable by the gateway user:
+
+```bash
+sudo mv rdpgw.keytab /etc/keytabs/
+sudo chown rdpgw:rdpgw /etc/keytabs/rdpgw.keytab
+sudo chmod 600 /etc/keytabs/rdpgw.keytab
+```
+
+### 3. Configure krb5.conf
+
+Ensure `/etc/krb5.conf` is properly configured:
+
+```ini
+[libdefaults]
+    default_realm = YOUR.REALM
+    dns_lookup_realm = true
+    dns_lookup_kdc = true
+
+[realms]
+    YOUR.REALM = {
+        kdc = kdc.your.realm:88
+        admin_server = kdc.your.realm:749
+    }
+
+[domain_realm]
+    .your.realm = YOUR.REALM
+    your.realm = YOUR.REALM
+```
+
+### 4. Gateway Configuration
+
+```yaml
+Server:
+  Authentication:
+    - kerberos
+Kerberos:
+  Keytab: /etc/keytabs/rdpgw.keytab
+  Krb5conf: /etc/krb5.conf
+Caps:
+  TokenAuth: false
+```
+
+## Authentication Flow
+
+1. Client connects to gateway with Kerberos ticket
+2. Gateway validates ticket using keytab
+3. Client connects directly without RDP file download
+4. Gateway proxies TGT requests to KDC as needed
+
+## KDC Proxy Support
+
+RDPGW includes KDC proxy functionality for environments where clients cannot directly reach the KDC:
+
+- Endpoint: `https://your-gateway/KdcProxy`
+- Supports MS-KKDCP protocol
+- Automatically configured when Kerberos authentication is enabled
+
+## Client Configuration
+
+### Windows Clients
+
+Configure Windows clients to use the gateway's FQDN and ensure:
+- Client can resolve gateway hostname
+- Client time is synchronized with KDC
+- Client has valid TGT
+
+### Linux Clients
+
+Ensure `krb5.conf` is configured and client has valid ticket:
+
+```bash
+kinit username@YOUR.REALM
+klist  # Verify ticket
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Clock Skew**: Ensure all systems have synchronized time
+2. **DNS Issues**: Verify forward/reverse DNS resolution
+3. **Principal Names**: Ensure service principal matches gateway FQDN
+4. **Keytab Permissions**: Verify keytab file permissions and ownership
+
+### Debug Commands
+
+```bash
+# Test keytab
+kinit -k -t /etc/keytabs/rdpgw.keytab HTTP/rdpgw.example.com@YOUR.REALM
+
+# Verify DNS
+nslookup rdpgw.example.com
+nslookup <gateway-ip>
+
+# Check time sync
+ntpdate -q ntp.your.realm
+```
+
+### Log Analysis
+
+Enable verbose logging in RDPGW and check for:
+- Keytab loading errors
+- Principal validation failures
+- KDC communication issues
+
+## Security Considerations
+
+- Protect keytab files with appropriate permissions (600)
+- Regularly rotate service account passwords
+- Monitor for unusual authentication patterns
+- Ensure encrypted communication (aes256-cts-hmac-sha1-96)
+- Use specific service accounts, not user accounts