{"token_count": 2928} # Certificate Authority Overrides is available only with Teleport Enterprise. 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](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/ver/19.x/get-started/deploy-community.md). - 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** ``` $ TELEPORT_DOMAIN=teleport.example.com:443 $ TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')" ``` **Windows - Powershell** ``` $ $TELEPORT_DOMAIN = "teleport.example.com:443" $ $TELEPORT_VERSION = (Invoke-RestMethod -Uri "https://${TELEPORT_DOMAIN}/v1/webapi/find").server_version ``` 2. Follow the instructions for your platform to install `tctl` and `tsh` clients: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v$TELEPORT_VERSION-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/ver/19.x/installation/single-machine.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * 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](https://goteleport.com/docs/ver/19.x/enroll-resources/desktop-access/active-directory.md#step-37-configure-a-gpo-to-allow-teleport-connections) or [local](https://goteleport.com/docs/ver/19.x/enroll-resources/desktop-access/getting-started.md#step-14-prepare-windows) 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 } ```