# Pomerium Enterprise Quickstart
# Before You Begin
This document assumes:
- A non-containerized environment, either your local computer or a virtual machine (vm). While Pomerium is designed to scale with your production environment, we'll leave containerization and infrastructure as code (IaC) out for now, to focus on learning how Pomerium Enterprise works.
sudoprivileges on the host.
- You already have the open-source Pomerium base installed. If not, follow this doc before you continue.
- While an existing route is not required, we suggest implementing one test route to validate your identity provider (IdP) configuration.
- Pomerium Enterprise requires a relational database. PostgreSQL 9+ is supported.
- Securing the database connection with TLS may not be required, especially for a local installation, but is strongly recommended for production deployments. Therefor, this guide will assume a TLS-secured database connection.
- A supported data broker backend. Currently we support Redis.
- As with the database, TLS encryption is strongly recommended for production deployments.
- Pomerium Enterprise requires Linux amd64/x86_64. It can manage Pomerium instances on other platforms, however.
- Each Console instance should have at least:
- 4 vCPUs
- 8G RAM
- 100G of disk wherever logs are stored
- Each Postgres instance should have at least:
- 4 vCPUs
- 8G RAM
- 20G for data files
- Each Redis instance should have at least:
- 2 vCPUs
- 4G RAM
- 20G for data files
# Install Pomerium Enterprise
Pomerium publishes standard OS packages for RPM and DEB based systems. The repositories require authentication via username and access key. These credentials will be issued to you during the onboarding process.
# System Service
Once the package is installed, enable and start the system service:
sudo systemctl enable --now pomerium-console
# Initial Configuration
Like the open-source Pomerium base, Pomerium Enterprise is configured through a single config file, located at
# Update Pomerium
Open your Pomerium config file,
Add a list item in the
routesblock for the Enterprise Console:
routes: - from: https://console.localhost.pomerium.com to: https://localhost:8701 policy: - allow: or: - domain: is: companydomain.com pass_identity_headers: true
The example value for
to:assumes Pomerium and Pomerium Enterprise are running on the same test environment.
If you haven't already, set
signing_key. See the reference page for more information. The same signing key must be used in both Pomerium Core and Enterprise.
Define the databroker storage type and connection string. The example below assumes a local Redis server:
databroker_storage_type: redis databroker_storage_connection_string: redis://127.0.0.1:6379/0
# External Services
First configure the Console to communicate with the database and databroker service:
database_url: pg://user:firstname.lastname@example.org/pomerium?sslmode=require databroker_service_url: https://pomerium-cache.internal.mydomain.com shared_secret: XXXXXXXXXXXXXXXXXXX database_encryption_key: YYYYYYYYYYYYYYYYYYYYYY
For database uri options (especially TLS settings) see the PostgreSQL SSL Support (opens new window) documentation.
As a first-time setup step, you must also configure at least one administrator for console access. This user (or users) can then configure additional administrators in the console UI.
Once you have set permissions in the console UI, you should remove this configuration.
# TLS, Signing Key and Audience
If your open-source Pomerium installation is already configured to use TLS to secure back-end communication, you can do the same for Pomerium Enterprise by providing it a certificate, key, and optional custom CA file to validate the
tls_ca_file: /etc/pomerium-console/ca.pem tls_cert_file: /etc/pomerium-console/cert.pem tls_key_file: /etc/pomerium-console/key.pem
For proof-of-concept installations in the same local system, this is not required.
signing_keyto match Pomerium's.
audiencekey to match the
fromdomain value from your Pomerium configuration, excluding protocol:
This sets the expected "audience" key in the JWT header to match what's provided by open-source Pomerium as it proxies traffic to the Enterprise Console UI.
Once complete, your
/etc/pomerium-console/config.yaml file should look something like this:
database_url: pg://user:email@example.com/pomerium?sslmode=require databroker_service_url: https://pomerium-cache.internal.mydomain.com shared_secret: "XXXXXXXXXXXXXXXXXXX" database_encryption_key: "YYYYYYYYYYYYYYYYYYYYYY" # change / remove this after initial setup administrators: firstname.lastname@example.org tls_ca_file: /etc/pomerium-console/ca.pem tls_cert_file: /etc/pomerium-console/cert.pem tls_key_file: /etc/pomerium-console/key.pem signing_key: "ZZZZZZZZZZZZZZ" audience: console.localhost.pomerium.com
# Next Steps
# Generate Recovery Token
In the event that you lose access to the console via delegated access (the policy defined in Pomerium), there exists a fallback procedure to regain access to the console via a generated recovery token.
To generate a token, run the
pomerium-console generate-recovery token command with the following flags:
| ||base64-encoded encryption key for encrypting sensitive data in the database.|
| ||The database to connect to (default "|
| ||The namespace to use (default "|
| ||Where to save the JWT. If not specified, it will be printed to stdout.|
| ||The amount of time before the recovery token expires. Requires a unit (example: |
You can run the
pomerium-console binary from any device with access to the database.