awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Complete preliminary ssh host group feature

Browse Source
This commit is contained in:
Tuan Dang
2025-04-30 18:14:31 -07:00
parent b06eeb0d40
commit b21b0b340b
46 changed files with 561 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/documentation/platform/ssh/host-groups.mdx Normal file
View File

@@ -0,0 +1,56 @@
---
title: "Infisical SSH"
sidebarTitle: "Host Groups"
description: "Learn how to organize SSH hosts into groups and manage access policies at scale."
---
## Concept
Infisical SSH lets you configure host groups to organize and manage multiple SSH hosts with shared access configuration.
These host groups can be created based on environments (`development`, `staging`, `production`), geographical regions (`us-east`, `eu-west`, `ap-northeast`), or functions (`web-servers`, `database-servers`, `worker-nodes`) to streamline access management across your infrastructure.
Using a host group, you can define login mappings at the group level and have them be applied to all hosts assigned to that group. For example, you can specify that `john@acme.com` can login as `ubuntu` on all hosts assigned to the `production` host group.
## Workflow
The typical workflow for using Infisical SSH with host groups consists of the following steps:
1. The administrator creates host groups based on logical groupings (environments, regions, functions, etc.).
2. The administrator configures login mappings at the host group level to define access policies.
3. The administrator registers remote hosts with Infisical using the Infisical CLI via the `infisical ssh add-host` command and assigns them to appropriate host groups either using the `--host-group` flag or by adding them to the host group via UI.
4. User(s) access the remote hosts using the Infisical CLI via the `infisical ssh connect` command, with access determined by the login mappings defined at both host and host group levels.
## Admin Guide for Configuring Host Groups
In the following steps, we'll walk through how to create and configure Host Groups in Infisical SSH, and how to add hosts to these groups.
<Steps>
<Step title="Create a host group">
1.1. Navigate to your Infisical SSH project and select the **Hosts** tab.
1.2. Click **Add Group** in the **Host Groups** section to create a new group.
Enter a name (e.g., `production-servers` or `tokyo-region`) and login mapping(s) for the host group.
A login mapping for a host group applies to all hosts assigned to the group and dictates what user(s) will be allowed access to the remote hosts
in that group under specific login user(s); 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 to a host group with the login user `ec2-user` to some users John and Alice in Infisical, then they will be allowed to login to any remote host that is part of the group as `ec2-user` which is a system user that
exists on the remote host(s).
![ssh group add group](/images/platform/ssh/v2/ssh-group-add-group-1.png)
![ssh group add group 2](/images/platform/ssh/v2/ssh-group-add-group-2.png)
1.3. Click **Add** to create the host group.
</Step>
<Step title="Add host(s) to the host group">
After creating the host group, you can assign a host to it from inside the host group page in the **SSH Hosts** section. Generally, this is where you'll manage the hosts in a group.
![ssh group add group - add host](/images/platform/ssh/v2/ssh-group-add-host-1.png)
![ssh group add group - added host](/images/platform/ssh/v2/ssh-group-add-host-2.png)
</Step>
</Steps>

201
docs/documentation/platform/ssh/overview.mdx Normal file
View File

@@ -0,0 +1,201 @@
---
title: "Infisical SSH"
sidebarTitle: "Overview"
description: "Learn how to securely provision user SSH access to your infrastructure using SSH certificates."
---
## 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](/documentation/platform/identities/machine-identities) and configure Infisical to grant user(s) access to the remote host.
<Steps>
<Step title="Create an Infisical SSH project">
1.1. Start by creating a new Infisical SSH project in Infisical.
![ssh project create](/images/platform/ssh/v2/ssh-create-project.png)
1.2. Create a custom role in the project under Access Control > Project Roles to grant the machine identity that we will create in step 2 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.
![ssh custom role bootstrap 1](/images/platform/ssh/v2/ssh-add-bootstrap-role-1.png)
![ssh custom role bootstrap 2](/images/platform/ssh/v2/ssh-add-bootstrap-role-2.png)
</Step>
<Step title="Create a machine identity for bootstrapping Infisical SSH">
2.1. Follow the instructions [here](/documentation/platform/identities/universal-auth) to configure a [machine identity](/documentation/platform/identities/machine-identities) 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.
<Note>
You may use other authentication methods as suitable (e.g. [AWS Auth](/documentation/platform/identities/aws-auth), [Azure Auth](/documentation/platform/identities/azure-auth), [GCP Auth](/documentation/platform/identities/gcp-auth), etc.) as part of the machine identity configuration but, to keep this example simple, we will be using Universal Auth.
</Note>
2.2. Add the machine identity to the Infisical SSH project you created in the previous step and assign it the custom role you created in step 1.2.
![ssh add identity to project](/images/platform/ssh/v2/ssh-add-identity-to-project.png)
</Step>
<Step title="Configure the remote host">
3.1. Follow the instructions [here](/cli/overview) 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.
```bash
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.
```bash
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
```
<Tip>
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](/cli/overview).
</Tip>
If successful, you should see output similar to the following:
```bash
✅ 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:
```bash
sudo systemctl reload sshd
```
<Note>
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`.
</Note>
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.
![ssh hosts](/images/platform/ssh/v2/ssh-added-hosts.png)
</Step>
<Step title="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.
![ssh hosts](/images/platform/ssh/v2/ssh-add-user.png)
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.
![ssh host mappings](/images/platform/ssh/v2/ssh-host-login-mappings.png)
<Note>
Note that you should configure authorized principals files for each login user you add to the remote host.
</Note>
</Step>
</Steps>
## 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.
<Steps>
<Step title="Install the Infisical CLI">
Follow the instructions [here](/cli/overview) to install the Infisical CLI onto your local machine.
</Step>
<Step title="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.
<Tabs>
<Tab title="Interactive Mode">
In interactive mode, you'll first need to authenticate with Infisical by running:
```bash
infisical login
```
Then simply run:
```bash
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.
```bash
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:
```bash
? Select Login User:
▸ ec2-user
```
If successful, you should be able to SSH to the remote host.
```bash
✔ ec2-54-199-104-116.ap-northeast-1.compute.amazonaws.com
✔ ec2-user
✔ SSH credentials successfully added to agent
Connecting to ec2-user@ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com...
```
</Tab>
<Tab title="Non-Interactive Mode">
For CI/CD pipelines or automation scenarios, you can use the non-interactive mode with an Infisical token:
```bash
infisical ssh connect \
--hostname ec2-12-345-678-910.ap-northeast-1.compute.amazonaws.com \
--login-user ec2-user \
--out-file-path ~/.ssh/id_rsa-cert.pub \
--token <your-infisical-token>
```
This will:
- Connect to the specified hostname
- Use the specified login user
- Write the SSH credentials to the specified path instead of adding them to the SSH agent
- Authenticate using the provided Infisical token
</Tab>
</Tabs>
</Step>
</Steps>