Version: 19.x (unreleased)

Certificate Authority Overrides

Is this page helpful?

Certificate Authority Overrides let a cluster administrator override a self-signed Teleport CA certificate with a certificate signed by an external certificate authority. In practice, that Teleport CA becomes a subordinate CA in an external trust chain.

info

Certificate Authority Overrides are currently in active development. The released feature set is considered stable, but additional CA support and user experience improvements are planned for future releases.

The current implementation has a few limitations:

Only selected CAs are supported.
tctl get cas/windows only shows the self-signed CA certificate.
tctl auth export only exports the self-signed CA certificates.
tctl auth rotate does not account for active overrides. Administrators must track active overrides and manually create new overrides at the appropriate steps during rotation.

Use tctl get ca_overrides to get override data.

How it works

Teleport maintains several CAs, each with its own self-signed certificates and private keys. A CA override replaces a self-signed CA certificate with an externally signed one.

Teleport continues to manage the CA private keys. Override certificates must target existing CA public keys, so Teleport must generate the CSRs for the overrides.

When Teleport finds an enabled override for a CA certificate, it signs newly issued credentials with the existing private key and uses the override certificate as the issuing CA certificate.

To create a CA override, you must first generate a CSR from Teleport, sign the CSR using an external CA, and then create the cert_authority_override resource.

The cert_authority_override resource targets a CA with the following fields:

sub_kind: the CA type to override, such as windows or db_client.
metadata.name: the Teleport cluster name.

Prerequisites

A running Teleport Enterprise cluster. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
The tctl and tsh clients.
Installing tctl and tsh clients
1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:
  - Mac/Linux
  - Windows - Powershell
  TELEPORT_DOMAIN=teleport.example.com:443
  TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"
2. Follow the instructions for your platform to install tctl and tsh clients:
  - Mac
  - Windows - Powershell
  - Linux
  Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:
  curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg
  In Finder double-click the pkg file to begin installation.
  danger
  Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

Only the following CAs are currently supported: db_client and windows.
All Auth Service instances and related services, such as Windows Desktop Service and Database Service instances, must be upgraded to the same CA override-aware Teleport version.
For safety, back up your cluster state before starting and retain downstream trust to the self-signed CA certificates until the upgrade is fully verified.

Step 1/5. Prepare the override certificate CSR

The windows CA is used as an example. Replace with your target CA, as appropriate.

Prepare the CSR using tctl:

tctl auth create-override-csr --type=windows
-----BEGIN CERTIFICATE REQUEST-----(...)-----END CERTIFICATE REQUEST-----

If you have multiple active or additional keys, such as in HSM deployments or during CA rotation, this command prints multiple PEMs. You may use the --out flag to print each CSR to its own file.

You may customize the certificate subject:

tctl auth create-override-csr --type=windows --subject='OU=My Organization Unit,CN=My Windows CA'

Prepare CSRs for multi-Auth, HSM-enabled clusters

In multi-Auth, HSM-enabled clusters, run tctl locally against each Auth Service instance. Each Auth Service instance generates CSRs for the keys it can access.

For example:

Access the first Auth instance.
Modify the command below as appropriate.
tsh ssh user@Auth1

Generate the CSRs.
Modify as desired.
tctl auth create-override-csr --type=windows

Second Auth instance.
tsh ssh user@Auth2
tctl auth create-override-csr --type=windows

Repeat for each remaining Auth Service instance.

When writing the override resource, make sure the final spec.certificate_overrides contains one entry for each certificate issued from those CSRs. See steps 4 and 4.1.

Step 2/5. Issue override certificates using your external CA

Using the CSRs from step 1, issue the override certificates with your external CA.

The certificates must meet the following requirements:

KeyUsage: keyCertSign and cRLSign.
BasicConstraintsValid: true.
IsCA: true.
Subject: The Teleport cluster name must be present in either the O field (first element) or in the OID 1.3.9999.4.1. CSRs from step 1 always have a valid subject.

Step 3/5. Configure downstream trust

Using the certificates acquired in step 2, configure downstream trust before proceeding. We recommend retaining trust in the self-signed Teleport CA for a grace period, until you have verified normal cluster use.

CA instructions:

db_client: most databases only need to trust the external root CA and intermediate CAs. They do not need to trust the override CA certificate directly.
windows: NTAuth needs to trust the override CA certificate directly. Follow the AD or local guides, adding or replacing the self-signed Teleport CA certificate with the override certificate.

Step 4/5. Create the certificate overrides

After issuing certificates and configuring downstream trust, create the certificate overrides.

Find your cluster name:

tctl get cas/windows | yq '.spec.cluster_name'
mycluster

Prepare the ca_override_windows.yaml file, assigning cluster-name to your cluster name.

Add one entry under spec.certificate_overrides for each override certificate. Replace the example PEM with your override certificate PEM.

kind: cert_authority_override
sub_kind: windows
version: v1
metadata:
  name: cluster-name
spec:
  certificate_overrides:
  - certificate: |-
      -----BEGIN CERTIFICATE-----
      (...)
      -----END CERTIFICATE-----

Create the override:

tctl create ca_override_windows.yaml

tip

You may create a disabled override and enable it later.

This is useful for environments with staged rollouts, so overrides may be created in a disabled state until downstream services are ready to accept them. Set disabled to false when you are ready to enable the override.

kind: cert_authority_override
sub_kind: windows
version: v1
metadata:
  name: cluster-name
spec:
  certificate_overrides:
  - certificate: |-
      -----BEGIN CERTIFICATE-----
      (...)
      -----END CERTIFICATE-----
    disabled: true

Create certificate overrides on multi-Auth, HSM-enabled clusters

In multi-Auth, HSM-enabled clusters, each certificate_override entry must be added by the corresponding Auth Service instance, which is the Auth Service instance that has access to the relevant private key.

Start with an empty CA override created by any Auth Service instance:

kind: cert_authority_override
sub_kind: windows
version: v1
metadata:
  name: cluster-name
spec: {}

tctl create ca_override_windows.yaml

Then, on each Auth Service instance, edit the CA override with tctl edit.

Modify the command below as appropriate.
tsh ssh user@Auth1

tctl edit ca_overrides/windows

Add the corresponding certificate_override stanza, then save and exit.

kind: cert_authority_override
sub_kind: windows
version: v1
metadata:
  name: cluster-name
spec:
  certificate_overrides:
  - certificate: |-
      -----BEGIN CERTIFICATE-----
      (...)
      -----END CERTIFICATE-----
  - certificate: |-
      -----BEGIN CERTIFICATE-----
      (...)
      -----END CERTIFICATE-----

Step 5/5. Exercise the CA override

Exercise the override by attempting a connection with the appropriate protocol (RDP for windows, tsh db connect for db_client, etc).

Using the windows CA as an example, start a new desktop session from your Teleport Proxy. If downstream trust is configured correctly, the session should start successfully.

To confirm that the override is in use, inspect the "Windows Desktop Session Started" event for the new session. You should see the "ca_override" stanza with "active": true and a corresponding public_key_hash. ("Database Session Started" events are modified similarly.)

Session Started sample event

{
  "ca_override": {
    "active": true,
    "public_key_hash": "f4522365888fdddcf3c854e79e5928447fe1a2388353efb2f0d30db8ba7c81bc"
  },
  "cluster_name": "mycluster",
  "code": "TDP00I",
  "desktop_name": "example-desktop",
  "ei": 1,
  "event": "windows.desktop.session.start",
  "success": true
}

Was this page helpful?

How it works​

Prerequisites​

Step 1/5. Prepare the override certificate CSR​

Prepare CSRs for multi-Auth, HSM-enabled clusters​

Step 2/5. Issue override certificates using your external CA​

Step 3/5. Configure downstream trust​

Step 4/5. Create the certificate overrides​

Create certificate overrides on multi-Auth, HSM-enabled clusters​

Step 5/5. Exercise the CA override​