### Start RDPGW Authentication Helper

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This bash command starts the `rdpgw-auth` helper service, specifying its configuration file and the socket path for communication.

```bash
./rdpgw-auth -c /etc/rdpgw-auth.yaml -s /tmp/rdpgw-auth.sock
```

--------------------------------

### Example RDP Gateway Configuration

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

A comprehensive example configuration file for RDP Gateway, demonstrating various settings including authentication, TLS, gateway address, port, hosts, and session management.

```yaml
# web server configuration. 
Server:
 # can be set to openid, kerberos, local and ntlm. If openid is used rdpgw expects
 # a configured openid provider, make sure to set caps.tokenauth to true. If local
 # rdpgw connects to rdpgw-auth over a socket to verify users and password. Note: 
 # rdpgw-auth needs to be run as root or setuid in order to work. If kerberos is
 # used a keytab and krb5conf need to be supplied. local can be stacked with 
 # kerberos or ntlm authentication, so that the clients selects what it wants.
 Authentication:
  # - kerberos
  # - local
  - openid
  # - ntlm
 # The socket to connect to if using local auth. Ensure rdpgw auth is configured to
 # use the same socket.
 # AuthSocket: /tmp/rdpgw-auth.sock
 # Basic auth timeout (in seconds). Useful if you're planning on waiting for MFA
 BasicAuthTimeout: 5
 # The default option 'auto' uses a certificate file if provided and found otherwise
 # it uses letsencrypt to obtain a certificate, the latter requires that the host is reachable
 # from letsencrypt servers. If TLS termination happens somewhere else (e.g. a load balancer) 
 # set this option to 'disable'. This is mutually exclusive with 'authentication: local'
 # Note: rdp connections over a gateway require TLS
 Tls: auto
 # gateway address advertised in the rdp files and browser
 GatewayAddress: localhost
 # port to listen on (change to 80 or equivalent if not using TLS)
 Port: 443
 # list of acceptable desktop hosts to connect to
 Hosts:
  - localhost:3389
  - my-{{ preferred_username }}-host:3389
 # if true the server randomly selects a host to connect to
 # valid options are: 
 #  - roundrobin, which selects a random host from the list (default)
 #  - signed, a listed host specified in the signed query parameter
 #  - unsigned, a listed host specified in the query parameter
 #  - any, insecurely allow any host specified in the query parameter
 HostSelection: roundrobin 
 # a random strings of at least 32 characters to secure cookies on the client
 # make sure to share this across the different pods
 SessionKey: thisisasessionkeyreplacethisjetzt
 SessionEncryptionKey: thisisasessionkeyreplacethisnunu!
  # where to store session details. This can be either file or cookie (default: cookie) 
  # if a file store is chosen, it is required to have clients 'keep state' to the rdpgw
  # instance they are connected to.
 SessionStore: cookie
  # tries to set the receive / send buffer of the connections to the client
 # in case of high latency high bandwidth the defaults set by the OS might
 # be to low for a good experience
 # ReceiveBuf: 12582912
 # SendBuf: 12582912 
# Open ID Connect specific settings
OpenId:
 ProviderUrl: http://keycloak/auth/realms/test
 ClientId: rdpgw
 ClientSecret: your-secret
# Kerberos:
#  Keytab: /etc/keytabs/rdpgw.keytab
#  Krb5conf: /etc/krb5.conf
```

--------------------------------

### Build RDPGW from Source

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Instructions for installing dependencies, cloning the repository, and compiling the RDPGW binary on Debian/Ubuntu systems.

```bash
sudo apt-get install build-essential golang libpam0g-dev
git clone https://github.com/bolkedebruin/rdpgw.git
cd rdpgw
make
make install
./rdpgw -c /etc/rdpgw/rdpgw.yaml
```

--------------------------------

### GET /connect

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Initiates a Remote Desktop connection by redirecting the user to the configured OpenID provider for authentication.

```APIDOC
## GET /connect

### Description
Initiates the connection flow. The user is redirected to the OpenID provider. Upon successful authentication, the client receives an RDP file download.

### Method
GET

### Endpoint
/connect

### Response
#### Success Response (302/200)
- **Content-Type** (string) - Redirects to OIDC provider or returns application/x-rdp file.
```

--------------------------------

### Build and Install RDPGW from Source

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Commands to clone the repository and build the RDPGW binary using make. Requires Go 1.19+ and PAM development headers.

```bash
cd rdpgw
make
make install
```

--------------------------------

### Deploy RDPGW with Docker Compose

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Example docker-compose configuration integrating RDPGW with a Keycloak OpenID Connect provider and an XRDP backend.

```yaml
version: '3.4'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    ports:
      - 8080:8080
  xrdp:
    image: bolkedebruin/docker-ubuntu-xrdp-mate-rdpgw:latest
    ports:
      - 3389:3389
  rdpgw:
    image: bolkedebruin/rdpgw:latest
    ports:
      - 9443:9443
    environment:
      RDPGW_SERVER__SESSION_STORE: cookie
      RDPGW_OPEN_ID__PROVIDER_URL: "http://keycloak:8080/auth/realms/rdpgw"
```

--------------------------------

### Connect to RDPGW via RDP Clients

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Examples of how to configure various RDP clients including FreeRDP to connect through the RDPGW gateway.

```bash
xfreerdp /v:desktop.internal:3389 \
         /g:rdpgw.example.com:443 \
         /gu:user@example.com \
         /gp:password \
         /u:rdpuser \
         /p:rdppassword \
         /cert:ignore
```

--------------------------------

### OpenID Connect Authentication Configuration

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Example configuration for setting up OpenID Connect authentication. This involves specifying the OpenID provider URL, client ID, and client secret.

```yaml
Authentication:
  - openid
OpenId:
 ProviderUrl: http://keycloak/auth/realms/test
 ClientId: rdpgw
 ClientSecret: your-secret
```

--------------------------------

### Test Authentication Header with cURL

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

A command-line example to test if the proxy correctly handles forwarded user headers for authentication.

```bash
curl -H "X-Forwarded-User: testuser@domain.com" https://your-proxy/connect
```

--------------------------------

### GET /connect

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Initiates the authentication flow for the RDP gateway. Users are redirected to the configured identity provider, and upon successful authentication, an RDP file is downloaded.

```APIDOC
## GET /connect

### Description
Initiates the authentication flow for the RDP gateway. After successful authentication, an RDP file is downloaded to the user's desktop.

### Method
GET

### Endpoint
/connect

### Parameters
None

### Request Example
GET /connect

### Response
#### Success Response (200)
- **Content-Type** (string) - application/x-rdp
- **Body** (file) - The RDP configuration file for the remote session.
```

--------------------------------

### Verify RDP Gateway Authentication Configuration

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This command displays the content of the `rdpgw-auth` configuration file, typically located at `/etc/rdpgw-auth.yaml`. Verifying this file is essential for correct authentication setup.

```bash
cat /etc/rdpgw-auth.yaml
```

--------------------------------

### GET /api/v1/hosts

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Retrieves a list of available RDP hosts for the authenticated user.

```APIDOC
## GET /api/v1/hosts

### Description
Returns a JSON list of RDP hosts that the authenticated user is permitted to access.

### Method
GET

### Endpoint
/api/v1/hosts

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer <token>

### Response
#### Success Response (200)
- **hosts** (array) - List of available host objects.
```

--------------------------------

### GET /tokeninfo

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Verifies the provided JWT access token and returns the decrypted payload.

```APIDOC
## GET /tokeninfo

### Description
Validates an access token and returns the associated user information or claims.

### Method
GET

### Endpoint
/tokeninfo

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The JWT token to verify.

### Response
#### Success Response (200)
- **payload** (object) - The decrypted claims contained within the JWT.
```

--------------------------------

### GET /api/v1/user

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Retrieves profile information for the currently authenticated user.

```APIDOC
## GET /api/v1/user

### Description
Fetches user details based on the provided authentication token.

### Method
GET

### Endpoint
/api/v1/user

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer <token>

### Response
#### Success Response (200)
- **user** (object) - User profile information.
```

--------------------------------

### Enable Debug Logging for RDP Gateway Authentication

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This command starts the `rdpgw-auth` service with debug logging enabled, using a specified configuration file and socket path. Debug logging provides detailed NTLM protocol analysis for troubleshooting.

```bash
./rdpgw-auth -c /etc/rdpgw-auth.yaml -s /tmp/rdpgw-auth.sock -v
```

--------------------------------

### GET /tokeninfo

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Verifies a user token by decrypting it and returning the embedded information. This endpoint is used for integrating with external services like pam-jwt.

```APIDOC
## GET /tokeninfo

### Description
Verifies the provided access token and returns the decrypted token details.

### Method
GET

### Endpoint
/tokeninfo

### Parameters
#### Query Parameters
- **access_token** (string) - Required - The token to be verified.

### Request Example
GET /tokeninfo?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

### Response
#### Success Response (200)
- **token_data** (object) - The decrypted contents of the token.

#### Response Example
{
  "username": "admin",
  "exp": 1672531200
}
```

--------------------------------

### Run RDPGW Local Testing Environments

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Commands to launch various local testing environments using Docker Compose, including OpenID Connect and local/PAM authentication flavors.

```bash
# with open id
cd dev/docker
docker-compose -f docker-compose.yml up

# or for arm64 with open id
docker-compose -f docker-compose-arm64.yml up

# or for local or pam
docker-compose -f docker-compose-local.yml up
```

--------------------------------

### Configure RDPGW via Environment Variables

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Demonstrates how to override or set RDPGW configuration using environment variables with the RDPGW_ prefix. Nested configuration keys are represented using double underscores.

```bash
export RDPGW_SERVER__GATEWAY_ADDRESS="rdpgw.example.com"
export RDPGW_SERVER__PORT="443"
export RDPGW_SERVER__TLS="auto"
export RDPGW_SERVER__HOSTS="desktop1:3389 desktop2:3389"
export RDPGW_SERVER__SESSION_KEY="your32characterrandomsessionkey!"
export RDPGW_OPEN_ID__PROVIDER_URL="https://keycloak.example.com/auth/realms/rdpgw"
export RDPGW_CAPS__ENABLE_CLIPBOARD="true"
export RDPGW_SECURITY__VERIFY_CLIENT_IP="true"
```

--------------------------------

### Deploy RDPGW via Docker Compose

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

A docker-compose configuration to deploy the RDPGW container, mounting the configuration file and setting environment variables.

```yaml
services:
  rdpgw:
    image: bolkedebruin/rdpgw:latest
    ports:
      - "80:443"
    volumes:
      - ./rdpgw.yaml:/app/rdpgw.yaml:ro
    environment:
      - RDPGW_SERVER__TLS=disable
      - RDPGW_SERVER__PORT=443
    networks:
      - internal

networks:
  internal:
    driver: bridge
```

--------------------------------

### Static File Serving

Source: https://github.com/bolkedebruin/rdpgw/blob/master/cmd/rdpgw/templates/README.md

The RDP Gateway serves static assets like CSS and JavaScript files directly from the `/static` directory without requiring authentication.

```APIDOC
## GET /static/style.css

### Description
Serves the main CSS stylesheet for the web interface.

### Method
GET

### Endpoint
/static/style.css

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **CSS Content** (text/css) - The content of the stylesheet.

## GET /static/app.js

### Description
Serves the JavaScript file containing the web interface logic, including server loading, authentication, and RDP client launching.

### Method
GET

### Endpoint
/static/app.js

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **JavaScript Content** (application/javascript) - The content of the JavaScript file.
```

--------------------------------

### Configure RDPGW Authentication Helper (rdpgw-auth)

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This YAML configuration defines user credentials for the `rdpgw-auth` helper service, which is used for NTLM authentication. It includes usernames and plain-text passwords.

```yaml
# /etc/rdpgw-auth.yaml
Users:
  - Username: "alice"
    Password: "secure_password_1"
  - Username: "bob"
    Password: "secure_password_2"
  - Username: "admin"
    Password: "admin_secure_password"
```

--------------------------------

### Configure TLS with Custom Certificate

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Enables TLS using a provided certificate and key file. Ensure the certificate is signed by a valid CA trusted by clients.

```yaml
Tls: enable
CertFile: server.pem
KeyFile: key.pem
```

--------------------------------

### Configure TLS with Let's Encrypt

Source: https://github.com/bolkedebruin/rdpgw/blob/master/README.md

Enables automatic TLS certificate acquisition from Let's Encrypt. Requires the host to be reachable on port 80 from Let's Encrypt servers.

```yaml
Tls: auto
```

--------------------------------

### Debug RDPGW Deployment

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

Commands to inspect container logs, test internal connectivity, and verify token generation endpoints. These are essential for diagnosing runtime issues.

```bash
docker logs rdpgw-container
curl -H "X-MS-CLIENT-PRINCIPAL-NAME: test@domain.com" http://rdpgw-internal/connect
curl -v https://rdpgw.yourdomain.com/connect
```

--------------------------------

### Configure TLS Settings

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Defines how to configure TLS for RDPGW, including automatic Let's Encrypt certificates, custom certificate files, or disabling TLS for proxy termination.

```yaml
# Automatic TLS with Let's Encrypt
Server:
  Tls: auto
  GatewayAddress: rdpgw.example.com
  Port: 443

# Custom TLS certificate
Server:
  Tls: enable
  CertFile: /etc/rdpgw/server.pem
  KeyFile: /etc/rdpgw/key.pem
  GatewayAddress: rdpgw.example.com
  Port: 443

# Disable TLS (proxy handles termination)
Server:
  Tls: disable
  GatewayAddress: rdpgw.example.com
  Port: 80
```

--------------------------------

### Configure Google Cloud IAP Headers

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

YAML snippet mapping Google Cloud Identity-Aware Proxy headers to RDPGW authentication fields.

```yaml
Header:
  UserHeader: "X-Goog-Authenticated-User-Email"
  UserIdHeader: "X-Goog-Authenticated-User-ID"
  EmailHeader: "X-Goog-Authenticated-User-Email"
```

--------------------------------

### Secure RDPGW Authentication Helper Configuration File

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This bash snippet demonstrates how to set secure file permissions for the `rdpgw-auth.yaml` configuration file. It ensures only the owner can read or write to it.

```bash
sudo chown rdpgw:rdpgw /etc/rdpgw-auth.yaml
sudo chmod 600 /etc/rdpgw-auth.yaml
```

--------------------------------

### Check RDP Gateway Authentication Helper Process

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This command checks if the `rdpgw-auth` helper process is currently running on the system. It's a crucial step for diagnosing authentication failures.

```bash
ps aux | grep rdpgw-auth
```

--------------------------------

### Systemd Service for RDPGW Authentication Helper

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This INI configuration defines a Systemd service unit for the `rdpgw-auth` helper. It specifies dependencies, execution command, and restart policies for reliable operation.

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

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

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Test RDP Gateway Authentication Socket Connectivity

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This command lists the details of the authentication socket file, usually located at `/tmp/rdpgw-auth.sock`. Checking its existence and permissions helps diagnose socket-related errors.

```bash
ls -la /tmp/rdpgw-auth.sock
```

--------------------------------

### Configure RDPGW via YAML

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Defines the primary configuration structure for RDPGW, including server settings, authentication providers, security keys, and RDP capabilities. This file is the central point for managing gateway behavior and access policies.

```yaml
Server:
  Authentication:
    - openid
  Tls: auto
  GatewayAddress: rdpgw.example.com
  Port: 443
  Hosts:
    - desktop1.internal:3389
    - desktop2.internal:3389
  HostSelection: roundrobin
  SessionKey: your32characterrandomsessionkey!
  SessionEncryptionKey: another32characterencryptionkey
  SessionStore: cookie

OpenId:
  ProviderUrl: https://keycloak.example.com/auth/realms/rdpgw
  ClientId: rdpgw
  ClientSecret: your-client-secret

Caps:
  EnableClipboard: true
  EnableDrive: true

Security:
  PAATokenSigningKey: your32characterpaatokensigningk
  VerifyClientIp: true
```

--------------------------------

### Configure PAM Logging with Rsyslog

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/pam-authentication.md

This configuration snippet enables PAM logging in rsyslog by directing 'auth' and 'authpriv' messages to '/var/log/auth.log'. This is a prerequisite for monitoring authentication events.

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

--------------------------------

### Register Azure AD Application for RDPGW

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

Uses PowerShell to create a new Azure AD application registration for the RDP Gateway service. This is the first step in enabling Azure AD authentication for the proxy.

```powershell
$app = New-AzADApplication -DisplayName "RDPGW-AppProxy" `
    -HomePage "https://rdpgw.yourdomain.com" `
    -IdentifierUris "https://rdpgw.yourdomain.com"

Write-Host "Application ID: $($app.ApplicationId)"
```

--------------------------------

### Configure Traefik ForwardAuth Headers

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

YAML snippet mapping Traefik ForwardAuth middleware headers to RDPGW authentication fields.

```yaml
Header:
  UserHeader: "X-Forwarded-User"
  EmailHeader: "X-Forwarded-Email"
  DisplayNameHeader: "X-Forwarded-Name"
```

--------------------------------

### Verify RDPGW Headers and Connectivity

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

Uses curl to test the RDP Gateway server by injecting specific headers. This helps verify that the application proxy is correctly forwarding client principal names to the internal server.

```bash
curl -H "X-MS-CLIENT-PRINCIPAL-NAME: user@domain.com" http://rdpgw-server/connect
```

--------------------------------

### Configure Azure Application Proxy

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

Specific YAML configuration for Azure App Proxy and the corresponding Azure CLI command to create the application registration.

```yaml
Server:
  Authentication:
    - header
  Tls: disable

Header:
  UserHeader: "X-MS-CLIENT-PRINCIPAL-NAME"
  UserIdHeader: "X-MS-CLIENT-PRINCIPAL-ID"
  EmailHeader: "X-MS-CLIENT-PRINCIPAL-EMAIL"

Security:
  VerifyClientIp: false

Caps:
  TokenAuth: true
```

```bash
az ad app create --display-name "RDPGW-AppProxy"
```

--------------------------------

### Configure AWS ALB with Cognito Headers

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

YAML snippet mapping AWS Application Load Balancer OIDC headers to RDPGW authentication fields.

```yaml
Header:
  UserHeader: "X-Amzn-Oidc-Subject"
  EmailHeader: "X-Amzn-Oidc-Email"
  DisplayNameHeader: "X-Amzn-Oidc-Name"
```

--------------------------------

### Configure Application Proxy Settings

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

A JSON configuration object representing the advanced settings for the Azure Application Proxy, including URL mapping and header translation.

```json
{
  "application": {
    "name": "RDPGW",
    "internalUrl": "http://rdpgw-server",
    "externalUrl": "https://rdpgw.yourdomain.com",
    "preAuthentication": "aadPreAuthentication",
    "externalAuthenticationType": "aadPreAuthentication",
    "applicationProxyUrlSettings": {
      "externalUrl": "https://rdpgw.yourdomain.com",
      "internalUrl": "http://rdpgw-server",
      "isTranslateHostHeaderEnabled": true,
      "isTranslateLinksInBodyEnabled": false,
      "isOnPremPublishingEnabled": true
    }
  }
}
```

--------------------------------

### Monitor RDP Gateway Authentication Logs

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This command continuously monitors the system logs for the `rdpgw-auth` service, displaying new entries in real-time. This is useful for observing authentication attempts and errors as they happen.

```bash
journalctl -u rdpgw-auth -f
```

--------------------------------

### Docker Compose for RDPGW Authentication

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This Docker Compose configuration sets up RDPGW and its NTLM authentication helper (`rdpgw-auth`) as services. It includes volume mounts for configuration and shared sockets.

```yaml
# docker-compose.yml
services:
  rdpgw-auth:
    image: rdpgw-auth
    volumes:
      - ./rdpgw-auth.yaml:/etc/rdpgw-auth.yaml:ro
      - auth-socket:/tmp
    restart: always

  rdpgw:
    image: rdpgw
    volumes:
      - auth-socket:/tmp
    depends_on:
      - rdpgw-auth

volumes:
  auth-socket:
```

--------------------------------

### Verify Web Authentication

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

A simple curl command to verify that the RDPGW web endpoint is correctly redirecting to Azure AD for authentication.

```bash
curl -v https://rdpgw.yourdomain.com/connect
```

--------------------------------

### Define RDPGW Service Configuration

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

The YAML configuration file for the RDPGW service, defining authentication headers, security keys, and host mapping rules.

```yaml
Server:
  Authentication:
    - header
  Tls: disable
  GatewayAddress: https://rdpgw.yourdomain.com
  Port: 80
  Hosts:
    - server1.internal.domain:3389
    - server2.internal.domain:3389
    - "{{ preferred_username }}-desktop:3389"

Header:
  UserHeader: "X-MS-CLIENT-PRINCIPAL-NAME"
  UserIdHeader: "X-MS-CLIENT-PRINCIPAL-ID"
  EmailHeader: "X-MS-CLIENT-PRINCIPAL-EMAIL"

Security:
  VerifyClientIp: false
  PAATokenSigningKey: "your-32-character-signing-key-here"
  PAATokenEncryptionKey: "your-32-character-encryption-key"

Caps:
  TokenAuth: true
  IdleTimeout: 60

Client:
  UsernameTemplate: "{{ username }}\x1f{{ token }}"
```

--------------------------------

### Monitor RDP Gateway Authentication Attempts

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/pam-authentication.md

This bash command monitors the authentication log file in real-time and filters for lines containing 'rdpgw'. This helps in tracking RDP Gateway-specific authentication events.

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

--------------------------------

### Kubernetes Deployment for RDPGW Authentication

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ntlm-authentication.md

This Kubernetes configuration defines a ConfigMap for the `rdpgw-auth` configuration and a Deployment for the `rdpgw-auth` service. It mounts the configuration securely.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: rdpgw-auth-config
data:
  rdpgw-auth.yaml: |
    Users:
      - Username: "user1"
        Password: "password1"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: rdpgw-auth
spec:
  template:
    spec:
      containers:
      - name: rdpgw-auth
        image: rdpgw-auth
        volumeMounts:
        - name: config
          mountPath: /etc/rdpgw-auth.yaml
          subPath: rdpgw-auth.yaml
      volumes:
      - name: config
        configMap:
          name: rdpgw-auth-config
```

--------------------------------

### Configure RDPGW Header Authentication

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

Defines the base YAML configuration for enabling header-based authentication in RDPGW. It specifies the headers to extract from the reverse proxy and disables TLS termination as the proxy handles it.

```yaml
Server:
  Authentication:
    - header
  Tls: disable

Header:
  UserHeader: "X-Forwarded-User"
  UserIdHeader: "X-Forwarded-User-Id"
  EmailHeader: "X-Forwarded-Email"
  DisplayNameHeader: "X-Forwarded-Name"

Caps:
  TokenAuth: true

Security:
  VerifyClientIp: false
```

--------------------------------

### Customize RDPGW Web Interface Branding

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

JSON configuration for modifying the web interface appearance, including branding, UI messages, and color themes.

```json
{
  "branding": {
    "title": "RDP Gateway",
    "logo": "My Company RDP",
    "page_title": "Select a Server to Connect"
  },
  "messages": {
    "select_server": "Select a server to connect",
    "preparing": "Preparing your connection..."
  },
  "ui": {
    "progress_animation_duration_ms": 2000,
    "auto_select_default": true,
    "show_user_avatar": true
  },
  "theme": {
    "primary_color": "#667eea",
    "secondary_color": "#764ba2",
    "success_color": "#38b2ac",
    "error_color": "#c53030"
  }
}
```

--------------------------------

### Configure Nginx as a Reverse Proxy for RDPGW

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

This configuration sets up Nginx to handle SSL termination, authentication subrequests, and WebSocket upgrades for the RDP gateway service.

```nginx
upstream rdpgw {
    server 127.0.0.1:8080;
}

upstream auth-service {
    server auth-service:80;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 443 ssl http2;
    server_name rdpgw.example.com;

    ssl_certificate /etc/ssl/certs/rdpgw.pem;
    ssl_certificate_key /etc/ssl/private/rdpgw.key;

    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;
    }

    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_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;

        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_buffering off;

        proxy_pass http://rdpgw;
    }
}
```

--------------------------------

### Interact with RDPGW HTTP API

Source: https://context7.com/bolkedebruin/rdpgw/llms.txt

Provides common curl commands to interact with RDPGW endpoints for connection initiation, token verification, metrics retrieval, and host management.

```bash
curl -L https://rdpgw.example.com/connect
curl "https://rdpgw.example.com/tokeninfo?access_token=<jwt_token>"
curl https://rdpgw.example.com/metrics
curl -H "Authorization: Bearer <token>" https://rdpgw.example.com/api/v1/hosts
curl -H "Authorization: Bearer <token>" https://rdpgw.example.com/api/v1/user
curl -X POST https://rdpgw.example.com/KdcProxy
```

--------------------------------

### Configure Conditional Access Policy

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/ms-app-proxy-deployment.md

PowerShell snippet defining the conditions and grant controls for a Conditional Access Policy to secure the RDPGW application.

```powershell
$conditions = @{
    "applications" = @{
        "includeApplications" = @($app.ApplicationId)
    }
    "users" = @{
        "includeGroups" = @("rdp-users-group-id")
    }
    "locations" = @{
        "includeLocations" = @("AllTrusted")
    }
}

$grantControls = @{
    "operator" = "OR"
    "builtInControls" = @("mfa", "compliantDevice")
}
```

--------------------------------

### API Endpoints

Source: https://github.com/bolkedebruin/rdpgw/blob/master/cmd/rdpgw/templates/README.md

The RDP Gateway web interface utilizes several authenticated API endpoints to fetch server lists, user information, and RDP connection details.

```APIDOC
## GET /api/hosts

### Description
Returns a list of available servers for the authenticated user in JSON format.

### Method
GET

### Endpoint
/api/hosts

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **servers** (array) - A list of server objects, each containing server details.

#### Response Example
```json
[
  {
    "name": "Server1",
    "address": "192.168.1.100"
  },
  {
    "name": "Server2",
    "address": "192.168.1.101"
  }
]
```

## GET /api/user

### Description
Returns information about the currently authenticated user in JSON format.

### Method
GET

### Endpoint
/api/user

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **username** (string) - The username of the current user.
- **groups** (array) - A list of groups the user belongs to.

#### Response Example
```json
{
  "username": "user1",
  "groups": ["admin", "users"]
}
```

## GET /api/rdp-content

### Description
Generates and returns the RDP file content as plain text. This is used for the auto-launch functionality of the RDP client.

### Method
GET

### Endpoint
/api/rdp-content

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **RDP File Content** (text/plain) - The raw content of the RDP file.

#### Response Example
```text
full address:s:server.example.com:3389
...
```

## GET /connect

### Description
This is a traditional endpoint that initiates the download of an RDP file, allowing users to connect to a remote desktop session.

### Method
GET

### Endpoint
/connect

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **RDP File** (application/rdp) - A downloadable RDP file.

#### Response Example
(A file download prompt will appear in the browser.)
```

--------------------------------

### Azure App Proxy JSON Configuration

Source: https://github.com/bolkedebruin/rdpgw/blob/master/docs/header-authentication.md

JSON representation of the Azure Application Proxy settings, including internal/external URLs and passthrough paths for the RDP gateway.

```json
{
  "name": "RDPGW",
  "internalUrl": "http://rdpgw-internal",
  "externalUrl": "https://rdpgw.yourdomain.com",
  "preAuthenticatedApplication": {
    "preAuthenticationType": "AzureActiveDirectory",
    "passthroughPaths": [
      "/remoteDesktopGateway/*"
    ]
  }
}
```