Skip to content
Integrations
Operations
Session Recording
Getting Started

Getting Started

Overview

This integration pairs the Britive Access Broker with Apache Guacamole to deliver clientless, browser-based SSH and RDP sessions that are recorded to video. Britive curates each session — it’s short-lived and the credentials are rotated by the broker — so end users never install tools or copy credentials. Guacamole’s guacd daemon opens the actual RDP/SSH connection and streams it to the browser over WebSocket.

What you’ll accomplish:

  • Stand up the Guacamole + broker stack with your chosen deployment method
  • Wire the broker checkout routines that mint signed, encrypted Guacamole tokens
  • Verify a recorded session end-to-end

How It Works 

    sequenceDiagram
    actor User
    participant Britive
    participant Guacamole
    participant guacd
    participant Target as Target Host
    participant S3 as Amazon S3

    User->>Guacamole: Open web UI in browser
    Britive->>Guacamole: Checkout mints signed+encrypted token (encrypt-token.sh)
    Guacamole->>guacd: Pass connection params
    guacd->>Target: Open RDP/SSH connection
    guacd->>guacd: Encode session to WebSocket stream + record to disk
    guacd-->>S3: Recording (.guac) optionally converted to .m4v and synced

The connection is made by guacd, not the browser — so guacd must have network access to the target host.

Before You Begin

  • The Access Broker is deployed and connected (or use a deployment method below that bundles it)
  • Docker, plus AWS CLI for the cloud options
  • The britive-broker-2.0.0.jar file for the broker container
  • A Britive tenant subdomain and broker pool token

The Guacamole JSON auth uses a shared JSON_SECRET_KEY. Treat it like any other secret — generate it securely and keep it out of source control.

Choose a Deployment Method

MethodBest for
Docker ComposeLocal development, single-host setups
CloudFormationAWS production via declarative IaC
ECS FargateAWS production via automated script

The stack runs four services: broker (Access Broker + SSH server), guacd (protocol daemon), guacamole (web UI), and guacenc (converts .guac recordings to .m4v).

Generate a JSON secret key 

echo -n "your-passphrase" | md5sum   # Linux  (use `md5` on macOS)

Set the key in the compose file

docker/docker-compose.yaml
guacamole:
  environment:
    JSON_SECRET_KEY: "<your-key>"

Set broker config

Edit docker/broker/broker-config.yml with your tenant subdomain and broker token.

Build and start 

cd docker/
mkdir -m a+rw recordings
docker build -t broker-docker .
docker compose up -d

Broker Checkout Routines

The broker mints a signed, encrypted Guacamole token at checkout. Scripts live in session-recording/broker-scripts:

ScriptPurpose
checkout-generic.shGeneric token generator — accepts a full connection JSON
ssh/checkout-ssh.shSSH checkout — creates user, key pair, and token
rdp/checkout-rdp.ps1 / rdp/checkin-rdp.ps1RDP checkout/checkin — temporary local admin user
ssh/checkout-ec2-ssh.sh / rdp/checkout-ec2-rdp.shEC2 variants — pull keys from Secrets Manager

encrypt-token.sh signs (HMAC-SHA256) and encrypts (AES-128-CBC) the connection JSON into a URL-encoded token:

session-recording/encrypt-token.sh
# Generate a JSON secret key
echo -n "britiveallthethings" | md5    # → fb57d11d533339aea1e37c2a5a1cb92c

# Encrypt a connection token
./encrypt-token.sh fb57d11d533339aea1e37c2a5a1cb92c example_user.json

# Browser opens: https://guacamole.example.com/guacamole?data=<token>

A connection JSON sets the protocol, target, credentials, and recording path:

example_user.json
{
  "username": "first.last@britive.com",
  "expires": "1750000000000",
  "connections": {
    "my-ssh-session": {
      "protocol": "ssh",
      "parameters": {
        "hostname": "1.2.3.4",
        "port": "22",
        "username": "ubuntu",
        "private-key": "...",
        "recording-path": "/recordings",
        "recording-name": "${GUAC_DATE}-${GUAC_TIME}-${GUAC_USERNAME}-my-ssh-session"
      }
    }
  }
}

Verify

Check out the profile

In My Access, check out the session-recording profile. The response contains a Guacamole URL with a ?data=<token> parameter.

Open the session

Open the URL in a browser. The SSH/RDP session loads in-page — no plugin or client.

Confirm the recording

After the session ends, check the recordings location (/recordings, the EFS mount, or the S3 bucket if GuacSync is enabled). A .guac file (or converted .m4v) is present.

Troubleshoot

SymptomCauseFix
Token rejected / blank loginJSON_SECRET_KEY mismatchThe key used by encrypt-token.sh must match the Guacamole container’s JSON_SECRET_KEY
Session fails to connectguacd can’t reach the targetEnsure guacd has network access to the target host’s RDP/SSH port
No recording producedrecording-path missing or not writableSet recording-path in the connection JSON; ensure the directory exists and is writable
.guac not converted to .m4vGuacSync not deployedEnable guacenc (Docker) or --enable-guacsync + --s3-bucket (Fargate)
Broker not connectedBad tenant/tokenVerify BRITIVE_TENANT (subdomain only) and BRITIVE_TOKEN

Next Steps

Last updated on