HashiCorp Vault CA Integration for RDP

This guide provides general information on how to add an existing HashiCorp Vault certificate authority (CA) as a third-party CA to StrongDM. Vault CA integration allows certificate-based RDP resources to authenticate with X.509 certificates issued by the HashiCorp PKI Secrets Engine, instead of the default Strong CA managed by StrongDM.

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 PKI Secrets engine and configuring X.509 public key infrastructure (PKI)
• 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 PKI 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 and signing role #

Vault CA integration requires a mount point name and signing role name to be specified. The mount point and signing role are used to configure the Vault CA in StrongDM.

Each mount point can have multiple CAs. Certificates that are issued by a 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 and required features for the certificates. The signing role can specify the issuer_ref setting to determine which CA should sign the Certificate Signing Request (CSR) created by StrongDM nodes. If not specified, the PKI mount’s default issuer will be used.

When integrating a Vault CA, it is up to the you to configure the mount point and the desired signing role to resolve to the issuer that you want to use (either the default or some other specified issuer). We recommend that your signing role specifies the issuer, as in the example signing role that follows.

Please ensure that your signing role in Vault matches the settings shown in the following example signing roles, which include the minimum requirements to work with certificate-based RDP resources.

RDP example signing role specifying default issuer #

This example signing role does not include the issuer_ref, and so the signing role uses the default issuer of the mount point.

{
    "allow_any_name": false,
    "allowed_other_sans": ["1.3.6.1.4.1.311.20.2.3;UTF8:*"],
    "require_cn": false,
    "organization": "strongDM",
    "key_usage": ["DigitalSignature", "KeyEncipherment"],
    "ext_key_usage":["ServerAuth", "ClientAuth"],
    "ext_key_usage_oids": "1.3.6.1.4.1.311.20.2.2",
    "max_ttl":"5m0s"
}

RDP example signing role specifying a different issuer #

This example signing role specifies an issuer that is not the default.

vault write example-pki/roles/example-pki-signer-issuer-ref

{
    "issuer_ref": "eca2396b-5e6c-bd2d-64f9-3d7046bbd803",
    "allowed_other_sans": ["1.3.6.1.4.1.311.20.2.3;UTF8:*"],
    "require_cn": false,
    "organization": "strongDM",
    "key_usage": ["DigitalSignature", "KeyEncipherment"],
    "ext_key_usage":["ServerAuth", "ClientAuth"],
    "ext_key_usage_oids": "1.3.6.1.4.1.311.20.2.2",
    "max_ttl":"5m0s"
}

Certificate signing requests #

How does certificate signing work? StrongDM generates a key pair on the gateway or relay and generates a Certificate Signing Request (CSR) signed by the private key. The CSR is submitted to the HashiCorp Vault for signing via the sign endpoint using the path <PKI_MOUNT_POINT>/sign/<SIGNING_ROLE>. Notice that the endpoint requires the mount point and signing role. The resulting signed certificate is then used, along with the private key, to authenticate to the target resource. The private key never leaves the gateway or relay where it was created.

Add Vault CA in the Admin UI #

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

1. From the Settings > Credentials Management page in the Certificate Authorities tab, click Add certificate authority.
2. Enter the Name for the CA (any name).
3. For Type, select HashiCorp Vault RDP, HashiCorp Vault RDP (AppRole), or HashiCorp Vault RDP (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 RDP CA properties #

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

Add the Vault CA to a Certificate-Based RDP Server #

1. If you have not already done so, follow the instructions to add an RDP server with certificate authentication.
2. On the resource form, pay particular attention to Certificate Authority. For this field, select the newly added Vault CA.
3. Complete all required fields and save.
4. Test the connection to the resource (for example, use Remote Desktop 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 > Credentials 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.

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 RDP CA in the CLI #

To add a Vault RDP 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.

• vaultTLSCertX509 corresponds to the HashiCorp Vault RDP CA type
• vaultAppRoleCertX509 corresponds to the HashiCorp Vault RDP (AppRole) CA type.
• vaultTokenCertX509 corresponds to the HashiCorp Vault RDP (Token) CA type.

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

CLI example #

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

# Create RDP (Certificate Based) server
sdm admin servers create rdp-cert
--name="Example RDP 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 connect "Example RDP Vault"

Add Vault RDP 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 RDP 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 RDP CA
resource "sdm_secret_store" "example-tf-rdp-ca" {
  vault_token_cert_x509 {
    name = "${var.prefix}rdp-ca"
    server_address = "https://vault.example.com:1234"
    pki_mount_point = "example-pki-mount-point"
    signing_role = "example-rdp-signing-role"
    issued_cert_ttl_minutes = "480"
  }
}

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

Add Vault RDP CA with the SDKs #

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

• Go
• Java
• Python
• Ruby