diff --git a/docs/documentation/platform/ssh.mdx b/docs/documentation/platform/ssh.mdx
index 4135fd053..d85cab98b 100644
--- a/docs/documentation/platform/ssh.mdx
+++ b/docs/documentation/platform/ssh.mdx
@@ -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.
+
+
+
+```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]
+
+```
+
+
+
+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.
-Test
+
+ Note that the workflow above requires an operator to perform additional
+ configuration on the remote host to trust SSH certificates issued by
+ Infisical.
+
-Note on using CLI
+## 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.
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
+## 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:
+
+
+
+
+```bash
+infisical login
+```
+
+
+
+ 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.
+
+
+
+ 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= --principals=
+ ```
+
+ 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.
+
+
+ If `outFilePath` is not specified, the SSH certificate will be written to the current working directory where the command is run.
+
+
+
+
+ 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= --certificateTemplateId= --principals=
+ ```
+
+ 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.
+
+
+ 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.
+
+
+
+
+
+
+
+ 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
+ ```
+
+
+ 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 that the above workflow can be executed via API or other client methods
+ such as SDK.
+
diff --git a/docs/images/platform/ssh/ssh-ca-public-key.png b/docs/images/platform/ssh/ssh-ca-public-key.png
new file mode 100644
index 000000000..42653df4a
Binary files /dev/null and b/docs/images/platform/ssh/ssh-ca-public-key.png differ
diff --git a/docs/images/platform/ssh/ssh-create-ca-1.png b/docs/images/platform/ssh/ssh-create-ca-1.png
new file mode 100644
index 000000000..e9a5b7f06
Binary files /dev/null and b/docs/images/platform/ssh/ssh-create-ca-1.png differ
diff --git a/docs/images/platform/ssh/ssh-create-ca-2.png b/docs/images/platform/ssh/ssh-create-ca-2.png
new file mode 100644
index 000000000..63025025f
Binary files /dev/null and b/docs/images/platform/ssh/ssh-create-ca-2.png differ
diff --git a/docs/images/platform/ssh/ssh-create-template-1.png b/docs/images/platform/ssh/ssh-create-template-1.png
new file mode 100644
index 000000000..9d9420948
Binary files /dev/null and b/docs/images/platform/ssh/ssh-create-template-1.png differ
diff --git a/docs/images/platform/ssh/ssh-create-template-2.png b/docs/images/platform/ssh/ssh-create-template-2.png
new file mode 100644
index 000000000..7b93e6d80
Binary files /dev/null and b/docs/images/platform/ssh/ssh-create-template-2.png differ
diff --git a/docs/images/platform/ssh/ssh-project.png b/docs/images/platform/ssh/ssh-project.png
new file mode 100644
index 000000000..0b57f9245
Binary files /dev/null and b/docs/images/platform/ssh/ssh-project.png differ
diff --git a/frontend/src/views/Project/SshPage/components/SshCaModal.tsx b/frontend/src/views/Project/SshPage/components/SshCaModal.tsx
index f0a2eb685..47a58bfdf 100644
--- a/frontend/src/views/Project/SshPage/components/SshCaModal.tsx
+++ b/frontend/src/views/Project/SshPage/components/SshCaModal.tsx
@@ -1,5 +1,6 @@
import { useEffect } from "react";
import { Controller, useForm } from "react-hook-form";
+import { useRouter } from "next/router";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";
@@ -17,6 +18,7 @@ import { useWorkspace } from "@app/context";
import { useCreateSshCa, useGetSshCaById, useUpdateSshCa } from "@app/hooks/api";
import { certKeyAlgorithms } from "@app/hooks/api/certificates/constants";
import { CertKeyAlgorithm } from "@app/hooks/api/certificates/enums";
+import { ProjectType } from "@app/hooks/api/workspace/types";
import { UsePopUpState } from "@app/hooks/usePopUp";
type Props = {
@@ -39,6 +41,7 @@ const schema = z
export type FormData = z.infer;
export const SshCaModal = ({ popUp, handlePopUpToggle }: Props) => {
+ const router = useRouter();
const { currentWorkspace } = useWorkspace();
const projectId = currentWorkspace?.id || "";
const { data: ca } = useGetSshCaById((popUp?.sshCa?.data as { caId: string })?.caId || "");
@@ -83,11 +86,13 @@ export const SshCaModal = ({ popUp, handlePopUpToggle }: Props) => {
friendlyName
});
} else {
- await createMutateAsync({
+ const { id: newCaId } = await createMutateAsync({
projectId,
friendlyName,
keyAlgorithm
});
+
+ router.push(`/${ProjectType.SSH}/${projectId}/ca/${newCaId}`);
}
reset();