Connecting to a Heroku Postgres Database with Enhanced Certificates
Last updated May 12, 2022
Table of Contents
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.
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.
Enhanced Certificates provisions publicly verifiable end entity TLS certificates from the ISGR Root Certificates.
Heroku Prerequisites
The following Heroku resources are required for Enhanced Certificates:
- A Standard, Premium, Private, or Shield tier Heroku Postgres database, version 13 or greater
Enabling Enhanced Certificates
Installing the Heroku Data CLI Plugin
To install the data plugin, use the following CLI command:
$ heroku plugins:install data
Provisioning 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
After enabling Enhanced Certificates for a Heroku Postgres database, applications and clients can connect using the sslmode=verify-full parameter to prevent MITM attacks. For language-specific instructions, see Connecting to Heroku Postgres.
Adding Enhanced Certificates to an Existing Heroku Postgres Database
To enable Enhanced Certificates on an existing Heroku Postgres database, use the heroku data:enhanced-certificates:enable CLI command:
$ 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 replace server side certificates when enabled. If you are using MTLS, you must download and use the new CA to verify your connection. For more information about how to download the certificates, see Setting client-side certificates.
After enabling Enhanced Certificates for a Heroku Postgres Database, applications and clients can connect using the sslmode=verify-full parameter to prevent MITM attacks. For language-specific instructions, see Connecting to Heroku Postgres.
Adding Enhanced Certificates from an existing Heroku Postgres database changes the value of its connection URL. This updates the add-on config var (DATABASE_URL by default), creating a new release of the application and forcing a restart. The previous connection URL for the database remains valid, but external clients and applications must be updated to use the new connection string to use full SSL verification.
Disabling Enhanced Certificates
To disable Enhanced Certificates on an existing Heroku Postgres database, use the heroku data:enhanced-certificates:disable CLI command:
$ 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 the value of its connection URL. This updates the add-on config var (DATABASE_URL by default), creating a new release of the application and forcing a restart.
If your app or external clients connect to your database with server certificate validation (for example, using sslmode=verify-full), update their configuration to sslmode=require before disabling Enhanced Certificates to avoid failed connections to your Heroku Postgres database.
Displaying Enhanced Certificates Status
To display the Enhanced Certificates status of an existing Heroku Postgres database, run the heroku data:enhanced-certificates:status CLI command:
$ heroku data:enhanced-certificates:status DATABASE -a example-app
=== Enhanced Certificates for postgresql-colorful-12345.
Status: Enabled
Connecting 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 toverify-full. This parameter makes applications automatically perform certificate verification and ensure that the database hostname matches its certificate when the feature is enabled.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.