Skip to main content

Certificate Authority Overrides is available only with Teleport Enterprise. Start your free trial.

Start your free trial
Version: 19.x (unreleased)

Certificate Authority Overrides

Report an Issue

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 (v18.9.0 or higher) 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:

      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:

      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'

Multi-Auth Service clusters with per-instance HSM keys​

In clusters with multiple Auth Service instances and a separate HSM key per instance, 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 Step 4.

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.

See below for CA-specific instructions.

db_client​

Most databases only need to trust the external root CA and intermediate CAs. It's not necessary to trust the override CA certificate directly. Those include, but are not limited to, MariaDB, MySQL, PostgreSQL, Redis and Oracle.

We recommend checking your database documentation and verifying access after applying the CA override in a controlled environment.

windows​

Your configuration depends on whether you use AD or local setups.

For AD, import the CA chain's trusted roots and intermediates as required by the domain, and publish the override CA certificate directly to NTAuth.

Run the following command on a domain-joined Windows host to verify that the NTAuth store includes the override CA certificate.

certutil -viewstore -enterprise NTAuth

Additionally, verify the override CA chain:

certutil -verify -urlfetch .\override.cer

For local setups, import the CA chain to the Local Computer "Trusted Root CAs" and "Intermediate CAs" stores, as appropriate. An externally signed override CA certificate is usually an intermediate CA.

Verify the override CA chain:

certutil -verify -urlfetch .\override.cer

Step 4/5. Create the certificate overrides​

After issuing certificates and configuring downstream trust, create a certificate override for each certificate:

tctl auth create-override --type=windows cert.pem

Disabled overrides​

You may create a disabled override and enable it later. A disabled override works as if it didn't exist, leaving signing to the self-signed CA certificate.

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.

Create the disabled override:

tctl auth create-override --type=windows cert.pem --disabled

Enable it:

tctl auth update-override --type=windows --public-key=public-key --set-disabled=false

You can find the public key of the target override using the tctl auth pub-key-hash command or reading it from the ca_override itself.

Using tctl auth pub-key-hash:

tctl auth pub-key-hash --cert=cert.pem

Using tctl get:

tctl get ca_overrides/windows

Alternatively, you may edit directly using:

tctl edit ca_overrides/windows

Multi-Auth Service clusters with per-instance HSM keys​

In clusters with multiple Auth Service instances and a separate HSM key per instance, each Auth Service instance may only be able to access its own private keys. In this scenario, make sure all Auth Service instances are online and healthy, then create your overrides in the disabled state. The Auth Service instances automatically sign CRLs in the background for their respective keys. After a certificate override has a matching CRL it can be enabled.

Create the override. Repeat for each certificate override.
tctl auth create-override --disabled --type=windows cert.pem

Verify that CRLs are present.
tctl get ca_overrides/windows

Enable the override. Repeat for each certificate override.
tctl auth update-override --type=windows --public-key=public-key --set-disabled=false

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
}