Smallstep SSH How It Works

Users on macOS, Linux, and Windows 10 machines use step to configure the local OpenSSH agent to work with SSH certificates. Smallstep does not replace OpenSSH or delete existing configurations. During setup, we add a small SSH config block that only applies to Smallstep-managed hosts, ensuring continued operations with existing key-based solutions. Specifically, we add a ProxyCommand directive that checks to see if the user’s certificate needs to be renewed. If so, we'll inject the OAuth SSO flow into the ssh client flow.

Let's onboard a new user named Alice. She starts by running step ssh config --team [team-name]. She goes through an in-browser login flow with the company's identity provider (IdP), and she's ready to go.

Our step tool works alongside OpenSSH—we don't replace OpenSSH. Each workday, when Alice first runs ssh [hostname], we check in with the Smallstep CA to see if the host she's connecting to is managed in Smallstep. If so, step makes sure Alice's SSH certificate is valid. Since this is her first session of the day, she needs a new certificate. Alice signs in to your Identity Provider, which returns an OIDC bearer token to the login utility. step exchanges this token for a signed SSH certificate from Smallstep CA.

The certificate is valid for 16 hours by default, and it includes a list of Principals that Alice identifies as for SSH (for example, alice, and alice@mycompany.com). If Alice is using our GitHub integration, her GitHub username is also attached to the certificate, and she can use it to push code there. (GitHub Enterprise required)

Finally, step stores Alice's certificate in her laptop's SSH agent. It's never stored on disk.

From here, the ssh handshake continues seamlessly.

If Alice wants to connect from a different device, it's easier for her to run step ssh login (or let step ssh proxycommand run it for her transparently) than it is to extract her certificate from ssh-agent and copy it over. Bastion hosts are supported, too! You can ssh to the server using its internal DNS name, and the connection will flow through your bastion. All connection requests to the host are logged and reported in the smallstep dashboard.

All user and group information is maintained in your existing identity provider. We pull basic information from your IdP using the SCIM protocol or native APIs. In the smallstep dashboard, you'll tag groups that need SSH access. When you add or remove users in one of these groups in your IdP, it will automatically flow to your entire managed fleet of hosts. No need to kick off automation flows to push key changes. Access is instantly added, changed, or revoked.

Smallstep integrates with your identity provider using SCIM for user provisioning and OIDC for authentication. Users and hosts are issued both SSH and X.509 certificates (for securing interaction with smallstep's APIs using mTLS). The client API is used to determine if a host is managed, to discover bastions, and for other service-related requests.

Operators run step ca bootstrap and step ssh config --host to set up mTLS and to configure sshd to use certificates. Similar to User settings, we add our information to the end of the existing sshd configuration, ensuring continued operations with existing key-based solutions. This operation also instantiates the step-ssh agent, which is configured automatically to run via systemd. At setup, native Linux NSS and PAM modules are configured by the step-ssh agent. At runtime, the agent connects to the smallstep API using mTLS and is responsible for synchronizing User and group ACLs to the Host.

With an SSH certificate in place, smallstep interacts with SSHD, PAM, and NSS UNIX services to enable access control, user lifecycle management, and detailed event logging. Smallstep provides the ability to automatically sync GID and UID values from your identity provider for each User. If not available, the application will automatically assign values.

Host tags are similar to EC2 Instance Tags. They’re used to define collections of hosts for access control. You might assign tags identifying a host’s role (e.g., bastion, web, database), region (e.g., us-east), environment (e.g., staging, production), or any other relevant attribute. Let's look at an example:

Host tags are used along with IdP user groups in grants. Grants give users in a particular identity provider group, access to hosts with a specific tag combination.

With User information synced from the identity provider and the Hosts registered, the smallstep administrator can configure access control. IdP User groups are mapped to Host Tags and given standard SSH access or root access via sudo. Access grants synchronize automatically to all Managed Hosts, and the corresponding NSS and PAM modules are updated.

Read more: Access Control Guide

Upon connection, ssh and sshd validate the authenticity of certificates using a standard exchange process:

Upon verification of the User's certificate, the system will determine access using the following workflow:

Once user access privileges are determined, the system will:

With access verified and the proper services in place, SSH access is granted, and the User can perform any needed activities on the Host.

Smallstep SSH is designed for environments that are continually changing. We automatically synchronize Users and Groups with your company directory. As an administrator, when you add or remove users in your company directory, SSH access is instantly granted or revoked on all your hosts. Changes to Hosts are simple commands that can be integrated into existing run books or automation systems. Smallstep administrators can also view session logging, Host lists and tags, User and user group lists, and configure billing information.

The Smallstep API can be used to read and manage your host access control settings programmatically. The API is currently an alpha release with limited availability. Request access to this API for your account by creating a support ticket for our Customer Engineering team. Be sure to include your team name in your request.

The Smallstep SSH SaaS offering includes a hosted certificate authority and a set of related services to enable single sign-on SSH. The smallstep application is engineered for high availability and delivered as a managed offering running on Google Cloud. We also follow industry best practices around redundancy and backups to ensure continued operations. Certificate-based authentication relies on a trusted certificate authority. CAs use a private key to sign certificates. If a CA private key falls into the wrong hands, it can be used maliciously to impersonate people, services, or machines. Smallstep uses the Google Cloud KMS service. Designed to manage private keys, KMS prevents your private key from being transferred, so it cannot be exfiltrated and used maliciously. Instead, the KMS offers a limited API that you can use for signing. Requests to this API are logged. So you always know that your private keys are secure in the KMS. Learn more about our security measures.

The same offering is available in an on-premise configuration that brings the simplicity of a SaaS offering with a private deployment's control and security. Smallstep SSH Run Anywhere installs in Kubernetes and integrates with your existing HSM for storage of private keys. Contact Us for more information.