mirror of
https://github.com/awatertrevi/infisical.git
synced 2026-09-22 13:39:35 +00:00
Add docs for Infisical SSH
This commit is contained in:
Tuan Dang
@@ -4,18 +4,48 @@ sidebarTitle: "Infisical SSH"
|
||||
description: "Learn how to generate SSH credentials to provide secure and centralized SSH access control for your infrastructure."
|
||||
---
|
||||
|
||||
Infisical can be used to issue SSH certificates to provide short-lived, secure SSH access to your infrastructure.
|
||||
|
||||
## Concept
|
||||
|
||||
The following sequence diagram illustrates the client workflow for accessing a host using an SSH certificate (and optionally key pair)
|
||||
Infisical can be used to issue SSH certificates 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 Host
|
||||
participant Host as Remote Host
|
||||
|
||||
Note over Client,Client: Step 1: Client Authentication with Infisical
|
||||
Client->>Infisical: Send credential(s) to authenticate with Infisical
|
||||
@@ -33,16 +63,177 @@ sequenceDiagram
|
||||
Host-->>Client: Grant access to the host
|
||||
```
|
||||
|
||||
TODO: Mention required configuration on the host.
|
||||
|
||||
At a high-level, Infisical issues a signed SSH certificate to a client that can be used to access a 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 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 tha 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 access the host.
|
||||
3. The client uses the issued SSH certificate (and potentially SSH key pair) to temporarily access the host.
|
||||
|
||||
<Info>Test</Info>
|
||||
<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>
|
||||
|
||||
<Note>Note on using CLI</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 Infisical SSH">
|
||||
1.1. Start by creating a SSH project in the SSH tab of your organization.
|
||||
|
||||
|
||||
|
||||
1.2. Next, create a CA in the **Certificate Authorities** tab of the
|
||||
project.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Here's some guidance on each field:
|
||||
|
||||
- Friendly Name: A friendly name for the CA; this is only for display.
|
||||
- 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`.
|
||||
|
||||
1.3. 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 year.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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-toLive (TTL) for certificates issued under this template when a client does not explicitly specify a TTL in the certificate request.
|
||||
- Max TTL: The maximum TTL for certificates issued under this template.
|
||||
- Allow User Certificates: Whether or not to allow issuance of user certificates.
|
||||
- Allow Host Certificates: Whether or not to allow issuance of host certificates.
|
||||
- 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.
|
||||
|
||||
1.4. 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">
|
||||
|
||||
2.1. Begin by downloading the CA's public key from the CA's details section.
|
||||
|
||||
|
||||
|
||||
2.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`.
|
||||
|
||||
2.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
|
||||
```
|
||||
|
||||
2.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
|
||||
|
||||
We show how to obtain a SSH certificate (and optionally a new SSH key pair) for a client to access a host via CLI:
|
||||
|
||||
<Steps>
|
||||
<Step title="Authenticate with Infisical">
|
||||
|
||||
```bash
|
||||
infisical login
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Obtain a SSH certificate (and optionally new key-pair)">
|
||||
Depending on the use-case, a client may either request a SSH certificate along with a new SSH key pair or obtain a SSH certificate for an existing SSH key pair to access a host.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Using New Key Pair (Recommended)">
|
||||
If you wish to obtain a new SSH key pair in conjunction with the SSH certificate, then you can use the `infisical ssh issue-credentials` command.
|
||||
|
||||
```bash
|
||||
infisical ssh issue-credentials --certificateTemplateId=<certificate-template-id> --principals=<username>
|
||||
```
|
||||
|
||||
The following flags may be relevant:
|
||||
|
||||
- `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.
|
||||
- `outFilePath` (optional): The path to the file to write the SSH certificate to.
|
||||
|
||||
<Note>
|
||||
If `outFilePath` is not specified, the SSH certificate will be written to the current working directory where the command is run.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Using Existing Key Pair">
|
||||
If you have an existing SSH key pair, then you can use the `infisical ssh sign-key` command with either
|
||||
the `--publicKey` flag or the `--publicKeyFilePath` flag to obtain a SSH certificate corresponding to
|
||||
the existing credential.
|
||||
|
||||
```bash
|
||||
infisical ssh sign-key --publicKeyFilePath=<public-key-file-path> --certificateTemplateId=<certificate-template-id> --principals=<username>
|
||||
```
|
||||
|
||||
The following flags may be relevant:
|
||||
|
||||
- `publicKey`: The public key to sign.
|
||||
- `publicKeyFilePath`: The path to the public key file to sign.
|
||||
- `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.
|
||||
- `outFilePath` (optional): The path to the file to write the SSH certificate to.
|
||||
|
||||
<Note>
|
||||
If `outFilePath` is not specified but `publicKeyFilePath` is then the SSH certificate will be written to the directory of the public key file; if the public key file is called `id_rsa.pub`, then the file containing the SSH certificate will be called `id_rsa-cert.pub`.
|
||||
|
||||
Otherwise, if `outFilePath` is not specified, the SSH certificate will be written to the current working directory where the command is run.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
</Step>
|
||||
<Step title="SSH into the host">
|
||||
Once you have obtained the SSH certificate, you can use it to SSH into the desired host.
|
||||
|
||||
```bash
|
||||
ssh -i /path/to/private_key.pem \
|
||||
-o CertificateFile=/path/to/ssh-cert.pub \
|
||||
username@hostname
|
||||
```
|
||||
|
||||
<Note>
|
||||
We recommend setting up aliases so you can more easily SSH into the desired host.
|
||||
|
||||
For example, you may set up an SSH alias using the SSH client configuration file (usually `~/.ssh/config`), defining a host alias as below
|
||||
including the file path to the issued SSH credential(s).
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Note that the above workflow can be executed via API or other client methods
|
||||
such as SDK.
|
||||
</Note>
|
||||
|
||||
Reference in New Issue
Block a user