PAM Broker and browser access

How it works

Setting up a brokered host is a one-time admin step. The relay connects to the host, shows you the host key or certificate it saw, checks the password works, and then stores it sealed with its own passphrase. The password you type during setup goes to the relay only: the app does not keep it, and it is never synced through the vault.

From then on, every connection goes through three steps:

1. MangoSSH asks your vault server for a ticket: a signed statement that this device may use this one host. A connect ticket is valid for 60 seconds, and a fresh one is fetched for every attempt.
2. It presents the ticket to the relay. The relay checks the signature with the vault server's public key. It needs no copy of your members or roles.
3. The relay unseals the stored credential and signs in to the host itself. The person connecting gets a terminal or a screen, never the password.

The vault server never sees the password either. It only decides who may use which host, using the same visibility rules as ordinary vault sync.

SSH, RDP and VNC are not the same

The relay does a different job for each protocol, and that changes what it can promise.

SSH brokering signs in with a password, so the target account needs password authentication. A brokered RDP session has no clipboard channel and no shared folders.

What you need

• A Self Hosting Vault with TICKET_SIGNING_KEY set. Without it the vault server answers “PAM broker is not configured on this server”.
• A relay with BROKER_TRUST_PUBKEY set to the matching public key, and RELAY_BROKER_CACHE_PASSPHRASE set. That passphrase seals every stored credential and every server-side RDP recording.
• The relay URL in Settings → Relay Server on each device that sets up or connects.
• The host shared through the vault, and your device an Admin of that vault. Only an admin can provision a host. Any member who can see the host, Operator included, can then connect.
• A network path from the relay to the host. If the host is behind NAT, use a host agent.

If you installed both servers from the self-hosting bundles, the keys already exist: the vault installer generates the pair and the relay installer generates its passphrase. On one machine they are linked automatically. On two machines, copy the BROKER_TRUST_PUBKEY=… line from the vault server's .env into the relay's and restart the relay (see the relay guide).

To make a new pair yourself, run sudo docker run --rm mangossh-cloud-server:VERSION mangossh-cloud-server keygen on the vault server. TICKET_SIGNING_KEY (the private half, which signs tickets) goes in the vault server's .env; BROKER_TRUST_PUBKEY (the public half, which verifies them) goes in the relay's. Back up RELAY_BROKER_CACHE_PASSPHRASE: without it the relay cannot open the credentials or recordings it already holds.

Set up a host

Everything happens in one dialog. Right-click the host and choose Set up browser access…. For an SSH host you can also open Edit → Access and click Set Up Browser Access….

The dialog has five steps down the left: Vault, Relay, Target, Share and Certificates. A step shows ✓ when it is done and ! when something blocks it. A blocked step always says why and offers the fix.

1. Vault. Checks that a vault is set up on this device, that this device is an admin, and that the host is shared through it. If it is not shared yet, click Share this host through the vault. Sharing sends the host record; its password stays on this device unless you turned on secret sync.

2. Relay. Enter the Relay URL, for example ws://relay.example.com:8878/v1/session (or a wss:// address if your relay sits behind HTTPS), and click Test Connection. It is the same value as Settings → Relay Server, and testing saves it there.

3. Target. Fill in Target host, Port, Username and Password. They are prefilled from the host. For RDP there is also Domain (optional); leave it blank for a local account.

   Enter the address the relay uses to reach the host. That is not always the one you use. If the relay runs in Docker, on another network, or behind a jump host, it may need a container name or an internal IP instead.

4. Click 1 · Check host key. The relay connects and shows the SSH host key (or, for RDP, the TLS certificate) it saw. Compare it the way you would a first-connect prompt.

5. Click 2 · Provision. The relay reconnects, refuses to continue unless the key matches the one you confirmed, verifies the password, and only then seals and stores it. Every later connection is pinned to that key. A toast confirms “Credential sealed on the relay”.

6. RDP only: before provisioning, decide on Record every session brokered through this host. The relay enforces it, not the connecting device. Someone opening a link cannot turn it off or tell that it is on. See Audit, recording and alerts.

For a VNC host the Target step asks only for the address and has a single Provision button. The relay checks it can reach the address and that a VNC server answers before it stores anything. There is no username or password, because the recipient types the VNC password.

The last step, Certificates, is a separate and optional feature: short-lived SSH certificates from the vault's CA instead of a stored password. You can use the broker, certificates, both or neither. See SSH certificates.

Direct mode (RDP only)

For an RDP host the wizard opens with a choice, How should the browser reach this host?

• Brokered: the relay logs in and the viewer never sees the credential. This is everything on this page.
• Direct: the browser speaks RDP to the host through that machine's own agent, and the viewer signs in with the Windows login. No vault and no stored credential. The target needs Connect by ID turned on with the RDP backend. You enter its Remote ID and connect password, and Copy Link — Valid ~2 min gives you a link for one browser session. See Remote access by ID.

Connect to a brokered host

Once provisioned, the host is marked as brokered and connecting looks like any other host: double-click it. There is no password prompt, because this device has no password for it.

• SSH. The session runs on the relay. Closing the tab disconnects you from it, but the relay keeps the SSH connection open until nobody has been attached for its idle timeout (IDLE_TIMEOUT_SECS, 900 seconds by default). Connecting again from the app opens a new session. A browser link is different: reloading the page reattaches to the same session with the recent output replayed. A session can only ever be attached by the device that opened it; another member gets a session of their own.
• RDP. The relay streams the desktop into the normal RDP view. The session ends when you disconnect.
• If your vault requires a JIT grant for brokered access, a non-admin sees the Request Access dialog first. See below.

Every connection is attributed to the device that asked for the ticket, which is how the PAM Dashboard can say who is connected where.

Share a browser link

A browser link gives someone one session on one host, in a plain browser tab. There is nothing to install and, for SSH and RDP, no password to send.

1. Quick way: right-click a brokered host and choose Share browser access…. MangoSSH copies a single-use link that is valid for one hour.

2. With options: open the wizard's Share step. Single use is on by default. Click Copy Link — Valid 1 Hour. The link is copied and also shown in a box, in case the clipboard is unavailable.

3. Send it. For VNC, send the VNC password by a different channel.

Links open /s/… (a terminal) for SSH, /r/… (a desktop) for RDP and /v/… for VNC, on your relay's address. When the page loads it moves the ticket out of the address bar into the tab's own storage, so it does not linger in history or get passed on in a Referer header. Reloading an SSH page reattaches to the same session.

• Single use means single holder. The first browser tab to open the link keeps it. That tab can reload and reconnect. Anyone else who gets the link is refused with “this share link has already been used by someone else — ask for a new one”. With Single use off, anyone holding the link can use it until it expires.
• Any member can share. A member who can connect to a brokered host can share it, not just an admin. The link carries the sharer's device, so every session it opens is attributed to them, and it appears in the issued-link list.
• Links end with the grant. If your vault requires a JIT grant, a link cannot outlast the sharer's grant.

Revoke links and see what was issued

Every link is recorded on the vault server before it is handed out, so none can exist without a record.

• Right after sharing: the wizard's Share step has Revoke This Link. Holding the link is proof enough, so you do not need to be an admin.
• Later: open the PAM Dashboard (PAM Dashboard in the Dashboard's side rail) and choose Browser share links. Each row shows the host, who shared it, whether it is single use or reusable, its status (Active, Expired or Revoked) and when it was issued. Admins see every link in the vault and can Revoke any active one. Members see only their own.

Revoking takes effect on the relay at once: the link stops working and any session it opened is ended. The relay remembers claimed and revoked links across restarts, so a restart cannot bring a link back.

To stop brokering a host entirely, open Edit → Access and click Disable PAM Broker…. The relay deletes the credential, every link for the host stops working, and the host becomes a normal SSH host again. This device has no password for it, so enter one under Authentication before you connect directly.

Reach a host behind NAT through a host agent

Normally the relay opens a connection straight to the target. If the target is behind a home router or a corporate NAT, the relay can instead reach it through a MangoSSH host agent running on that network. This works for SSH, RDP and VNC.

1. In the wizard's Target step, turn on Reach it through a host agent (target behind NAT).

2. Enter the agent's Agent ID (its 9-digit Remote ID) and Agent password. The password is sealed on the relay next to the target credential and not kept by the app.

3. Set Target host to the address as the agent sees it: 127.0.0.1 for the agent's own machine, or a LAN address for another machine on its network.

4. Continue with Check host key and Provision as usual. Both go through the agent, so the key you confirm is the one seen on that path.

The agent has four rules, and they are the security boundary:

Require approval for brokered access

A brokered host holds no credential on the connecting device, so the ticket is the only way in. That makes it the right place to enforce just-in-time access, on the server rather than in the app.

Turn on Require an approved grant for brokered and shared access in the PAM Dashboard, under Pending requests → Approval security. The same switch is on the Policies page under Global. Then:

• The vault server issues no broker ticket and no browser link to a non-admin who lacks an active grant for that host. Admins are exempt, since they approve grants.
• A ticket or link that is issued ends when the grant does, and the relay closes the session at that moment.
• When a non-admin connects from the app, MangoSSH asks for the grant up front with the Request Access dialog, rather than failing on a bare refusal.

Tickets and links are also subject to device posture (an encrypted disk) and, when required, a recent single sign-on. A policy can also flag hosts that should be brokered with Require the PAM broker; the app warns when such a host is not.

The PAM Dashboard

Open PAM Dashboard from the Dashboard's side rail. It shows one section at a time, grouped down its own rail. The parts that matter for the broker:

The other sections (discovered accounts, credential rotation, stale credentials, password strength, shared accounts, recording coverage and audit evidence) cover credential hygiene and evidence rather than the broker. Most fleet views need a vault, and the relay views need Settings → Relay Server set on your device.

Troubleshooting