infisical/docs/documentation/platform/ssh-old.mdx

---
title: "Infisical SSH"
sidebarTitle: "Infisical SSH"
description: "Learn how to generate SSH credentials to provide secure and centralized SSH access control for your infrastructure."
---

## Concept

Infisical can be used to issue SSH credentials to clients to provide short-lived, secure SSH access to infrastructure;
this improves on many limitations of traditional SSH key-based authentication via mitigation of private key compromise, static key management,
unauthorized access, and SSH key sprawl.

The following concepts are useful to know when working with Infisical SSH:

- SSH Certificate Authority (CA): A trusted authority that issues SSH certificates.
- Certificate Template: A set of policies bound to a SSH CA for certificates issued under that template; a CA can possess multiple templates, each with different policies for a different purpose (e.g. for admin versus developer access).
- SSH Certificate: A short-lived, credential issued by the SSH CA granting time-bound access to infrastructure.

<div align="center">

```mermaid
graph TD
    A[SSH CA]
    A --> B[Certificate Template A]
    A --> C[Certificate Template N]
    B --> D[SSH Certificate A]
    C --> E[SSH Certificate N]

```

</div>

When using Infisical SSH to provision client access to a remote host, an operator must create a SSH CA in Infisical; a certificate template under it,
specifying policies such as allowed users that can be requested under that template by a client; and configure the host to trust certificates issued by the Infisical SSH CA.

When a client needs access to a host, they authenticate with Infisical and request a SSH certificate (and optionally key pair)
to be used to access the host for a time-bound session as part of the SSH operation.

## Client Workflow

The following sequence diagram illustrates the client workflow for accessing a remote host using an SSH certificate (and optionally key pair)
supplied by Infisical.

```mermaid
sequenceDiagram
  participant Client as Client
  participant Infisical as Infisical (SSH CA)
  participant Host as Remote Host

  Note over Client,Client: Step 1: Client Authentication with Infisical
  Client->>Infisical: Send credential(s) to authenticate with Infisical

  Infisical-->>Client: Return access token

  Note over Client,Infisical: Step 2: SSH Certificate Request
  Client->>Infisical: Make authenticated request for SSH certificate via either /api/v1/ssh/issue or /api/v1/ssh/sign

  Infisical-->>Client: Return signed SSH certificate (and optionally key pair)

  Note over Client,Client: Step 3: SSH Operation
  Client->>Host: SSH into Host using the SSH certificate

  Host-->>Client: Grant access to the host
```

At a high-level, Infisical issues a signed SSH certificate to a client that can be used to access a remote host.

To be more specific:

1. The client authenticates with Infisical; this can be done using a user or machine identity [authentication method](/documentation/platform/identities/machine-identities) or a user [authentication method](/documentation/platform/identities/user-identities).
2. The client makes an authenticated request for an SSH certificate via either the `/api/v1/ssh/issue` or `/api/v1/ssh/sign` endpoints. Note that if the client wishes to use an existing SSH key pair, it can use the `/api/v1/ssh/sign` endpoint; otherwise, it can use the `/api/v1/ssh/issue` endpoint to have Infisical issue a new SSH key pair in conjunction with the certificate.
3. The client uses the issued SSH certificate (and potentially SSH key pair) to temporarily access the host.

<Note>
  Note that the workflow above requires an operator to perform additional
  configuration on the remote host to trust SSH certificates issued by
  Infisical.
</Note>

## Guide to Configuring Infisical SSH

In the following steps, we explore how to configure Infisical SSH to start issuing SSH certificates to clients as well as a remote host to trust these certificates
as part of the SSH operation.

<Steps>
  <Step title="Configuring a SSH CA for client key signing">
    1.1. Start by creating a SSH project in the SSH tab of your organization.
    
    ![ssh project create](/images/platform/ssh/ssh-project.png)
    
    1.2. Next, create a SSH CA in the **Certificate Authorities** tab of the
    project; this CA will be used for client key signing.
    
    ![ssh create client ca](/images/platform/ssh/ssh-client-create-ca-1.png)
    
    ![ssh create client ca popup](/images/platform/ssh/ssh-client-create-ca-2.png)
    
    Here's some guidance on each field:

    - Friendly Name: A friendly name for the CA; this is only for display.
    - Key Source: Whether the CA's key pair should be generated internally or supplied from an external source. Select **Internal**.
    - Key Algorithm: The type of public key algorithm and size, in bits, of the key pair for the CA. Supported key algorithms are `RSA 2048`, `RSA 4096`, `ECDSA P-256`, and `ECDSA P-384` with the default being `RSA 2048`.

  </Step>
  <Step title="Configuring a certificate template on the CA">

    2.1. Next, create a certificate template in the **Certificate Templates** section of the newly-created CA.

    A certificate template is a set of policies for certificates issued under that template; each template is bound to a specific CA.

    With certificate templates, you can specify, for example, that certificates issued under a template are only allowed for users with a specific username like `ec2-user` or perhaps that the max TTL requested cannot exceed 1 hour.

    ![ssh client create template](/images/platform/ssh/ssh-client-create-template-1.png)

    ![ssh client create template popup](/images/platform/ssh/ssh-client-create-template-2.png)

    Here's some guidance on each field:

    - SSH Template Name: A name for the certificate template; this must be a valid slug.
    - Allowed Users: A comma-separated list of valid usernames (e.g. `ec2-user`) on the remote host for which a client can request a certificate for. If you wish to allow a client to request a certificate for any username, set this to `*`; alternatively, if left blank, the template will not allow issuance of certificates under any username.
    - Allowed Hosts: A comma-separated list of valid hostnames/domains on the remote host for which a client can request a certificate for. Each item in the list can be either a wildcard hostname (e.g. `*.acme.com`), a specific hostname (e.g. `example.com`), an IPv4 address (e.g. `192.168.1.1`), or an IPv6 address. If left empty, the template will not allow any hostnames; if set to `*`, the template will allow any hostname.
    - Default TTL: The default Time-to-Live (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request. We recommend setting a shorter **Default TTL** for client certificates such as `30m`.
    - Max TTL: The maximum TTL for certificates issued under this template.
    - Allow User Certificates: Whether or not to allow issuance of user certificates; this should be set to `true`.
    - Allow Host Certificates: Whether or not to allow issuance of host certificates; this is not relevant for this step.
    - Allow Custom Key IDs: Whether or not to allow clients to specify a custom key ID to be included on the certificate as part of the certificate request.

    2.2. Finally, add the user(s) you wish to be able to request a SSH certificate to the SSH project through the **Access Control** tab.

  </Step>
  <Step title="Configuring the remote host to trust the client">
  
    3.1. Begin by downloading the client CA's public key from the CA's details section.
    
    ![ssh ca public key](/images/platform/ssh/ssh-client-ca-public-key.png)
    
    <Note>
      The CA's public key can also be retrieved programmatically via API by making a `GET` request to the endpoint [here](/api-reference/endpoints/ssh/ca/public-key).
    </Note>
    
    3.2. Next, create a file containing this public key in the SSH folder of the remote host; we'll call the file `ca.pub`.

    This would result in the file at the path `/etc/ssh/ca.pub`.

    3.3. Next, add the following lines to the `/etc/ssh/sshd_config` file on the remote host.

    ```bash
    TrustedUserCAKeys /etc/ssh/ca.pub

    PubkeyAcceptedKeyTypes=+ssh-rsa,ssh-rsa-cert-v01@openssh.com
    ```

    3.4. Finally, reload the SSH daemon on the remote host to apply the changes.

    ```bash
    sudo systemctl reload sshd
    ```

    At this point, the remote host is configured to trust SSH certificates issued by the Infisical SSH CA.

  </Step>
</Steps>

## Guide to Using Infisical SSH to Access a Host

In the following steps, we show how to obtain an SSH certificate and use it for a client to access a host via CLI:

<Note>
  The subsequent guide assumes the following prerequisites:

- SSH Agent is running: The `ssh-agent` must be actively running on the host machine.
- OpenSSH is installed: The system should have OpenSSH installed; this includes
  both the `ssh` client and `ssh-agent`.
- `SSH_AUTH_SOCK` environment variable
  is set; the `SSH_AUTH_SOCK` variable should point to the UNIX socket that
  `ssh-agent` uses for communication.

</Note>

<Steps>
  <Step title="Authenticate with Infisical">

```bash
infisical login
```

  </Step>
  <Step title="Obtain a SSH certificate for the client and load it into the SSH agent">
    Run the `infisical ssh issue-credentials` command, specifying the `--addToAgent` flag to automatically load the SSH certificate into the SSH agent.
    ```bash
    infisical ssh issue-credentials --certificateTemplateId=<certificate-template-id> --principals=<username> --addToAgent
    ```

    Here's some guidance on each flag:

    - `certificateTemplateId`: The ID of the certificate template to use for issuing the SSH certificate.
    - `principals`: The comma-delimited username(s) or hostname(s) to include in the SSH certificate.

    For fuller documentation on commands and flags supported by the Infisical CLI for SSH, refer to the docs [here](/cli/commands/ssh).

  </Step>
  <Step title="SSH into the host">
    Finally, SSH into the desired host; the SSH operation will be performed using the SSH certificate loaded into the SSH agent.

    ```bash
    ssh username@hostname
    ```

  </Step>
</Steps>

<Note>
  Note that the above workflow can be executed via API or other client methods
  such as SDK.
</Note>

## Guide to Configuring Host Key Signing

In the following steps, we show how to configure host key signing for clients to verify the identity of a remote host before attempting the SSH operation; this is recommended to reduce the probability of a client accessing a malicious machine.

<Note>
This guide expects that the remote host already has an existing SSH key pair (typically found in the `/etc/ssh/` folder at `/etc/ssh/ssh_host_<algo>_key` and `.pub`).

If the remote host does not have an existing SSH key pair, you can generate a new key pair using the `ssh-keygen` command: `ssh-keygen -t rsa -b 4096 -f /etc/ssh/ssh_host_rsa_key -N ''`. This will generate:

- A private key: `/etc/ssh/ssh_host_rsa_key`.
- A public key: `/etc/ssh/ssh_host_rsa_key.pub`.

</Note>

<Steps>
  <Step title="Configuring a SSH CA for host key signing">
    1.1. In the same SSH project, create another SSH CA in the **Certificate Authorities** tab; this CA will be used for host key signing.
    
    ![ssh create host ca](/images/platform/ssh/ssh-host-create-ca-1.png)
    
    ![ssh create host ca popup](/images/platform/ssh/ssh-host-create-ca-2.png)
    
    Here's some guidance on each field:

    - Friendly Name: A friendly name for the CA; this is only for display.
    - Key Source: Whether the CA's key pair should be generated internally or supplied from an external source. Select **External**.
    - Public Key: The public key for the CA (i.e. the host's SSH public key).
    - Private Key: The private key for the CA (i.e. the host's SSH private key).

  </Step>
  <Step title="Configuring a certificate template on the CA">
  
    2.1. Next, create a certificate template in the **Certificate Templates** section of the newly-created CA.
    
    ![ssh host create template](/images/platform/ssh/ssh-host-create-template-1.png)

    ![ssh host create template popup](/images/platform/ssh/ssh-host-create-template-2.png)

    Here's some guidance on each field:

    - SSH Template Name: A name for the certificate template; this must be a valid slug.
    - Allowed Users: A comma-separated list of valid usernames (e.g. `ec2-user`) on the remote host for which a client can request a certificate for. If you wish to allow a client to request a certificate for any username, set this to `*`; alternatively, if left blank, the template will not allow issuance of certificates under any username.
    - Allowed Hosts: A comma-separated list of valid hostnames/domains on the remote host for which a client can request a certificate for. Each item in the list can be either a wildcard hostname (e.g. `*.acme.com`), a specific hostname (e.g. `example.com`), an IPv4 address (e.g. `192.168.1.1`), or an IPv6 address. If left empty, the template will not allow any hostnames; if set to `*`, the template will allow any hostname.
    - Default TTL: The default Time-to-Live (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request. We recommend setting a longer **Default TTL** for host certificates such as `2y`.
    - Max TTL: The maximum TTL for certificates issued under this template.
    - Allow User Certificates: Whether or not to allow issuance of user certificates; this is not relevant for this step.
    - Allow Host Certificates: Whether or not to allow issuance of host certificates; this should be set to `true`.
    - Allow Custom Key IDs: Whether or not to allow clients to specify a custom key ID to be included on the certificate as part of the certificate request.

  </Step>
  <Step title="Configuring the remote host with an SSH certificate">

    2.1. Obtain a SSH certificate for the host by requesting one from the **Certificates** tab.

    ![ssh host issue certificate 1](/images/platform/ssh/ssh-host-issue-cert-1.png)

    ![ssh host issue certificate 2](/images/platform/ssh/ssh-host-issue-cert-2.png)

    <Note>
      You should select **Sign SSH Key** under the **Operation** field.

      Then input your host's SSH public key under the **SSH Public Key** field and hostname under the **Principal(s)** field; the host's public key should be in the `/etc/ssh` folder of the host as used in step 1.
    </Note>

    ![ssh host issue certificate 3](/images/platform/ssh/ssh-host-issue-cert-3.png)

    2.2. Create a file containing the certificate in the SSH folder of the remote host; we'll call it `ssh_host_key-cert.pub`.

    2.3. Set permissions on the certificate to be `0640`:

    ```bash
    sudo chmod 0640 /etc/ssh/ssh_host_key-cert.pub
    ```

    2.4. Next, add the following lines to the `/etc/ssh/sshd_config` file on the remote host.

    ```bash
    HostKey /etc/ssh/ssh_host_rsa_key
    HostCertificate /etc/ssh/ssh_host_key-cert.pub
    ```

    <Note>
      You should adjust the `HostKey` directive to match the path to the host's SSH private key as used in step 1.
    </Note>

    2.5. Finally, reload the SSH daemon on the remote host to apply the changes.

    ```bash
    sudo systemctl reload sshd
    ```

  </Step>
  <Step title="Configuring the client to trust the remote host">
    3.1. Begin by downloading the host CA's public key from the CA's details section.
    
    ![ssh host ca public key](/images/platform/ssh/ssh-host-ca-public-key.png)
    
    <Note>
      The CA's public key can also be retrieved programmatically via API by making a `GET` request to the endpoint [here](/api-reference/endpoints/ssh/ca/public-key).
    </Note>

    3.2. Next, add the resulting public key to the `known_hosts` file on the client machine (e.g. at the path `~/.ssh/known_hosts`).

    ```bash
    @cert-authority *.example.com ssh-rsa ...
    ```

  </Step>
  <Step title="SSH into the host">
    Finally, SSH into the desired host as usual; the SSH operation will now also include client-side host verification.

    ```bash
    ssh username@hostname
    ```

  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="How can I confirm if the Infisical SSH workflow is working?">
    After configuring Infisical SSH, you can add the `-vvv` flag as part of the
    SSH operation to see verbose output from the SSH client.

    ```bash
    ssh -vvv username@hostname
    ```

    You should see output from the SSH client that includes the following if both client key signing and host key signing are working:

    Host certificate was verified and trusted:

    ```bash
    debug1: Host 'example.com' is known and matches the ECDSA-CERT host certificate.
    debug1: Found CA key in /Users/user/.ssh/known_hosts:1
    ```

    You authenticated with your user certificate:

    ```bash
    debug1: Offering public key: Added via Infisical CLI RSA-CERT SHA256:...
    debug1: Server accepts key: Added via Infisical CLI RSA-CERT SHA256:...
    ```

  </Accordion>
</AccordionGroup>