"x509: certificate signed by unknown authority" from Terraform CLI with a Terraform Enterprise remote

Problem

When using the remote backend in Terraform to execute runs on a Terraform Enterprise instance that uses a custom Certificate Authority (CA), client commands such as terraform login fail with one of the following errors:

x509: certificate signed by unknown authority

x509: certificate is not trusted

Cause

When Terraform Enterprise is configured with a custom CA, any client connecting to it must also trust that CA to validate the SSL/TLS certificate chain. When you use the Terraform CLI, the machine running the terraform command must have the Terraform Enterprise CA certificate installed in its operating system's trust store.

Solutions

To resolve this issue, you must add the Terraform Enterprise CA certificate to the trust store of the client machine where you run terraform commands. The procedure varies depending on the operating system.

First, you must obtain the CA certificate from your Terraform Enterprise instance. You can export the PEM-formatted CA certificate with the following command on the Terraform Enterprise instance.

Replicated

replicatedctl app-config export --template '{{.ca_certs.Value}}' > tfe-ca.pem

Flexible Deployment Options (FDO) Docker/Podman

cp /path/to/certs_dir/cert.pem tfe-ca.pem

After you have the tfe-ca.pem file, follow the instructions for your operating system.

Solution 1: Configure the Windows Trust Store

1. Convert the PEM-formatted CA certificate to the PFX format using OpenSSL.

   openssl pkcs12 -export -in tfe-ca.pem -out tfe-ca.pfx

2. Transfer the tfe-ca.pfx file to the client machine.
3. Click Start, type mmc, and press Enter.
4. Click Yes to start the Microsoft Management Console.
5. Select File > Add/Remove Snap-in.
6. Under Available snap-ins, select Certificates and click Add.
7. Select Computer account, then click Next.
8. Click Finish, then click OK.
9. Expand Certificates, right-click Trusted Root Certification Authorities, and select All Tasks > Import.
10. Click Next.
11. Click Browse, select your tfe-ca.pfx certificate file, and click Open.
12. Click Next, Next, then Finish.
13. When the "import was successful" message appears, click OK.
14. Select File > Save, then Save again.
15. Close the Microsoft Management Console.

Solution 2: Configure the macOS Keychain

1. Convert the PEM-formatted CA certificate to the DER format (.cer) using OpenSSL.

   openssl x509 -inform PEM -in tfe-ca.pem -outform DER -out tfe-ca.cer

2. Transfer the tfe-ca.cer file to the client machine (e.g., to the ~/Downloads folder).
3. Open the Terminal application.

4. Run the following command to add the certificate to the system keychain. This example assumes the file is named tfe-ca.cer.

   sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/Downloads/tfe-ca.cer

5. Enter your password when prompted and press Return.
6. Close the Terminal.

Solution 3: Configure the Linux Trust Store

Note: This procedure assumes the Linux distribution uses ca-certificates, which includes supported distributions like Red Hat-based and Debian-based systems.

1. Transfer the PEM-formatted CA certificate (tfe-ca.pem) to the client machine (e.g., to the ~/Downloads folder).
2. Open a command-line terminal.

3. Copy the CA certificate to the trust store source directory. This example renames the file to tfe-ca.crt for clarity.

   sudo cp ~/Downloads/tfe-ca.pem /etc/pki/ca-trust/source/anchors/tfe-ca.crt

4. Update the system's CA trust store.

   sudo update-ca-trust

After completing these steps, Terraform CLI commands should connect to Terraform Enterprise without certificate errors.

Additional Information

For more information on how to download the Terraform Enterprise CA certificate, refer to the guide on Tracing SSL certificate chain issues in Terraform Enterprise.