Terraform Enterprise - mTLS auth for PostgreSQL not able to connect – HashiCorp Help Center

Introduction

Problem

With the introduction of Terraform Enterprise version v202504-1 there is support for mTLS authentication for PostgreSQL as can be found here.

Within the Terraform Enterprise configuration you have used a configuration like the below example:

 # Database settings.
TFE_DATABASE_USER: "your_database_user"
TFE_DATABASE_HOST: "10.114.1.22"
TFE_DATABASE_NAME: "postgres"
TFE_DATABASE_PARAMETERS: sslmode=verify-full
TFE_DATABASE_USE_MTLS: true
TFE_DATABASE_CA_CERT_FILE: /etc/ssl/private/terraform-enterprise_postgres/root.crt
TFE_DATABASE_CLIENT_CERT_FILE: /etc/ssl/private/terraform-enterprise_postgres/client.crt
TFE_DATABASE_CLIENT_KEY_FILE: /etc/ssl/private/terraform-enterprise_postgres/client.key

After starting the Terraform Enterprise environment it stops and the logs show the following:

{"component":"terraform-enterprise","log":"2025-04-24T11:21:52.572Z 
[ERROR] terraform-enterprise: check failed: 
name=database duration=1m30.001925383s err=\"timeout: context deadline exceeded\""}

Checking with psql you are able to connect without issues to PostgreSQL:

psql "host=$TFE_DATABASE_HOST user=$TFE_DATABASE_USER dbname=$TFE_DATABASE_NAME $TFE_DATABASE_PARAMETERS sslcert=$TFE_DATABASE_CLIENT_CERT_FILE sslkey=$TFE_DATABASE_CLIENT_KEY_FILE sslrootcert=$TFE_DATABASE_CA_CERT_FILE"

psql (16.8 (Ubuntu 16.8-1.pgdg22.04+1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=#

Prerequisites

Terraform Enterprise >= v202504-1
PostgreSQL authentication with mTLS

Cause

The issue may be caused by PostgreSQL's certificates missing a Subject Alternative Name (SAN).

While the psql command-line tool allows connections without a subjectAltName, the Go libraries used by Terraform Enterprise enforce stricter TLS requirements and expect this field to be present and match the hostname/IP.

The official documentation about it can be found here

Solution

Verify that the certificate used by PostgreSQL contains that Subject Alternative Name.

Command to verify the certificate:

openssl req -in server.csr -noout -text

output:

Attributes:
  Requested Extensions:
    X509v3 Subject Alternative Name: 
      DNS:this-should-exist.example.com, IP Address:10.114.1.22

If the Subject Alternative Name is missing please contact the team responsible for the certificates. Explain the situation and what is missing.

Outcome

After having the correct Subject Alternative Name added to the certificate the connection should succeed.

Additional Information

Configuration parameter to use mTLS can be found here