Last updated April 20, 2023

Enhanced Certificates can help you protect against man-in-the-middle attacks by using an sslmode of verify-full when connecting to a Heroku Postgres database. The Enhanced Certificates feature provisions publicly verifiable end entity TLS certificates from the ISGR Root Certificates.

Overview

Prerequisites

• A Standard, Premium, Private, or Shield tier Heroku Postgres database, version 13 or greater

Enable Enhanced Certificates

Install the Heroku Data CLI Plugin

To install the data plugin, use the following CLI command:

$ heroku plugins:install data

Provision a New Heroku Postgres Database with Enhanced Certificates

To provision a Heroku Postgres database with Enhanced Certificates Beta, pass the --enhanced-certificates-beta flag to the add-on creation command:

$ heroku addons:create heroku-postgresql:standard-0 -a example-app --enhanced-certificates-beta

Add Enhanced Certificates to an Existing Heroku Postgres Database

To enable Enhanced Certificates on an existing Heroku Postgres database, use the

$ heroku data:labs:enable enhanced-certificates -a example-app --addon=ADDON_NAME
Enabling enhanced-certificates on ADDON_NAME... done

Alternatively, you can use the heroku data:enhanced-certificates:enable CLI command instead:

$ heroku data:enhanced-certificates:enable DATABASE_URL -a example-app
Enabling Enhanced Certificates Beta on example-app... done

It can take 15 minutes or more to provision Enhanced Certificates. You can check the current status with the heroku data:enhanced-certificates:status command.

Disable Enhanced Certificates

If your app or external clients connect to your database with server certificate validation, you must update their configuration before disabling the Enhanced Certificates feature.

For example, if the configuration used sslmode=verify-full, update it to sslmode=require before disabling the database’s enhanced certificate to avoid failed connections.

To disable Enhanced Certificates on an existing Heroku Postgres database,

$ heroku data:labs:disable enhanced-certificates -a example-app --addon=ADDON_NAME
Disabling enhanced-certificates on ADDON_NAME... done

Alternatively, you can use the heroku data:enhanced-certificates:disable CLI command instead:

$ heroku data:enhanced-certificates:disable DATABASE_URL -a example-app
Disabling Enhanced Certificates Beta on postgresql-colorful-12345... done

Display Enhanced Certificates Status

To display the Enhanced Certificates status of an existing Heroku Postgres database,

$ heroku data:labs:list ADDON_NAME -a example-app
=== Experimental Features Available for ADDON_NAME:
[+] enhanced-certificates   Provides publicly signed TLS certificates for connectivity to your addon
[ ] wal-compression         Write-ahead log compression on Heroku Postgres addons

Alternatively, you can use the heroku data:enhanced-certificates:status CLI command instead:

$ heroku data:enhanced-certificates:status DATABASE -a example-app
=== Enhanced Certificates for postgresql-colorful-12345.
Status: Enabled

Connect to a Heroku Postgres Database with Enhanced Certificates

The Enhanced Certificates feature modifies the structure of the connection string of the database to include the following parameters:

• sslmode, set to verify-full. This parameter prevents MITM attacks by automatically performing certificate verification and ensuring that the database hostname matches its certificate. For language-specific instructions on how applications and clients can connect, see Connecting to Heroku Postgres.
• sslrootcert, set to /etc/ssl/certs/ca-certificates.crt. This parameter points to the location of the file containing SSL certificate authority (CA) certificates in Heroku dynos.
• Database clients and applications can also set a different SSL mode (like sslmode=require) to connect to a Heroku Postgres database with Enhanced Certificates. All connections to Heroku Postgres databases require SSL connections.