Skip to main content

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.
    • root or sudo privileges 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. Therefore, this guide will assume a TLS-secured database connection.

Requirements​

  • 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

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.

  1. To automatically configure the repository for Debian and Ubuntu distributions, run the following command replacing [access-key]:

    curl -1sLf \
    'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.deb.sh' \
    | sudo -E bash

    Or to manually configure, you can manually import the apt key, then create a new .list file in /etc/apt/source.list.d. Make sure to replace the distro and version:

    curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key' | apt-key add -

    echo "deb https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/deb/debian buster main" | sudo tee /apt/sources.list.d/pomerium-console.list

  2. Update apt and install Pomerium Enterprise:

    sudo apt update; sudo apt install pomerium-console

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 /etc/pomerium-console/config.yaml.

Update Pomerium​

Open your Pomerium config file, /etc/pomerium/config.yaml.

  1. Add a list item in the routes block for the Enterprise Console:

    /etc/pomerium/config.yaml
    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.

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

    /etc/pomerium/config.yaml
    signing_key: 'ZZZZZZZZZZZZZZ'

  3. Define the databroker storage type and connection string. The example below assumes a local Postgres server:

    /etc/pomerium/config.yaml
    databroker_storage_type: postgres
    databroker_storage_connection_string: postgres://user:pass@dbhost.internal.mydomain.com/pomerium?sslmode=require

With these changes made to Pomerium Core, we can begin editing the Pomerium Console configuration.

External Services​

First configure the Console to communicate with the database and databroker service:

/etc/pomerium-console/config.yaml
database_url: postgres://user:pass@dbhost.internal.mydomain.com/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 documentation.

Administrators​

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.

/etc/pomerium-console/config.yaml
administrators: you@mydomain.com

Once you have set permissions in the console UI, you should remove this configuration.

TLS, Signing Key and Audience​

  1. 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 databroker_service_url connection:

    /etc/pomerium-console/config.yaml
    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.

  2. Set the signing_key to match Pomerium's.

  3. Set the audience key to match the from domain value from your Pomerium configuration, excluding protocol:

    /etc/pomerium-console/config.yaml
    audience: console.localhost.pomerium.com

    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.

License Key​

Finally, add your license key to the configuration file:

/etc/pomerium-console/config.yaml
license-key: YOURLICENSEKEY

Once complete, your /etc/pomerium-console/config.yaml file should look something like this:

/etc/pomerium-console/config.yaml
database_url: postgres://user:pass@dbhost.internal.mydomain.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: you@mydomain.com

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

license-key: YOURLICENSEKEY

Next Steps​

Pomerium Enterprise assumes access to a Prometheus data store for metrics. See Configure Metrics to learn how to configure access.

Troubleshooting​

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.

Pomerium Enterprise Recovery Sign In

To generate a token, run the pomerium-console generate-recovery token command with the following flags:

FlagDescription
--database-encryption-keybase64-encoded encryption key for encrypting sensitive data in the database.
--database-urlThe database to connect to (default "postgresql://pomerium:pomerium@localhost:5432/dashboard?sslmode=disable").
--namespaceThe namespace to use (default "9d8dbd2c-8cce-4e66-9c1f-c490b4a07243" for Global).
--outWhere to save the JWT. If not specified, it will be printed to stdout.
--ttlThe amount of time before the recovery token expires. Requires a unit (example: 30s, 5m).
tip

You can run the pomerium-console binary from any device with access to the database.