rdpgw/docs/kerberos-authentication.md

Kerberos Authentication

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:

# 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:

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:

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:

[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

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:

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

# 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