Resolving “Certificate signed by unknown authority” Errors Due to Missing SAN in Self-Signed Certificates

Problem

When deploying or interacting with Terraform Enterprise (TFE), you may encounter a TLS error indicating that a certificate is signed by an unknown authority.

x509: certificate signed by unknown authority

This error can occur during TFE agent registration or when making API calls using the Terraform CLI.

Example Agent Log:

[ERROR] agent: Failed starting core plugin: error="failed configuring core: agent registration failed: POST https://<tfe_hostname>/api/agent/register giving up after 1 attempt(s): Post \"https://<tfe_hostname>/api/agent/register\": tls: failed to verify certificate: x509: certificate signed by unknown authority"

Example CLI Error:

Error: Failed to request workspace details: Get "https://<tfe_hostname>/api/v2/workspaces": x509: certificate signed by unknown authority

Cause

This error occurs because the TLS certificate used by Terraform Enterprise is not trusted by the client system. This is common in environments using self-signed certificates that are missing a Subject Alternative Name (SAN) entry.

Clients like the Terraform CLI and TFE agents use Go’s HTTP client, which strictly validates that the hostname being connected to (e.g., tfe.example.com) is present in the certificate's SAN list. If the SAN field is missing or does not contain the correct hostname, the client will reject the certificate, even if the Common Name (CN) matches.

Solutions

Solution 1: Verify the Certificate for SANs

Before generating a new certificate, check if your existing certificate is missing the required SAN entries.

Run the following openssl command, replacing tfe.crt with the path to your TFE public certificate.

$ openssl x509 -in tfe.crt -text -noout

In the output, look for the X509v3 Subject Alternative Name section. A correctly configured certificate will include the DNS hostname and/or IP address for your TFE instance.

X509v3 Subject Alternative Name: 
    DNS:<tfe_hostname>, IP Address:xxx.xxx.xxx.xxx

If this section is missing, you must regenerate the certificate with the correct SANs.

Solution 2: Generate a Self-Signed Certificate with SANs

To resolve the error, generate a new self-signed certificate that includes the TFE hostname in the SAN field.

Execute the command below, replacing example.com with your TFE hostname in both the -subj and -addext flags.

$ openssl req -nodes -x509 -sha256 -newkey rsa:4096 \
    -keyout cert.key \
    -out cert.crt \
    -days 365 \
    -subj "/C=US/ST=CA/L=San Francisco/O=MyOrganization/OU=Global/CN=example.com" \
    -addext "subjectAltName=DNS:example.com"

After generating the new certificate and key, apply them to your Terraform Enterprise instance according to the installation documentation.

Outcome

After configuring Terraform Enterprise and all client systems to use and trust the new certificate containing the correct SAN, TLS connections will succeed without x509: certificate signed by unknown authority errors.

Additional Information

• Whenever possible, prefer certificates signed by a trusted internal Certificate Authority (CA) or a public CA.
• Ensure that the Subject Alternative Names match the exact TFE hostname used in CLI, API, and agent configurations.
• In air-gapped or isolated environments, you must distribute the CA certificate to all nodes and containers that communicate with TFE.
• For more details on TFE host preparation, refer to the official Prepare the Host documentation.