jump-host/docs/connecting.md

layout, title, description

layout	title	description
default	Connecting	How to reach downstream hosts through the jump host — the username grammar, the interactive picker, SFTP/WinSCP, and what access you get.

Connecting

You reach a downstream host two ways: name the target in your username, or log in plain and pick it from a menu. Either way you authenticate once, to the jump host, with your directory credentials.

The username grammar

{uid}_-_{target}

• {uid} — your directory username.
• _-_ — the separator (legal in an SSH username everywhere, including WinSCP).
• {target} — the host to reach: a directory slug (host_web01 or just web01), the host's display name, its IP, or the hostname in its directory address.

ssh alice_-_web01@jump.example.com          # by slug (host_ prefix optional)
ssh alice_-_10.0.0.10@jump.example.com      # by IP (must be a host you can reach)

If the target matches a host your directory groups grant, you're bridged straight to its sshd — same as if you'd SSH'd directly, but through the audited jump host.

SFTP / WinSCP / scp

Because the whole route is encoded in the username, file transfer tools that only take one connection string work with no extra configuration:

sftp -P 2222 alice_-_web01@jump.example.com
scp -P 2222 file.txt alice_-_web01@jump.example.com:/tmp/

WinSCP: set Host name to jump.example.com, Port to 2222, and User name to alice_-_web01. SFTP is bridged as an opaque byte stream, so all operations (browse, upload, download, rename) work normally.

The interactive picker

Log in with just your username and you get a TUI list of every host you can reach:

ssh alice@jump.example.com

• ↑ / ↓ move the selection
• type to filter the list incrementally
• Enter connect to the highlighted host
• number keys jump straight to that row
• q or Ctrl-C to quit

Pick a host and you're bridged into it. The picker only ever lists hosts your directory access allows — it doubles as "what can I reach from here?"

What you can reach

The set of hosts is computed per login: your LDAP group memberships intersected with the SSO directory's catalog hosts (via the host_<name>_access groups the directory auto-creates for each machine). To get access to a new host, an admin adds you to that host's access group in the SSO — nothing on the jump host changes.

Targets that don't resolve to a host you're allowed to reach are refused (and audited). Raw IPs that aren't a known directory host are denied by default.

Only catalog hosts are jump targets. A machine that the SSO merely discovered — a Proxmox guest, a UniFi client — is not a jump target until an admin promotes it into the directory catalog. The jump host applies the same rule the SSO's own Directory listing does: a resource carrying discovery_sources but never promoted is excluded, while hand-created hosts and promoted ones are included. Previously the filter treated a missing managed flag as permission, so unpromoted discovery results showed up in the picker.

On a standalone jump host (no LDAP/SSO), every registered host is reachable by every registered user — there's no group-based restriction to ask an admin about.

Authentication

The jump host authenticates you against the directory:

• Public key — matched against your sshPublicKey entries in LDAP. Use your normal SSH key; the client picks it automatically.
• Password — your directory password (LDAP bind). Password auth is often restricted to local networks or disabled entirely on a public jump host (keys-only) — check with your operator.

You never manage a separate credential for the downstream host: the jump host handles onward authentication for you (see Architecture).

First connection to a host

The very first time you reach a given downstream host, the jump host provisions its access key for you behind the scenes. If that first attempt races the directory's key-cache refresh you may see a brief

jump-host: first-time key propagation, retrying…

and it reconnects automatically. Subsequent connections are immediate.