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

Problem

Terraform Enterprise version v202504-1 introduced support for mTLS authentication for PostgreSQL, as detailed in the release notes.

When you configure Terraform Enterprise with mTLS for the PostgreSQL database using settings similar to the following example, the application fails to start.

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

The application logs show a timeout error when attempting to connect to the database.

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

However, a direct connection test using the psql command-line tool with the same credentials and certificates succeeds.

$ 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 version v202504-1 or newer.
PostgreSQL configured to require mTLS for authentication.

Cause

The issue may be caused by the PostgreSQL server's certificate missing a Subject Alternative Name (SAN). While the psql command-line tool may allow connections without a subjectAltName, the Go libraries used by Terraform Enterprise enforce stricter TLS validation and require this field to be present and match the hostname or IP address of the database server.

This requirement is noted in the Terraform Enterprise configuration documentation.

Solution

To resolve this issue, you must verify that the certificate used by the PostgreSQL server contains the correct Subject Alternative Name (SAN) for the database host.

Run the following openssl command on the certificate signing request (.csr) or the final server certificate (.crt) to inspect its contents.
```
$ openssl req -in server.csr -noout -text
```
Review the output and confirm the presence of the X509v3 Subject Alternative Name extension. The extension must contain a DNS or IP Address entry that matches the value of TFE_DATABASE_HOST.
```
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 or incorrect, you must generate a new certificate that includes the proper SAN. Contact the team responsible for managing your organization's certificates to request an updated certificate.

Outcome

After you configure PostgreSQL with a certificate that includes the correct Subject Alternative Name, Terraform Enterprise should connect to the database successfully.

Additional Information

For more details on the configuration parameters for mTLS, refer to the Terraform Enterprise documentation.