HashiCorp Vault CA Integration for RDP

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.

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.

Authentication

Vault CAs now support both standard and AWS-based authentication methods.

Standard authentication: Token or AppRole
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 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
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 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.

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

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.

The signing role is allowed to access (or is not restricted from accessing) both the <MOUNTPOINT>/sign and <MOUNTPOINT>/sign-verbatim API endpoints via a policy.

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.

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 5m0s in the signing role allows the certificate to be valid for a maximum of 5 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 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 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 RDP 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-rdp-ca.

Add Vault CA in the Admin UI

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

From the Settings > Secrets Management page in the Certificate Authorities tab, click Add certificate authority.
Enter the Name for the CA (any name).
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 RDP
2. HashiCorp Vault RDP (AWS EC2 auth)
3. HashiCorp Vault RDP (AWS IAM auth)
4. HashiCorp Vault RDP (AppRole)
5. HashiCorp Vault RDP (Token).
The form updates with other CA properties, some of which are specific to the selected type. Complete all required properties.
Click Create certificate authority.

When HashiCorp Vault RDP (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.

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.
vaultAWSEC2CertX509 corresponds to the HashiCorp Vault RDP (AWS EC2 auth) CA type.
vaultAWSIAMCertX509 corresponds to the HashiCorp Vault RDP (AWS IAM auth) 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"
  }
}

Vault RDP CA properties

The following properties are available for HashiCorp Vault RDP.

Property

Requirement

Description

Type

Required

HashiCorp Vault RDP

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)

PKI Mount Point

Required

PKI mount point (string; for example, dev-pki) configured for the CA to be used

Signing Role

Required

Signing role configured in Vault for signing the certificate (string; for example, signing-role)

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

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. Moreover, if the Certificate TTL Minutes value set in StrongDM is higher than the max_ttl configured in Vault, you get an error and the connection will fail.

See the Vault Configuration Considerations section of this guide for more information about the TTL.

AWS IAM Authentication

To use AWS IAM–based authentication for your Vault CA, 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 RDP Server

If you have not already done so, follow the instructions to add an RDP server with certificate authentication.
On the resource form, pay particular attention to Certificate Authority. For this field, select the newly added Vault CA.
Complete all required fields and save.
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 > 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.

Last updated 16 days ago

Was this helpful?