Client Quick Start — Smallstep

Client Quickstart

How to configure OpenSSH to connect to smallstep managed hosts

Follow these steps to configure OpenSSH clients to connect to hosts managed by Smallstep SSH.

Install `step`

The step command-line tool configures your OpenSSH client to connect to smallstep managed hosts using single sign-on.

$ curl -L -o step https://dl.step.sm/s3/cli/ui-cli-install/step_latest_linux_amd64
$ sudo install -m 0755 -t /usr/bin step

Configure your SSH client

Ensure ssh-agent is running and use the step CLI to configure OpenSSH on your machine.

$ step ssh config --team <team-name-slug>

Troubleshooting ssh-agent

Smallstep SSH uses the ssh-agent protocol to securely manage ephemeral SSH credentials. You'll need an ssh-agent running in order to use Smallstep SSH. On macOS and many Linux distributions anssh-agent is started for you automatically.

To check whether you have an ssh-agent running already and start one if you don't, run:

if [[ ! -z "${SSH_AUTH_SOCK}" ]]; then
  echo "ssh-agent is already running"
else
  eval $(ssh-agent -s)
fi

This should launch your web browser and initiate a single sign-on flow with your identity provider.

If your web browser doesn't open automatically, you can copy the URL from the command-line and initiate single sign-on yourself.

Use SSH like normal

Once you've run step ssh config you can use ssh to connect to managed hosts like you would any other host.

$ ssh <hostname>

That's it!

Bonus Feature

You can also query for a list of available hosts using step ssh hosts. This command outputs a list of smallstep managed hosts to which you have access rights.

$ step ssh hosts

Day-to-day with Smallstep SSH

Your OpenSSH client has been configured to obtain credentials via single sign-on to connect to smallstep managed hosts. If those credentials expire, a single sign-on flow will be triggered in your web browser when you try to SSH to a smallstep managed host. Upon completion you can SSH as normal.

Subscribe to updates

Unsubscribe anytime. See our privacy policy.