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.

You'll need the Homebrew package manager. With that installed, run:

$ brew install step

Alternatively, if you wish to install without using Homebrew, you can run:

$ curl -L -o step $ sudo install -m 0755 step /usr/local/bin
$ curl -L -o step $ sudo install -m 0755 -t /usr/bin step

Run PowerShell as administrator, then download and run the installation script.

PS > curl.exe -LO PS > powershell -ExecutionPolicy Bypass -File "install-step.ps1"

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>

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.

Single Sign-On

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.

© 2020 Smallstep Labs, Inc. All rights reserved.