Remote SSH Access

Overview

In the remote SSH pattern, the broker does not run scripts on itself — it connects to the target Linux host over SSH using a privileged key (e.g. an EC2 .pem file), creates the requesting user’s account if needed, and installs a per-session public key. At checkin, only the key matching the transaction ID is removed; other sessions are unaffected.

This is the right pattern when:

The broker is a separate management host and scripts run against remote servers
You need concurrent session support without session interference
You want optional PPK output for PuTTY/Windows RDP clients

Before You Begin

The broker is running and connected (see Getting Started)
The broker host has ssh, ssh-keygen, scp, and jq installed
A privileged SSH key (e.g. MYKEY.pem) is stored on the broker host at a fixed path with 600 permissions
The target Linux host accepts SSH connections from the broker using that key

How It Works

User → Britive Console → Broker → (ssh with MYKEY.pem) → Target Host → authorized_keys

Broker generates a fresh RSA key pair (never stored permanently)
Broker SSHes to the target host using the privileged key
Creates the user account if it doesn’t exist
Appends the public key with a TRX marker to authorized_keys
Returns the private key (PEM, and optionally PPK) to the user
At checkin, broker removes only the key line matching the TRX marker

Checkout Routine

Full script: Linux/permissions/temp-ssh-key-remote/checkout_remote.sh

Environment variables:

Variable	Default	Notes
`BRITIVE_USER_EMAIL`	—	Injected — user’s email, used to derive Linux username
`TRX`	—	Injected — unique transaction ID
`HOST`	—	Target server hostname or IP
`REMOTE_USER`	`ec2-user`	Privileged SSH user the broker connects as
`BRITIVE_SUDO`	`0`	Set to `1` to grant sudo on the target
`BRITIVE_HOME_ROOT`	`home`	Home directory base on the target host
`CONVERT_TO_PPK`	`1`	Set to `1` to also output PPK format (requires `puttygen`)

Generate key pair and create user on remote:

Linux/permissions/temp-ssh-key-remote/checkout_remote.sh

TMP_DIR=$(mktemp -d)
ssh-keygen -q -N '' -t rsa -C "$BRITIVE_USER_EMAIL" -f "$TMP_DIR/britive-id_rsa"

ssh -i "$REMOTE_KEY" "$REMOTE_USER@$HOST" bash -s <<EOF
  if ! id "$USERNAME" &>/dev/null; then sudo useradd -m "$USERNAME"; fi
  sudo mkdir -p /$HOME_ROOT/$USERNAME/.ssh
  sudo chmod 700 /$HOME_ROOT/$USERNAME/.ssh
  sudo chown "$USERNAME:$USERNAME" /$HOME_ROOT/$USERNAME/.ssh
EOF

Install public key with TRX marker:

Linux/permissions/temp-ssh-key-remote/checkout_remote.sh

PUB_KEY_WITH_MARKER="$(cat $TMP_DIR/britive-id_rsa.pub) # britive-$TRX"

# Push the public key to the remote host
scp -i "$REMOTE_KEY" <(echo "$PUB_KEY_WITH_MARKER") "$REMOTE_USER@$HOST:/tmp/britive-key.pub"

ssh -i "$REMOTE_KEY" "$REMOTE_USER@$HOST" bash -s <<EOF
  sudo bash -c "cat /tmp/britive-key.pub >> /$HOME_ROOT/$USERNAME/.ssh/authorized_keys"
  sudo chmod 600 /$HOME_ROOT/$USERNAME/.ssh/authorized_keys
  sudo rm -f /tmp/britive-key.pub
EOF

Return key to user (PEM + optional PPK):

Linux/permissions/temp-ssh-key-remote/checkout_remote.sh

# Output as JSON so the response template can display both formats
jq -n \
  --arg pemContent "$(tr '\n' '\\' < "$TMP_DIR/britive-id_rsa" | sed 's/\\/\\n/g')" \
  '{pemContent: $pemContent}'

rm -rf "$TMP_DIR"

Set CONVERT_TO_PPK=1 and install puttygen on the broker host to also output a .ppk key for PuTTY. The script will include ppkContent in the JSON output.

Checkin Routine

Full script: Linux/permissions/temp-ssh-key-remote/checkin_remote.sh

Removes only the authorized_keys entry tagged with the current TRX ID. Other sessions for the same user are unaffected.

Linux/permissions/temp-ssh-key-remote/checkin_remote.sh

MARKER="# britive-$TRX"

ssh -i "$REMOTE_KEY" "$REMOTE_USER@$HOST" bash -s <<EOF
  AUTHORIZED_KEYS="/$HOME_ROOT/$USERNAME/.ssh/authorized_keys"
  sudo grep -vF "$MARKER" "\$AUTHORIZED_KEYS" | sudo tee "\$AUTHORIZED_KEYS.tmp" > /dev/null
  sudo mv "\$AUTHORIZED_KEYS.tmp" "\$AUTHORIZED_KEYS"
  sudo chmod 600 "\$AUTHORIZED_KEYS"
EOF

Privileged Key Setup

The broker needs a private key to authenticate to target hosts. Store it on the broker host and lock down permissions:

# Place the key at the path referenced in the script
sudo mkdir -p /home/britivebroker
sudo cp MYKEY.pem /home/britivebroker/MYKEY.pem
sudo chown britivebroker:britivebroker /home/britivebroker/MYKEY.pem
sudo chmod 600 /home/britivebroker/MYKEY.pem

The privileged key path (REMOTE_KEY) is hardcoded in the script. Store the key in the Britive Secrets Store or a vault and inject it as an environment variable in production environments.

Configure in Britive

Create a response template

Go to Resource Manager → Response Templates → New Template. Add a field that surfaces the pemContent field from the checkout JSON output. If PPK is enabled, add a second field for ppkContent.

Create a permission

Go to Resource Manager → Resource Type Permissions → New Permission. Set Language to Shell.

Paste checkout_remote.sh and checkin_remote.sh into the respective fields.

Declare variables:

Variable	System defined	Notes
`BRITIVE_USER_EMAIL`	Yes	Injected automatically
`TRX`	Yes	Injected automatically
`HOST`	No	Set per resource
`REMOTE_USER`	No	Default `ec2-user`
`BRITIVE_SUDO`	No	`0` or `1`
`BRITIVE_HOME_ROOT`	No	Home directory base on target
`CONVERT_TO_PPK`	No	`1` to include PPK output

Under Response Templates, attach the template you created.

Create a profile

Go to Resource Manager → Profiles → New Profile. Set an expiration (e.g. 1h). Under Associations, select the resource label(s) covering the target Linux servers. Under Permissions, add the permission above.

Add a policy

Under Policies, assign members (users or tags) and set any approval or time-of-access conditions.

linux-remote-ssh.tf

# Response template — surfaces the PEM private key
resource "britive_resource_manager_response_template" "remote_ssh_key" {
name                     = "Remote-SSH-PEM-Key"
description              = "Returns SSH private key (PEM) on checkout"
show_on_ui               = true
is_console_access_enabled = false
template_data            = "Private Key (PEM):\n{{pemContent}}"
}

# Resource type — defines the LinuxServer class
resource "britive_resource_manager_resource_type" "linux" {
name        = "LinuxServer"
description = "Linux SSH server"

parameters {
  param_name   = "hostname"
  param_type   = "string"
  is_mandatory = true
}
parameters {
  param_name   = "port"
  param_type   = "string"
  is_mandatory = true
}
}

# Permission — remote checkout/checkin routines
resource "britive_resource_manager_resource_type_permission" "remote_ssh" {
name             = "Remote-SSH-TempKey-Access"
resource_type_id = britive_resource_manager_resource_type.linux.id
description      = "JIT SSH access via broker-mediated remote key installation"
code_language    = "Shell"

checkout_code_file = "${path.module}/scripts/checkout_remote.sh"
checkin_code_file  = "${path.module}/scripts/checkin_remote.sh"

variables        = ["BRITIVE_USER_EMAIL", "TRX", "HOST", "REMOTE_USER", "BRITIVE_SUDO", "BRITIVE_HOME_ROOT", "CONVERT_TO_PPK"]
response_templates = [britive_resource_manager_response_template.remote_ssh_key.name]
}

# Resource label — categorize servers by environment
resource "britive_resource_manager_resource_label" "env" {
name        = "environment"
description = "Deployment environment"
label_color = "#2563eb"

values { name = "Production";  description = "Production servers" }
values { name = "Staging";     description = "Staging servers" }
}

# Resource — a specific Linux server
resource "britive_resource_manager_resource" "web01" {
name          = "prod-web-01"
description   = "Production web server"
resource_type = britive_resource_manager_resource_type.linux.name

parameter_values = {
  hostname = "prod-web-01.internal"
  port     = "22"
}

resource_labels = {
  environment = "Production"
}
}

# Broker pool association — broker must reach the target over SSH
resource "britive_resource_manager_resource_broker_pools" "web01_pools" {
resource_id  = britive_resource_manager_resource.web01.id
broker_pools = ["pool-us-east-1"]
}

# Profile — JIT remote SSH access profile
resource "britive_resource_manager_profile" "remote_ssh" {
name                = "Linux-Remote-SSH-Access"
description         = "JIT remote SSH key access to Linux servers"
expiration_duration = 3600000   # 1 hour in milliseconds

associations {
  label_key = "environment"
  values    = ["Production"]
}
}

# Profile permission — link profile to the remote SSH permission
resource "britive_resource_manager_profile_permission" "remote_ssh" {
profile_id = britive_resource_manager_profile.remote_ssh.id
name       = britive_resource_manager_resource_type_permission.remote_ssh.name
version    = "latest"

variables {
  name              = "REMOTE_USER"
  value             = "ec2-user"
  is_system_defined = false
}
variables {
  name              = "BRITIVE_SUDO"
  value             = "0"
  is_system_defined = false
}
variables {
  name              = "BRITIVE_HOME_ROOT"
  value             = "home"
  is_system_defined = false
}
variables {
  name              = "CONVERT_TO_PPK"
  value             = "0"
  is_system_defined = false
}
}

# Profile policy — who can check out
resource "britive_resource_manager_profile_policy" "remote_ssh" {
profile_id  = britive_resource_manager_profile.remote_ssh.id
policy_name = "Remote-SSH-Access-Policy"

members = jsonencode({
  tags             = [{ name = "linux-users" }]
  users            = []
  serviceIdentities = []
  aiIdentities     = []
})

condition   = jsonencode({ ipAddress = null, timeOfAccess = null })
access_type = "Allow"
consumer    = "resourceprofile"
is_active   = true
is_draft    = false
}

Verify

Check out the profile

Navigate to My Access → find the profile → Check Out. The SSH private key (PEM) appears in the response.

Save and connect

echo "<pem-content-from-response>" > ~/britive-key.pem
chmod 600 ~/britive-key.pem
ssh -i ~/britive-key.pem jdoe@<target-host>

Check in

Return to My Access → Check In.

Confirm revocation

ssh -i ~/britive-key.pem jdoe@<target-host>
# Expected: Permission denied (publickey)

Troubleshoot

Symptom	Cause	Fix
`Permission denied` when broker connects to target	Wrong `REMOTE_KEY` path or permissions	Verify key path and `chmod 600`
User not created on first checkout	`useradd` failed (e.g. UID conflict)	Check broker logs from the SSH session; verify `REMOTE_USER` has sudo on the target
`jq: command not found`	`jq` not installed on broker	`sudo apt-get install jq` or `sudo dnf install jq`
PPK output missing	`puttygen` not installed	`sudo apt-get install putty-tools` on broker, or set `CONVERT_TO_PPK=0`
Key not removed at checkin	TRX mismatch	Britive injects the same `TRX` for both checkout and checkin — verify it is declared as a system variable

Last updated on July 8, 2026

SSH Access EC2 SSH Access (SSM)