diff --git a/docs/cli/commands/ssh.mdx b/docs/cli/commands/ssh.mdx new file mode 100644 index 000000000..309f5d729 --- /dev/null +++ b/docs/cli/commands/ssh.mdx @@ -0,0 +1,118 @@ +--- +title: "infisical ssh" +description: "Generate SSH credentials with the CLI" +--- + +## Description + +[Infisical SSH](/documentation/platform/ssh) lets you issue SSH credentials to clients to provide short-lived, secure SSH access to infrastructure. + +This command enables you to obtain SSH credentials used to access a remote host; we recommend using the `issue-credentials` sub-command to generate dynamic SSH credentials for each SSH session. + +### Sub-commands + + + This command is used to issue SSH credentials (SSH certificate, public key, and private key) against a certificate template. + + We recommend using the `--addToAgent` flag to automatically load issued SSH credentials to the SSH agent. + + ```bash + $ infisical ssh issue-credentials --certificateTemplateId= --principals= --addToAgent + ``` + + ### Flags + + The ID of the SSH certificate template to issue SSH credentials for. + + + A comma-separated list of principals (i.e. usernames like `ec2-user` or hostnames) to issue SSH credentials for. + + + Whether to add issued SSH credentials to the SSH agent. + + Default value: `false` + + Note that either the `--outFilePath` or `--addToAgent` flag must be set for the sub-command to execute successfully. + + + The path to write the SSH credentials to such as `~/.ssh`, `./some_folder`, `./some_folder/id_rsa-cert.pub`. If not provided, the credentials will be saved to the current working directory where the command is run. + + Note that either the `--outFilePath` or `--addToAgent` flag must be set for the sub-command to execute successfully. + + + The key algorithm to issue SSH credentials for. + + Default value: `RSA_2048` + + Available options: `RSA_2048`, `RSA_4096`, `EC_prime256v1`, `EC_secp384r1`. + + + The certificate type to issue SSH credentials for. + + Default value: `user` + + Available options: `user` or `host` + + + The time-to-live (TTL) for the issued SSH certificate (e.g. `2 days`, `1d`, `2h`, `1y`). + + Defaults to the Default TTL value set in the certificate template. + + + A custom Key ID to issue SSH credentials for. + + Defaults to the autogenerated Key ID by Infisical. + + + The authenticated token to use to issue SSH credentials. This is required when using a machine identity to authenticate. + + + + + This command is used to sign an existing SSH public key against a certificate template; the command outputs the corresponding signed SSH certificate. + + ```bash + $ infisical ssh sign-key --certificateTemplateId= --publicKey= --principals= --outFilePath= + ``` + + The ID of the SSH certificate template to issue the SSH certificate for. + + + The public key to sign. + + Note that either the `--publicKey` or `--publicKeyFilePath` flag must be set for the sub-command to execute successfully. + + + The path to the public key file to sign. + + Note that either the `--publicKey` or `--publicKeyFilePath` flag must be set for the sub-command to execute successfully. + + + A comma-separated list of principals (i.e. usernames like `ec2-user` or hostnames) to issue SSH credentials for. + + + The path to write the SSH certificate to such as `~/.ssh/id_rsa-cert.pub`; the specified file must have the `.pub` extension. If not provided, the credentials will be saved to the directory of the specified `--publicKeyFilePath` or the current working directory where the command is run. + + Note that either the `--outFilePath` or `--addToAgent` flag must be set for the sub-command to execute successfully. + + + The certificate type to issue SSH credentials for. + + Default value: `user` + + Available options: `user` or `host` + + + The time-to-live (TTL) for the issued SSH certificate (e.g. `2 days`, `1d`, `2h`, `1y`). + + Defaults to the Default TTL value set in the certificate template. + + + A custom Key ID to issue SSH credentials for. + + Defaults to the autogenerated Key ID by Infisical. + + + The authenticated token to use to issue SSH credentials. This is required when using a machine identity to authenticate. + + \ No newline at end of file diff --git a/docs/documentation/platform/ssh.mdx b/docs/documentation/platform/ssh.mdx index 1bcad484a..16faf1267 100644 --- a/docs/documentation/platform/ssh.mdx +++ b/docs/documentation/platform/ssh.mdx @@ -6,7 +6,7 @@ description: "Learn how to generate SSH credentials to provide secure and centra ## Concept -Infisical can be used to issue SSH certificates to clients to provide short-lived, secure SSH access to infrastructure; +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. @@ -191,7 +191,9 @@ infisical login - `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). + Finally, SSH into the desired host; the SSH operation will be performed using the SSH certificate loaded into the SSH agent. @@ -199,11 +201,10 @@ infisical login ```bash ssh username@hostname ``` - Note that the above workflow can be executed via API or other client methods such as SDK. - + \ No newline at end of file diff --git a/docs/mint.json b/docs/mint.json index 7eb28336b..9d5db3826 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -320,6 +320,7 @@ "cli/commands/run", "cli/commands/secrets", "cli/commands/dynamic-secrets", + "cli/commands/ssh", "cli/commands/export", "cli/commands/token", "cli/commands/service-token",