From 46d12c52be09a8f593e0900d8bf9cfd9cc7a0f73 Mon Sep 17 00:00:00 2001
From: Bolke de Bruin <bolke@xs4all.nl>
Date: Thu, 18 Sep 2025 23:03:46 +0200
Subject: [PATCH] Add extra info on app gateway

---
 docs/header-authentication.md | 134 +++++++++++++++++++++++++++++++---
 1 file changed, 122 insertions(+), 12 deletions(-)

diff --git a/docs/header-authentication.md b/docs/header-authentication.md
index 65c8a22..2867df2 100644
--- a/docs/header-authentication.md
+++ b/docs/header-authentication.md
@@ -28,13 +28,75 @@ Security:
 ### Microsoft Azure Application Proxy
 
 ```yaml
+Server:
+  Authentication:
+    - header
+  Tls: disable  # App Proxy handles TLS termination
+
 Header:
   UserHeader: "X-MS-CLIENT-PRINCIPAL-NAME"
   UserIdHeader: "X-MS-CLIENT-PRINCIPAL-ID"
   EmailHeader: "X-MS-CLIENT-PRINCIPAL-EMAIL"
+
+Security:
+  VerifyClientIp: false  # Required for App Proxy
+
+Caps:
+  TokenAuth: true  # Essential for RDP client connections
 ```
 
-**Setup**: Configure App Proxy to publish RDPGW with pre-authentication enabled. Users authenticate via Azure AD before reaching RDPGW.
+**Azure Configuration:**
+
+1. **Create App Registration** in Azure AD:
+   ```bash
+   # Note the Application ID for App Proxy configuration
+   az ad app create --display-name "RDPGW-AppProxy"
+   ```
+
+2. **Configure Application Proxy**:
+   - **Internal URL**: `http://rdpgw-internal:80` (or your internal RDPGW address)
+   - **External URL**: `https://rdpgw.yourdomain.com`
+   - **Pre-authentication**: Azure Active Directory
+   - **Pass through**: Enabled for `/remoteDesktopGateway/`
+
+3. **Configure Conditional Access Policies**:
+   - Target the RDPGW App Proxy application
+   - Set device compliance, location restrictions, MFA requirements
+   - Enable session controls as needed
+
+**Important App Proxy Configuration:**
+
+```json
+{
+  "name": "RDPGW",
+  "internalUrl": "http://rdpgw-internal",
+  "externalUrl": "https://rdpgw.yourdomain.com",
+  "preAuthenticatedApplication": {
+    "preAuthenticationType": "AzureActiveDirectory",
+    "passthroughPaths": [
+      "/remoteDesktopGateway/*"
+    ]
+  }
+}
+```
+
+**Authentication Flow:**
+
+1. **Web Authentication** (`/connect` endpoint):
+   ```
+   User Browser → App Proxy (Azure AD auth) → RDPGW → Downloads RDP file
+   ```
+
+2. **RDP Client Connection** (`/remoteDesktopGateway/` endpoint):
+   ```
+   RDP Client → App Proxy (passthrough) → RDPGW (token validation) → RDP Host
+   ```
+
+**Key Requirements:**
+- **Passthrough configuration** for `/remoteDesktopGateway/` path
+- **Header authentication** only for `/connect` endpoint
+- **Token-based auth** for actual RDP connections
+- **Disable IP verification** due to App Proxy NAT
 
 ### Google Cloud Identity-Aware Proxy (IAP)
 
@@ -79,19 +141,67 @@ Header:
 
 **nginx config**:
 ```nginx
-location /auth {
-  internal;
-  proxy_pass http://auth-service;
-  proxy_set_header X-Original-URI $request_uri;
+upstream rdpgw {
+    server rdpgw:443;
 }
 
-location / {
-  auth_request /auth;
-  auth_request_set $user $upstream_http_x_auth_user;
-  auth_request_set $email $upstream_http_x_auth_email;
-  proxy_set_header X-Auth-User $user;
-  proxy_set_header X-Auth-Email $email;
-  proxy_pass http://rdpgw;
+upstream auth-service {
+    server auth-service:80;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name your-gateway.example.com;
+
+    # SSL configuration
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    # Auth endpoint (internal)
+    location /auth {
+        internal;
+        proxy_pass http://auth-service;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Original-URI $request_uri;
+        proxy_set_header X-Original-Method $request_method;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # Main location with auth and WebSocket support
+    location / {
+        # Authentication
+        auth_request /auth;
+        auth_request_set $user $upstream_http_x_auth_user;
+        auth_request_set $email $upstream_http_x_auth_email;
+
+        # Forward user headers to RDPGW
+        proxy_set_header X-Auth-User $user;
+        proxy_set_header X-Auth-Email $email;
+
+        # WebSocket and HTTP upgrade support
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # Timeouts for long-lived connections
+        proxy_read_timeout 86400s;
+        proxy_send_timeout 86400s;
+
+        # Disable buffering for real-time protocols
+        proxy_buffering off;
+
+        proxy_pass https://rdpgw;
+    }
+}
+
+# WebSocket upgrade mapping
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
 }
 ```