HashiCorp Vault CA Integration for SSH

This guide provides general information on how to add an existing HashiCorp Vault certificate authority (CA) as a third-party CA to StrongDM. Integrated Vault CAs may be used for certificate-based SSH resources configured for either TLS certificate-based authentication, AppRole authentication, or token-based authentication.

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

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.

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.

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 Vault CA in Admin UI #

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

1. From the Certificate Authorities page, click Add certificate authority.
2. Enter the Name for the CA (any name).
3. For Type, select HashiCorp Vault SSH, HashiCorp Vault SSH (AppRole), or HashiCorp Vault SSH (Token). The type corresponds to your chosen authentication method that enables your StrongDM relay to authenticate with Vault: TLS certificate-based authentication, AppRole authentication, or token-based authentication.
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.

Vault SSH CA properties #

The following properties are for HashiCorp Vault SSH, HashiCorp Vault SSH (AppRole), and/or HashiCorp Vault SSH (Token).

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 page of 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.

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.

Additional Information #

Third-party CAs also may be added and managed in the CLI, SDKs, and Terraform. 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.

Add Vault SSH CA in the CLI #

To add a Vault SSH CA in the CLI instead of the Admin UI, use the sdm admin secretstores create CLI command. Create your “secret store” by choosing one the following secret store types and setting the correct options/properties.

• vaultTLSCertSSH corresponds to the HashiCorp Vault SSH CA type.
• vaultAppRoleCertSSH corresponds to the HashiCorp Vault SSH (AppRole) CA type.
• vaultTokenCertSSH corresponds to the HashiCorp Vault SSH (Token) CA type.

In the CLI, the options are the same as the Vault SSH CA properties set in the Admin UI.

CLI example #

# Create HashiCorp Vault SSH (Token) CA
sdm admin secretstores create vaultTokenCertSSH
--name="Example SSH CA" --server-address="https://vault.example.com:1234"
--signing-role="example-ssh-signing-role"
--ssh-mount-point="example-ssh-mount-point"
--issued-cert-ttl-minutes="480"

# Create RDP (Certificate Based) server
sdm admin servers create ssh-cert
--name="Example SSH Vault"
--hostname="https://vault.example.com:1234"
--secret-store-id="se-e1b2"
--username="username"

# Run secret store healthcheck
sdm admin secretstores healthcheck se-e1b2

# Check that the secret store is reachable
sdm admin secretstores status

# Check the connection to the resource
sdm ssh "Example SSH Vault"

Add Vault SSH CA in Terraform #

In addition to using the Admin UI and CLI, you may use Terraform to add a Vault CA for use with certificate-based SSH servers. This section includes a Terraform example.

For additional information, see our Terraform provider documentation.

Terraform example #

# Install StrongDM provider
terraform {
  required_providers {
    sdm = {
      source  = "strongdm/sdm"
      version = "7.1.1"
    }
  }
}

# Configure StrongDM provider
provider "sdm" {
    # Add API access key and secret key from Admin UI
    api_access_key = "njjSn...5hM"
    api_secret_key = "ziG...="
}

variable "prefix" {
  type = string
  default = "example-tf-"
}

# Create Vault SSH CA
resource "sdm_secret_store" "example-tf-ssh-ca" {
  vault_token_cert_ssh {
    name = "${var.prefix}ssh-ca"
    server_address = "https://vault.example.com:1234"
    ssh_mount_point = "example-ssh-mount-point"
    signing_role = "example-ssh-signing-role"
    issued_cert_ttl_minutes = "480"
  }
}

# Create SSH (Certificate Based) server
resource "sdm_resource" "demo-ssh-cert-based" {
  ssh_cert {
    name = "${var.prefix}ssh-vault-ca"
    hostname = "https://vault.example.com:1234"
    port=22
    secret_store_id = sdm_secret_store.example-tf-ssh-ca.id
    username = "ssh-username"
  }
}

Add Vault SSH CA with the SDKs #

To add a Vault CA with the StrongDM SDKs, please see the SDKs on GitHub:

• Go
• Java
• Python
• Ruby