Skip to main content
Version: vNext (upcoming release)

Secure Apache Guacamole

This guide shows you how to secure an instance of Apache Guacamole behind Pomerium using JWT Claim Headers to support HTTP header authentication. After a user authenticates against a configured identity provider, Pomerium will forward the user's email address in an unsigned HTTP header to Guacamole with the request. This setup allows for centralized, secure, and seamless authentication through Pomerium.

To complete this guide, you'll follow these steps:

  1. Install and configure Guacamole using Docker Compose.
  2. Replace the default Nginx with Pomerium in the Docker configuration.
  3. Configure Pomerium to forward identity headers to Guacamole.
  4. Securely run your setup and verify proper authentication.
note

This guide provides steps to secure access to the Guacamole gateway behind Pomerium. It does not cover how to add connections to Guacamole itself.

Before you start

To complete this guide, you need:

note

This guide uses the Hosted Authenticate Service, which provides its own hosted identity provider and authenticate service URL. If you prefer to configure your own identity provider, see Self-Hosted Authenticate Service.

Install Guacamole with Docker Compose

Installing Guacamole with Docker requires the following services:

  • guacamole/guacd: The guacd daemon, which provides support for VNC, RDP, SSH, telnet, and Kubernetes.
  • guacamole/guacamole: The Guacamole web application running within a Tomcat 8 server with websocket support.
  • mysql or postgres: The relational database that stores authentication and connection configuration data.
Security Best Practice

Ensure that environment variables containing sensitive data, such as passwords, are stored securely. Consider using Docker secrets or an .env file.

This guide uses an open-source Docker Compose configuration to install these services. This configuration file also includes an nginx instance, which you'll replace with Pomerium.

To get started:

  1. Clone the guacamole-docker-compose repository:

    git clone https://github.com/boschkundendienst/guacamole-docker-compose
  2. Go into your project and run the provided prepare.sh script. This script initializes a PostgreSQL database that works with Guacamole. (It generates also a self-signed certificate and private key for Nginx, which you can ignore.)

    cd guacamole-docker-compose
    ./prepare.sh
  3. In the guacamole container, add the following environment variables:

docker-compose.yaml
guacamole:
container_name: guacamole_compose
depends_on:
- guacd
- postgres
environment:
GUACD_HOSTNAME: guacd
POSTGRES_DATABASE: guacamole_db
POSTGRES_HOSTNAME: postgres
POSTGRES_PASSWORD: 'ChooseYourOwnPasswordHere1234'
POSTGRES_USER: guacamole_user
# Enables HTTP header authentication
HEADER_ENABLED: true
# Adds expected HTTP header from incoming Pomerium requests
HTTP_AUTH_HEADER: X-Pomerium-Claim-Email
image: guacamole/guacamole
networks:
- guacnetwork_compose
volumes:
- ./record:/record:rw
ports:
- 8080/tcp
restart: always

Configure Pomerium

In your Docker Compose file, replace nginx with Pomerium Core:

  1. Remove the nginx configuration:

    # nginx
    nginx:
    container_name: nginx_guacamole_compose
    restart: always
    image: nginx
    volumes:
    - ./nginx/templates:/etc/nginx/templates:ro
    - ./nginx/ssl/self.cert:/etc/nginx/ssl/self.cert:ro
    - ./nginx/ssl/self-ssl.key:/etc/nginx/ssl/self-ssl.key:ro
    ports:
    - 8443:443
    links:
    - guacamole
    networks: guacnetwork_compose
  2. Add the Pomerium Core configuration:

    pomerium:
    image: cr.pomerium.com/pomerium/pomerium:latest
    # Mount your config file
    volumes:
    - ./config.yaml:/pomerium/config.yaml:ro
    ports:
    - 443:443
    networks:
    - guacnetwork_compose
    environment:
    JWT_CLAIMS_HEADERS: email
  3. In line 5 above, you mount a Pomerium configuration file into Docker Compose. In your project's root directory, create a config.yaml file with the following configuration:

    Pomerium configuration file
    authenticate_service_url: https://authenticate.pomerium.app

    jwt_claim_headers: email

    routes:
    - from: https://guacamole.localhost.pomerium.io
    to: http://guacamole:8080
    policy:
    - allow:
    or:
    - email:
    is: user@example.com
    pass_identity_headers: true

    Don't forget to replace user@example.com with your own email address.

A few things to note:

  • pass_identity_headers instructs Pomerium to send the Pomerium JWT to Guacamole after the user authenticates successfully against the identity provider. You must enable this setting to forward identity headers with JWT Claims Headers.
  • jwt_claims_headers instructs Pomerium to forward additional claims as unsigned HTTP headers with the request. (Guacamole expects an incoming X-Pomerium-Claim-Email HTTP header from Pomerium.)

Run Docker Compose

Now, run Docker Compose:

docker compose up -d

Navigate to the Guacamole route defined in config.yaml by adding /guacamole to its path. For example, if your route is guacamole.localhost.pomerium.io, the route you'd access in the browser would be guacamole.localhost.pomerium.io/guacamole.

After authenticating against the configured identity provider, Pomerium will redirect you to the Guacamole dashboard:

The Guacamole dashboard after signing in with HTTP authentication

Configuration file reference

If you're stuck, the reference files below contain the configuration used to complete this guide. Compare your configuration to see if you missed something.

Docker Compose configuration reference file:

# networks
# create a network 'guacnetwork_compose' in mode 'bridged'
networks:
guacnetwork_compose:
driver: bridge
services:
# guacd
guacd:
container_name: guacd_compose
image: guacamole/guacd
networks:
- guacnetwork_compose
restart: always
volumes:
- ./drive:/drive:rw
- ./record:/record:rw

# postgres
postgres:
container_name: postgres_guacamole_compose
environment:
PGDATA: /var/lib/postgresql/data/guacamole
POSTGRES_DB: guacamole_db
POSTGRES_PASSWORD: 'ChooseYourOwnPasswordHere1234'
POSTGRES_USER: guacamole_user
image: postgres:15.2-alpine
networks:
- guacnetwork_compose
restart: always
volumes:
- ./init:/docker-entrypoint-initdb.d:z
- ./data:/var/lib/postgresql/data:Z

# guacamole
guacamole:
container_name: guacamole_compose
depends_on:
- guacd
- postgres
environment:
GUACD_HOSTNAME: guacd
POSTGRES_DATABASE: guacamole_db
POSTGRES_HOSTNAME: postgres
POSTGRES_PASSWORD: 'ChooseYourOwnPasswordHere1234'
POSTGRES_USER: guacamole_user
HEADER_ENABLED: true
HTTP_AUTH_HEADER: X-Pomerium-Claim-Email
image: guacamole/guacamole
networks:
- guacnetwork_compose
volumes:
- ./record:/record:rw
ports:
- 8080/tcp
restart: always

# pomerium
pomerium:
image: cr.pomerium.com/pomerium/pomerium:latest
volumes:
- ./config.yaml:/pomerium/config.yaml:ro
ports:
- 443:443
networks:
- guacnetwork_compose
environment:
JWT_CLAIMS_HEADERS: email

Pomerium configuration reference file:

authenticate_service_url: https://authenticate.pomerium.app

jwt_claim_headers: email

routes:
pass_identity_headers: true
- from: https://guacamole.localhost.pomerium.io
to: http://guacamole:8080
policy:
- allow:
or:
- email:
is: user@example.com
pass_identity_headers: true