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

Introduction

When deploying Terraform Enterprise (TFE), users sometimes encounter TLS errors such as:

x509: certificate signed by unknown authority

Problem

This error often occurs when TFE or its agents are configured with self-signed certificates that are either:

Missing Subject Alternative Names (SAN) entries.
Not trusted by the operating system or container runtime.

This article explains:

Why does the error happen in TFE environments? How to generate a valid self-signed certificate with SANs. How to configure TFE or supporting tools to trust your certificates.

Cause

TFE Agent Registration

During agent registration, you may see logs like:

[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"

This error occurs because:

The agent uses Go’s HTTP client, which strictly validates SANs. The TFE hostname certificate may be self-signed or signed by an internal CA unknown to the system

API Token Usage

Even if tokens are valid, Terraform CLI or API calls may fail if TFE’s certificate is not trusted:

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

How to Check If SANs Are Missing

Run:

openssl x509 -in tfe.crt -text -noout

Look for:

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

If this section is missing, clients may reject the certificate, even if the Common Name (CN) matches.

Overview of possible solutions

How to Generate a Self-Signed Certificate With SANs

Below is the recommended method for TFE environments.

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

Outcome

SSL connection will be successful without any issues.

Additional Information

Prefer certificates signed by a trusted internal CA or public CA if possible.
Please make sure that: Subject Alternative Names match the TFE hostname used in CLI/API calls. Agents and clients trust the certificate chain.
For air-gapped TFE installations, distribute the CA certificate to all relevant nodes and containers.

References

https://developer.hashicorp.com/terraform/enterprise/deploy/prepare-host