​
Concept

Infisical SSH can be configured to provide users on your team short-lived, secure SSH access to infrastructure. Under the hood, it uses SSH certificates and improves upon traditional SSH key-based authentication by mitigating private key compromise, static key management, unauthorized access, and SSH key sprawl.

The following entities are important to understand when configuring and using Infisical SSH:

  • Administrator: An individual on your team who is responsible for configuring Infisical SSH.
  • Users: Other individuals that gain access to remote hosts through Infisical SSH.
  • Host: A remote machine (e.g. EC2 instance, GCP VM, Azure VM, on-prem Linux server, Raspberry Pi, VMware VM, etc.) that users need SSH access to that is registered with Infisical SSH.

​
Workflow

The typical workflow for using Infisical SSH consists of the following steps:

  1. The administrator registers a remote host with Infisical using the Infisical CLI via the infisical ssh add-host command.
  2. The administrator configures Infisical SSH to grant users access to the remote host.
  3. User(s) access the remote host using the Infisical CLI via the infisical ssh connect command.

​
Admin Guide for Configuring Infisical SSH

In the following steps, we explore how to configure Infisical SSH to control and streamline your team’s SSH access to infrastructure. As part of this guide, we will register a remote host with Infisical through a machine identity and configure Infisical to grant user(s) access to the remote host.

1

Create an Infisical SSH project

Start by creating a new Infisical SSH project in Infisical.

2

Create a machine identity for bootstrapping Infisical SSH

2.1. Follow the instructions here to configure a machine identity in Infisical with Universal Auth.

By the end of this step, you should have a Client ID and Client Secret on hand as part of the Universal Auth configuration for the identity to authenticate with Infisical as part of registering a remote host in step 3.

You may use other authentication methods as suitable (e.g. AWS Auth, Azure Auth, GCP Auth, etc.) as part of the machine identity configuration but, to keep this example simple, we will be using Universal Auth.

2.2. Add the machine identity to the Infisical SSH project you created in the previous step and assign it the SSH Host Bootstrapper role.

This role grants the ability to Create and Issue Host Certificates on the SSH Host resource; this will enable the linked machine identity to bootstrap a remote host with Infisical and establish the necessary configuration on it.

If you plan to use a custom role to bootstrap SSH hosts, ensure the role has the Create and Issue Host Certificates on the SSH Host resource.

3

Configure the remote host

3.1. Follow the instructions here to install the Infisical CLI onto the remote host.

3.2. Run the commands below to register the remote host with Infisical.

Use the Client ID and Client Secret from the machine identity you created in step 2.1 as part of the infisical login command to obtain an access token and save it as an environment variable.

export INFISICAL_TOKEN=$(infisical login --method=universal-auth --client-id=<identity-client-id> --client-secret=<identity-client-secret> --silent --plain)

Next, use the infisical ssh add-host command to register the remote host with Infisical. As part of this command, input the ID of the Infisical SSH project you created in step 1 for the --projectId flag and the hostname of the remote host for the --hostname flag.

sudo infisical ssh add-host --projectId=<project-id> --hostname=<hostname> --token="$INFISICAL_TOKEN" --write-user-ca-to-file --write-host-cert-to-file --configure-sshd

Note that if you’re self-hosting Infisical, you can use the --domain flag on the infisical login command to specify the domain of your Infisical instance.

For more information on the infisical ssh add-host command, please refer to the Infisical CLI documentation.

If successful, you should see output similar to the following:

✅ Successfully registered host: <hostname>
📁 Wrote User CA public key to: /etc/ssh/infisical_user_ca.pub
📁 Wrote host certificate to: /etc/ssh/ssh_host_ed25519_key-cert.pub
📄 Updated sshd_config entries

Finally, use the following command to reload the SSH daemon on the remote host to apply the changes:

sudo systemctl reload sshd

The command may differ depending on the host. For older versions of Ubuntu/Debian/CentOS, you may need to use sudo service ssh reload instead; for Alpine or minimal systems, /etc/init.d/sshd reload.

Back in Infisical, you should now see the remote host you just registered in the Infisical SSH project you created in step 1 under the Hosts tab.

4

Grant users access to the remote host

4.1. Add the user(s) you wish to grant access to the remote host to the Infisical SSH project under Access Control > Users.

4.2. On the registered host in the Hosts tab, click Edit SSH Host and add a login mapping for the user(s) you added in step 4.1.

The login mapping dictates what user(s) will be allowed access to the remote host and under a specific login user; in the allowed principals, you should select user(s) part of the Infisical SSH project that will be allowed to login to the remote host as the login user.

For instance, if you add a mapping with the login user ec2-user to some users John and Alice in Infisical, then they will be allowed to login to the remote host as ec2-user which is a system user that exists on the remote host.

Note that you should configure authorized principals files for each login user you add to the remote host.

​
User Guide for SSHing to a Host

Once Infisical SSH is configured by an administrator, users can SSH to the remote host using the Infisical CLI.

1

Install the Infisical CLI

Follow the instructions here to install the Infisical CLI onto your local machine.

2

Connect to the remote host

The infisical ssh connect command can be used in either interactive or non-interactive mode to connect to a remote host.

In interactive mode, you’ll first need to authenticate with Infisical by running:

infisical login

Then simply run:

infisical ssh connect

You’ll be prompted to select an SSH Host from a list of accessible hosts; this is based on project membership and login mappings configured on hosts by the administrator.

Use the arrow keys to navigate: ↓ ↑ → ←
? Select an SSH Host:
▸ ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com

After selecting a host, you’ll be prompted to select a login user from a list of allowed login users:

? Select Login User:
▸ ec2-user

If successful, you should be able to SSH to the remote host.

✔ ec2-54-199-104-116.ap-northeast-1.compute.amazonaws.com
✔ ec2-user
✔ SSH credentials successfully added to agent
Connecting to [email protected]...