HashiCorp Vault CA Integration for SSH

This feature is part of the Enterprise plan. If it is not enabled for your organization, please contact StrongDM at the StrongDM Help Center.

This guide provides general information on how to add an existing HashiCorp Vault certificate authority (CA) as a third-party CA to StrongDM.

Authentication

Integrated Vault CAs may be used for certificate-based SSH resources configured for one of the following standard or AWS-based authentication methods:

• TLS certificate-based authentication

• AppRole authentication

• Token-based authentication

• AWS authentication (IAM user or EC2 role)

Prerequisites

Before you begin, ensure that you have the following.

• Administrator permission level in StrongDM

• Running Vault server that is accessible by a StrongDM gateway or relay

• Familiarity using the HashiCorp SSH Secrets engine and configuring SSH certificates

• Properly configured CA in the Vault instance with a mount point and signing role

• Correct paths to the CA

• If using AWS-based authentication, your Vault instance must have the AWS Auth method enabled.

Vault Configuration Considerations

Because StrongDM doesn't manage or configure third-party CAs, it is up to you to configure your SSH Secrets engine appropriately for your organization, as well as to ensure that the appropriate CA is trusted by the target resources. This section briefly describes the most important parts of Vault setup to consider when integrating a Vault CA with StrongDM.

If HashiCorp Vault is also used as a Secret Store, the same authentication method must be used.

Mount point

The Vault SSH service can be mounted multiple times to distinct mount points. Each mount point is configured with its own CA and signing role. A distinct Secret Store is created and configured for each CA.

Key type

The CA defines the key type and, in the case of variable bit length key types, the key bits. The default CA in HashiCorp Vault is ssh-rsa with 4096 bits. The key type of the CA must match the key type of the certificate-based resource in StrongDM.

Signing role

Certificates that are issued by the CA must be signed by a role that is configured for the specific mount point of the CA. The signing role defines the default values for the SSH certificates as well as what extensions and features are allowed in the SSH certificates.

All certificates generated using the CA will use the maximum time-to-live (TTL) that is defined in the signing role in Vault. The TTL determines the lifetime of the certificate. We recommend that the signing role specify the max_ttl setting, which sets the maximum value for the certificate's TTL. For example, setting max_ttl to 30m0s in the signing role allows the certificate to be valid for a maximum of 30 minutes. If set in the signing role, the max_ttl value overrides the configured Certificate TTL Minutes property in StrongDM if the Certificate TTL Minutes value is higher than the signing role's max_ttl value.

Please ensure that your signing role in Vault matches the following example signing role, which includes the minimum required settings to work with certificate-based SSH resources.

SSH example signing role

{
  "algorithm_signer": "rsa-sha2-256",
  "allow_user_certificates": true,
  "allowed_users": "*",
  "allowed_extensions": "permit-X11-forwarding,permit-agent-forwarding,permit-port-forwarding,permit-pty,permit-user-rc",
  "default_extensions": {
    "permit-X11-forwarding":   "",
	"permit-agent-forwarding": "",
	"permit-port-forwarding":  "",
	"permit-pty":              "",
	"permit-user-rc":          "",
  },
  "key_type": "ca",
  "default_user": "ubuntu",
  "max_ttl": "30m0s"
}

Add the CA in StrongDM

After all prerequisites and prep work is done, you are ready to add the CA in StrongDM. This section provides instructions for adding the CA in either the StrongDM Admin UI, CLI, Terraform provider, or SDKs.

Note that third-party CAs are treated like secret stores in the CLI, SDKs, and Terraform. As such, they use secret store commands, domain objects, and resources.

Activities related to third-party CAs are logged in the same way as secret store activities. For example, adding a third-party SSH CA in Terraform produces an activity similar to API Account example-terraform-key (cc1e23eb-e456-7891-23c4-edf5678c9123) created a secret store named example-tf-ssh-ca.

Admin UI

Add Vault CA in Admin UI

To add a Vault SSH CA in the Admin UI, follow these steps.

1. From the Settings > Secrets Management page in the Certificate Authorities tab, click Add certificate authority.

2. Enter the Name for the CA (any name).

3. For Type, select one of the following. The type corresponds to your chosen authentication method that enables your StrongDM relay to authenticate with Vault.

   1. HashiCorp Vault SSH

   2. HashiCorp Vault SSH (AWS EC2 auth)

   3. HashiCorp Vault SSH (AWS IAM auth)

   4. HashiCorp Vault SSH (AppRole)

   5. HashiCorp Vault SSH (Token)

4. The form updates with other CA properties, some of which are specific to the selected type. Complete all required properties.

5. Click Create certificate authority.

When HashiCorp Vault SSH (Token) is the selected type, you also need to get a token for Vault and set it as the VAULT_TOKEN environment variable on your StrongDM node. To do so, in your command line on the node, or when logged in to the node, edit the environment file. The default environment file location is /etc/sysconfig/sdm-proxy for gateways and relays, or /etc/sysconfig/sdm-worker for proxy clusters. In the file, add VAULT_TOKEN=<TOKEN> as a new line, where <TOKEN> is the actual value. Then restart the service. If your system uses systemd, the command is sudo systemctl restart sdm-proxy for gateways and relays, or sudo systemctl restart sdm-worker for proxy clusters.

CLI

Terraform

SDKs

Vault SSH CA properties

SSH

The following properties are available for HashiCorp Vault SSH.

Property	Requirement	Description
Type	Required	HashiCorp Vault SSH
Server Address	Required	Address where the CA is stored (for example, https://vault.example.com:1234)
Client Certificate Path	Required	Path to where the TLS certificate is stored on the relay (for example, /etc/strongdm/certs/client.crt)
Client Private Key Path	Required	Path to where the TLS private key is stored on the relay (for example, /etc/strongdm/certs/client.key)
CA Certificate Path	Optional	Path to where the CA certificate is stored on the relay (for example, /etc/strongdm/certs/ca.crt)
Signing Role	Required	Signing role configured in Vault for signing the certificate (string; for example, signing-role)
SSH Mount Point	Required	SSH mount point (string; for example, dev-ssh) configured for the CA to be used
Namespace	Optional	Namespace in Vault (for example, prod-namespace/)
Certificate TTL Minutes	Required	TTL of the issued certificate, in minutes (for example, 480); default is 5; if not specified, the default TTL of five minutes is used

AppRole

Token

AWS EC2 auth

AWS IAM auth

All third-party CAs except for AD CS and Keyfactor EJBCA have a default TTL of five minutes. A five-minute TTL ensures short-lived certificates so that authentications can’t be reused beyond the specified TTL. If you wish to have a longer TTL, please set it appropriately for your organization and consult your CA service provider and CA administrator.

Please note that in the Vault signing role, max_ttl sets the maximum TTL for certificates issued by the CA. If that is set and if a value is also specified for Certificate TTL Minutes in StrongDM, the resulting TTL is the lower of the two values. See the signing role section of this guide for more information.

AWS IAM Authentication

To use AWS IAM–based authentication for your Vault CA, you must also configure your StrongDM secret store to use one of the following AWS authentication types:

• AWS IAM User: This uses IAM credentials (access key and secret) to authenticate to Vault.

• AWS EC2 Role: This uses an instance’s EC2 metadata service for IAM-based authentication.

Authentication works the same as described in our HashiCorp Vault Secret Store guide.

For detailed information on the AWS authentication methods, please refer to HashiCorp’s Vault AWS Auth documentation.

Add the Vault CA to a Certificate-Based SSH Server

1. If you have not already done so, follow the instructions to add an SSH server with certificate auth.

2. On the resource form, pay particular attention to Certificate Authority and Key Type.

3. For Certificate Authority, select the newly added Vault CA.

4. For Key Type, select the key type configured for the CA in Vault: RSA-2048, RSA-4096, ECDSA-256, ECDSA-384, ECDSA-521, or ED25519. The key type must match what is configured on the Vault side.

5. Complete all required fields and save.

6. Test the connection to the resource (for example, use sdm ssh in the CLI to connect).

Manage the CA

After you have added the Vault CA and set a certificate-based server to use it, you may manage the CA and review its settings on the Certificate Authorities tab of the Settings > Secrets Management page in the Admin UI. You may select the CA from the list or click its Details button to view diagnostics, update its settings, or delete the CA configuration.

Deletion removes the CA configuration from StrongDM only, not from Vault.

The Diagnostics tab shows all the nodes (gateways and relays) that are configured to access the CA, as well as health information for the nodes.

If the CA is unable to be accessed by any gateway or relay, please review the CA's Settings tab and make sure the CA credentials are correct.

Every healthcheck for certificate-based resources configured to use a third-party CA generates a certificate with the CA provider.