Skip to content
ssoossh

Illustrated walkthrough

A friendly guide to certificate-based SSH login: the same flow as interactive user certificates, told from the outside, one screen at a time. Nothing here is configuration. If you have just been told your company uses ssoossh, start here.

Step 1: You type the command

Section titled “Step 1: You type the command”
$ ssoossh ssh loginApprove this request in your browser:https://ssh.company.com/approve/7f3c…Waiting for approval…

Open your terminal and run ssoossh ssh login, or just ssh host if it is set up in your ssh_config.

If you already hold a valid certificate, the client reuses it and you are done with no browser at all. Otherwise it generates a fresh, unique keypair, sends the public key to the ssoossh server, and gets back a URL.

Your terminal prints that URL and then waits patiently. Nothing leaves your laptop except the public key: the private key stays right there, on your machine.

Section titled “Step 2: You open the link in your browser”
ssh.company.com/loginSign in to ssoosshUse your company accountContinue with SSO

Open the link your terminal printed, in any browser, even one on another device. If your administrator turned on try_open_browser, the client opens it for you.

You land on the ssoossh sign-in page. If your organisation shows a notice there, you accept it first; Continue with SSO then takes you to your company’s identity provider: the same place you log into everything else.

Nothing special happens here. You log in exactly the way you normally do, including any multi-factor step your company requires.

Step 3: You see exactly what you are approving

Section titled “Step 3: You see exactly what you are approving”
Approve certificate?GrantedSSH to prod serversExpires in 12 hoursNot allowedX11 forwarding (not permitted)Agent forwarding (not permitted)ApproveDeny

After logging in you land on an approval page. This is where ssoossh shows you the certificate it is about to issue.

In green you see what you have been granted: which servers you can log into, and how long the certificate lasts. In amber you see anything you asked for that policy does not allow, such as X11 or agent forwarding.

That difference is the point. You can see what you requested against what you are actually getting, and if something looks wrong you can deny it and ask your administrator to adjust the policy.

The real page carries more than this picture – who asked, from where, and the public key being signed – and Approving in the browser shows it as a screenshot.

Step 4: You approve, and your part is over

Section titled “Step 4: You approve, and your part is over”
Approve

You click Approve. That is it for you: the page confirms the approval and you can close it.

Meanwhile your terminal has not gone anywhere. It is still sitting on that event stream, waiting for the certificate to arrive. The server signs the certificate in the background and delivers it straight to the waiting client, so the terminal learns the outcome the moment the certificate lands. The certificate is never stored on the server, so that delivery is the only copy.

Step 5: Your certificate arrives, automatically

Section titled “Step 5: Your certificate arrives, automatically”
$ ssoossh ssh loginWaiting for approval…Certificate loadedBadgeLoaded12h

Within seconds your terminal wakes up. The server has signed your certificate: a visitor badge that says who you are, which login names (principals) you may use, and when it expires.

ssoossh loads that certificate into your local ssh-agent, the part of SSH that holds your credentials, or writes it to key files if you do not run an agent. The private key never left your laptop; the certificate just joins it.

You are now ready to connect. The whole flow takes about a minute, including the time you spent logging in.

Step 6: SSH connects and works immediately

Section titled “Step 6: SSH connects and works immediately”
Your laptopBadgepresentcertificateServerVerified

Now you run ssh prod-server.internal the way you normally would. SSH uses the certificate you just received, your visitor badge, to authenticate.

The server does not have your key stored anywhere. It trusts the badge office, which is ssoossh’s CA key. It checks the certificate’s signature, checks that the principals and constraints match what you are trying to do, and if everything holds, you are in.

No special credentials to manage, no key stored in a thousand places, no ancient key from years ago that nobody remembers.

Step 7: It expires on its own, by design

Section titled “Step 7: It expires on its own, by design”
ValidExpiredNow12 hours

Your certificate is short-lived on purpose. After its window closes it is worthless. Nobody has to revoke it and nobody has to rotate anything; it just stops working.

Next time you need a server, run the command again. You go through the same flow, get a new badge, and keep working. ssoossh reuses a certificate that has not expired yet, so you see the browser only when a new one is needed. How often that is depends on the lifetime your administrator sets: the shipped default is 30 seconds, close to once per connection, while a deployment that sets eight hours asks about once a working day.

That is the whole story. A certificate is a visitor badge, issued for a moment, checked at the door, and discarded when its time is up.

Section titled “Related”