Single Sign-On SSH

Say Goodbye to SSH Key Management

Smallstep

How Smallstep SSH Works

Smallstep delivers a complete end-to-end workflow for single sign-on SSH that combines the benefits of modern identity providers with proven standard technologies like OpenSSH and SSHD. At the core is step-ca, our Open Source certificate authority, that mints short-lived certificates for secure SSH access, and our step CLI toolkit that makes single sign-on for SSH a simple and elegant experience for users.

ssh [host-name]. Smallstep lets OpenSSH users use SSH as normal. By use of the ProxyCommand, we obtain a client certificate automatically. No host fingerprint warnings, no passwords.

ssh [host-name]. Smallstep lets OpenSSH users use SSH as normal. By use of the ProxyCommand, we obtain a client certificate automatically. No host fingerprint warnings, no passwords.

If this is the first SSH session of the day, the user visits your existing identity provider single sign flow. By default, smallstep SSH mints the user a 16-hour certificate to cover their workday. Subsequent SSH sessions won't require re-authenticating until the certificate expires.

A browser-based OIDC sign-in flow makes it easy to enforce your existing security policies, like multi-factor authentication (MFA) with FIDO U2F security keys. Users log in with a natural flow, and removing a user from your identity provider terminates their SSH access within seconds.

A browser-based OIDC sign-in flow makes it easy to enforce your existing security policies, like multi-factor authentication (MFA) with FIDO U2F security keys. Users log in with a natural flow, and removing a user from your identity provider terminates their SSH access within seconds.

Once logged in, the user is issued a certificate and connected to the host, either directly, or transparently via a bastion host. Access control is enforced at the host using standard PAM and NSS UNIX tools. Running step ssh hosts allows users to query for a list of Smallstep Managed hosts to which the user has access rights.

That's it. An effortless experience empowered by SSH certificates and the smallstep SaaS offering.

Try it free for 30 days
Say goodbye to your SSH key deploys!
Build With Open Source
Create your own single sign-on SSH certificate authority

Behind-the-scenes when a User types ssh [host-name]

First-time configuration

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.

Daily use in detail

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 from the Identity Provider that Alice identifies as for SSH (for example, alice, and alice@mycompany.com).

Finally, step stores Alice's certificate in her laptop's SSH agent. It lives in memory only, insulating users from having to manage sensitive credentials. From here, the ssh handshake continues seamlessly.

image


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.

Manage SSH Access From Your Identity Provider

All User and User Group information is maintained in your existing identity provider. We don't create yet another list of users to manage. Instead, we synchronize changes using the SCIM protocol or native APIs. You can update a User's permissions in one place, your identity provider, and it will automatically flow to the entire managed fleet of Hosts. No need to kick off automation flows to push key changes. Access is instantly added, changed, or revoked with no interaction required from the smallstep administrator.

Standard, Secure Connections

Smallstep integrates with your identity provider using industry standards like SCIM for user provisioning and OIDC for user 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.

Try it free for 30 days
Say goodbye to your SSH key deploys!
Build With Open Source
Create your own single sign-on SSH certificate authority

First-time Host configuration

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 and ACLs

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:

  • A host tag combination of db: dev gives you access to myserver #1.
  • A host tag combination of db: prod gives you access to myserver #2 and myserver #3.

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.

Access Control

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.


SSH Handshake and Host ACL Enforcement

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


image2

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

  1. Does the User have a local account: Invokes the NSS module and connects to the step-ssh agent to determine if the User is allowed to access the machine. If the User is listed, the system passes the valid UID, GID, and user name. If the User is not listed, access is denied.
  2. Determine if the principal is allowed to SSH as user name: The system compares the principal list in the User's SSH certificate with the user name provided by the NSS service. If they match (or if the User is an SSH authorized principal), the principal is allowed to SSH as user name.
  3. Determine if the user name is allowed to SSH: Invokes a PAM module to validate what permissions (SSH, Sudo, None) user name has for SSH. If SSH or Sudo, SSH access is enabled; otherwise, access is denied.

Once user access privileges are determined, the system will:

  1. Create a home directory if none exists.
  2. Audit Logging: SSH events trigger a PAM module to log session start, sudo actions, and session end activities. This event information is displayed in the smallstep UI.

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

Ongoing Operations

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.


platforms


Secure and Highly Available

The smallstep application is a SaaS offering that 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.

Setup and Configuration

User

  1. Type brew install step
  2. Run step ssh config --team [team-name]
  3. Go through an in-browser single sign-on OAuth OIDC flow to authenticate
  4. SSH as normal. When your certificate expires, you’ll authenticate through the browser again.

Identity Provider

  1. Configure the smallstep application in your Okta, Azure AD, or G Suite identity provider interface.
    1. Activate OIDC flow for single sign-on workflows
    2. Activate SCIM to synchronize user groups
  2. Assign users to SSH groups (or repurpose existing groups)
  3. Users and groups from your identity provider will display in the smallstep UI for access control assignments.

Hosts

  1. Download and install package that includes step and the step-ssh agent.
  2. Run step ca bootstrap and step ssh config --host to set up mTLS and to configure SSH to use certificates.
  3. Run step-ssh activate to start up the smallstep agent and enable the PAM and NSS modules
  4. Use step-ssh-ctl to register the Host, define the host tags, and set the bastion flag. Host setup can be automated using Ansible, Chef, Puppet, Terraform, or any scripting language.
Try it free for 30 days
Say goodbye to your SSH key deploys!
Build With Open Source
Create your own single sign-on SSH certificate authority
Question & Answer
What do I have to set up and install, and where?
Users need the step command-line utility, which depends on OpenSSH and a running ssh-agent. Windows 10, macOS, and most Linux distributions meet this prerequisite. The step ssh config command adds an Include directive to your .ssh/config file, and a .step folder to your home directory. SSH certificates live in-memory, in your ssh-agent.
What are the integration point technologies?
  • SSH certificates are held in ssh-agent
  • Users authenticate to the CA using OAuth OIDC [RFC6749; OpenID.Core]
  • The CA issues OpenSSH and X.509 certificates
  • Users auto-provisioning from your identity provider to smallstep uses SCIM [RFC7644]
  • POSIX user accounts are managed via Name Switching Service (NSS) module
  • SSH and sudo access control is managed via Pluggable Authentication Module (PAM)
  • Connections to smallstep APIs use mutually authenticated HTTPS (mTLS) with client certificates

All the integration points use open standards: OpenSSH, X509, OAuth OIDC, etc.

How does this impact my existing workflows?
It doesn’t, well, it shouldn’t. Smallstep SSH is designed to not interfere with existing SSH configurations and workflows. Most users won’t notice any change, except for being asked to login via single sign-on the first time they attempt to access a managed host each day. Because Smallstep SSH works by configuring the standard OpenSSH client, it also works with tools like git and sftp that use OpenSSH and/or respect your OpenSSH configuration. Our client-side OpenSSH configuration is targeted, via a Match directive, to only apply to hosts that we’re managing. For other hosts, your existing configuration will not be touched. On the host side, we change your SSHD configuration, add keys and install PAM modules. You will no longer need your old workflows for adding and removing users, shipping public keys (no longer necessary), or modifying sudoer lists.
What will I have to tell my users to do?
You can direct users to the Client Quickstart Guide for step-by-step onboarding instructions.
What is the purpose of Host Tags, and how are they used?

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.

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

How much lock-in am I signing up for?
You’re asking Smallstep to run a CA for you. At any point, you could choose to run the open-source step CLI tool and step-ca server in place of our service. You will need to set it up yourself, develop an SSO OAuth flow, implement directory sync, and get your hosts and users migrated to pure open-source.
What's open-source, and what isn't?
Smallstep SSH is built on two open-source tools: step and step-ca. This toolchain makes it easy to run your own certificate authority (CA) and issue, renew, and revoke SSH and X.509 certificates. Open source does not address user lifecycle management, access control, or audit logging. For the most up-to-date and complete comparison, check out the pricing page feature matrix.