Getting started

ssoossh turns a login at your identity provider into a short-lived SSH certificate. This page names the pieces, then walks the shortest path from a fresh machine to ssh bastion.example.com working. It is written for the person who will use ssoossh to connect; operators and host administrators have their own pointers at the end.

The three components

• ssoosshd – the server. It authenticates you through OIDC, decides what a certificate may carry, signs your public key, and serves the web UI where requests are approved and history is read.
• ssoossh – the client. ssh invokes it from your ssh_config; it generates a keypair, asks the server for a certificate, and loads the result into your ssh-agent (or into key files when there is no agent). Private keys never leave your machine.
• pam_ssoossh – the PAM module installed on target hosts. It puts sudo, su, and console login behind the same identity provider and the same approval, using a certificate valid for seconds and stored nowhere.

flowchart LR
    accTitle: The three components and how they connect
    accDescr {
      The user drives the ssoossh client, which sends a public key to
      ssoosshd. ssoosshd authenticates the user against an identity provider
      over OIDC, and the user approves in a browser. ssoosshd returns a signed
      certificate to the client, which presents it to the target host’s sshd.
      On that same host, pam_ssoossh talks directly to ssoosshd for sudo, su
      and console logins.
    }
    You[You] --> Client[ssoossh client]
    Client -->|public key| Server[ssoosshd]
    Server -->|OIDC login| IdP[Identity provider]
    Browser[Your browser] -->|approve| Server
    Server -->|signed certificate| Client
    Client -->|certificate| Host[Target host sshd]
    PAM[pam_ssoossh on the host] -->|sudo, su, console| Server

Before you start

This assumes an ssoosshd server is already running and reachable, with a CA key configured and an identity provider wired up. If it is not, Deployment overview is the runbook for that half.

If you would rather see the flow before running it, the illustrated walkthrough shows what steps 3 and 4 look like from the user’s chair.

1. Install the client

On Linux, install from the signed package repository – one setup step, and upgrades then come through your package manager. See Installing from the package repository for the full story, including what is and is not verified on each side.

Debian / Ubuntu

curl -fsSLO https://packages.mikenestor.org/ssoossh/apt/pool/main/all/ssoossh-release_1.4.0_all.deb
sudo dpkg -i ssoossh-release_1.4.0_all.deb
sudo apt update && sudo apt install ssoossh-client

RHEL / Fedora

sudo rpm -i https://packages.mikenestor.org/ssoossh/yum/pool/ssoossh-release_1.4.0_noarch.rpm
sudo dnf install ssoossh-client

Packages for every platform are also on the releases page.

Both packages put the binary in /usr/bin and an annotated copy of the client defaults at /etc/ssoossh/ssoossh.yaml.

Windows – run the .msi, or install it silently:

msiexec /i .\ssoossh-client_<version>_windows_amd64.msi /qn

It installs per machine into Program Files\ssoossh, adds that directory to the system PATH, and creates %ProgramData%\ssoossh for an administrator’s enforced configuration. Being per machine and silent, it deploys through Group Policy software installation, Intune and Configuration Manager unchanged.

The package is not signed yet, so Windows shows an “Unknown Publisher” prompt when you run it by hand, and a WDAC policy in enforcement will need a rule for it. Machine-managed deployment is unaffected, since those install as SYSTEM and check no publisher.

There is no arm64 installer: on windows/arm64, download the .zip and extract ssoossh.exe somewhere on PATH.

macOS

sudo installer -pkg ssoossh-client_*_darwin_arm64.pkg -target /

darwin_amd64 for an Intel Mac; the installer refuses the wrong one. It puts the binary in /usr/local/bin, its man pages under /usr/local/share/man, and the annotated defaults at /usr/local/share/ssoossh/ssoossh.yaml – a copy to start from, not one the client reads. Package and binary are both Developer ID signed and notarized, so double-clicking it works too. The .zip is still there for anyone who would rather place the binary by hand.

2. Point the client at the server

One setting has no default. Check it resolves before trying a real login:

ssoossh --server https://ssh.example.com --debug ca

The CA public key goes to stdout; --debug puts the resolved configuration report on stderr, including every config file it looked at and what came of each. To make the address permanent, put it in ssoossh.yaml instead of passing --server every time:

~/.config/ssoossh.yaml

server: "https://ssh.example.com"

Client configuration covers where that file is looked for and what else can go in it.

3. Wire up ssh_config

Match host bastion.example.com exec "ssoossh ssh login"
    User youruser

ssoossh ssh config prints this recipe and the ProxyCommand alternative, and needs no server to do it. ssh_config integration explains which of the two you want.

4. Log in

ssh bastion.example.com

The client prints an approval URL (and opens a browser if try_open_browser is set). Approve it in the browser, and ssh proceeds: the certificate is loaded into your agent and reused for every later connection until it expires. How long that is depends on cert_options.user.valid_duration: 30 seconds out of the box, so set it to the length you want, such as 8h for about one approval a working day.

If it takes more than this to get a certificate, something is wrong with the deployment rather than with you. -v says what the client did and --debug says what it resolved – see Diagnostics.

For operators

Running the server itself:

• Deployment overview – the numbered runbook.
• Installing the server – CA key and systemd.
• Identity provider – OIDC client and redirect URI.
• Find out what your provider sends. Before the first real login, run sudo -u ssoossh ssoosshd identity echo on the server host and open the link it prints. You sign in once and see your own claims, which authentication.fields entry reads each one, whether the sign-in would succeed, and YAML to copy, including a group for admin.require_group. No admin role and no working mapping are needed. See Seeing what your provider actually sends.
• TLS and reverse proxies – the two settings that fail silently until someone tries to log in.
• Configuration reference – every server key, its type, and its default.

For host admins

Making a target host accept these certificates:

• Hosts overview – what a host needs.
• Trusting the CA in sshd – the one sshd_config line.
• Installing pam_ssoossh and sudo and su – read the lockout warning before editing a real PAM stack.
• Client settings enforcement – locking client settings across a fleet.
• Directory users on a host – directory accounts that resolve on a host with nothing provisioned per host.

Where to go next

• The ssoossh client – every command and flag.
• The web UI – the rail, where each page lives, and the detail pages you can link to.
• Approving in the browser – what the approval page shows and what else the web UI holds.
• Service accounts – certificates for a backup job, a CI runner, or a cron entry.
• User FAQ – the questions that come up first.
• How it works – what is actually happening underneath.