Heroku Data Labs: Enhanced Certificates for Heroku Postgres

Last updated November 27, 2024

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

Heroku Enhanced Certificates is currently available as a public beta. Until release to General Availability (GA), this feature is provided for evaluation purposes without guarantee of functionality or uptime.

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 @heroku-cli/plugin-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:

The addons:create example follows the syntax for Heroku CLI v9.0.0 or later. If you’re on v8.11.5 or earlier, use the command:

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

$ 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.

Enhanced certificates are currently incompatible with mTLS.

Adding enhanced certificates to an existing Heroku Postgres database changes its connection URL. The add-on config var (DATABASE_URL by default) updates, creating a new release of the application and forcing a restart. The previous connection URL remains valid, but you must update external clients and applications to the new one to use full SSL verification.

The data:labs:* commands require version 1.2.0 or higher of the Heroku Data CLI plugin. See the Heroku Data Labs article on how to update the Heroku Data CLI plugin.

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

Removing enhanced certificates from an existing Heroku Postgres database changes its connection URL. The add-on config var (DATABASE_URL by default) updates, creating a new release of the application and forcing a restart.

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.

Feedback

Log in to submit feedback.