Install and Configure Pomerium Proxy for your Services

A proxy server is a router that acts as a gateway between users and the internet. It is often referred to as an intermediary as it sits between the end-users and the web pages they visit online. A proxy provides a layer of security for the system. It can act as a web filter or firewall to protect the system from internet threats like malware. A proxy can be used to perform several tasks that include:

• Control the websites employees and staff access in the office
• Improve security in the organization.
• Balance internet traffic to prevent crashes
• Save bandwidth by caching files or compressing incoming traffic

There are many types of proxy servers in the market, these include forward proxy, transparent proxy, anonymous proxy, high anonymity proxy, distorting proxy, Datacenter proxy, residential proxy, public proxy, shared proxy, SSL Proxy, rotating proxy, and reverse proxy. These proxies offer different functionality to their users.

In this guide, we will systematically walk through how to install and configure Pomerium Proxy for your Services.

What is Pomerium Proxy?

Pomerium is an identity and context-aware reverse proxy used to secure access to applications and services at a scale. It is capable of creating a secure connection to services like MySQL, Redis, SSH e.t.c by creating a TCP tunnel to the service. It provides a standardized interface to add access control to applications even if the application itself does not have authorization/authentication baked-in.

It is commonly used as a VPN alternative, but unlike a VPN, it does not require a client for connection. It uses identity and context and not network locality to determine access.

Pomerium Proxy is commonly used cases for:

• Providing a single-sign-on gateway to internal applications.
• Enforcing dynamic access policy based on context, identity, and device identity
• Aggregating access logs and telemetry data.

The features offered by Pomerium Proxy are:

• Context-driven access: it uses identity and context to ensure secure access to internal applications, servers e.t.c from untrusted connections.
• Retain control over your data: Assert compliance in your current architecture without giving up control over data tenancy
• Support any app, on any platform: It supports a number of applications and integration such as Grafana, Prometheus e.t.c
• Use your preferred identity provider: Users can easily add their single sign-on authentication and authorization to any application. It supports all identity providers.
• Add access control to any app: It adds authentication and authorization to any application/server, therefore providing a centralized management panel for the organization.

Getting Started

There are quite a number of ways to install Pomerium Proxy. These include:

• From Binaries
• From Source
• On Kubernetes

In this guide, we will walk through how to install Pomerium Proxy using binaries. For this guide to work best, you need:

• A configured identity provider
• TLS certificates

First, update the system and install the required packages

##On Debian/Ubuntu
sudo apt update && sudo apt install vim curl -y

##On RedHat/Alma Linux/Rocky Linux
sudo yum install vim curl -y

Proceed and set the hostname on your system.

sudo hostnamectl set-hostname authenticate.localhost.pomerium.io

Modify /etc/hosts to accommodate your own IP address and hostname.

$ sudo vim /etc/hosts
192.168.200.51 authenticate.localhost.pomerium.io redis.localhost.pomerium.io ssh.localhost.pomerium.io

For this guide, we will use Self-signed certificates which can be generated using MKcert. The first thing to do is to download Mkcert binaries from the GitHub releases page.

Check the available version and export it with the command:

VER=v1.4.4

Then, download the binaries using the command:

##AMD64 
wget https://github.com/FiloSottile/mkcert/releases/download/$VER/mkcert-$VER-linux-amd64

##ARM64
wget https://github.com/FiloSottile/mkcert/releases/download/$VER/mkcert-$VER-linux-arm64

##ARM
wget https://github.com/FiloSottile/mkcert/releases/download/$VER/mkcert-$VER-linux-arm

Make the file executable and move it to your PATH

chmod +x mkcert-$VER-linux-* 
sudo mv mkcert-$VER-linux-* /usr/local/bin/mkcert

Now generate the certs with the command:

mkcert -install
   mkcert '*.localhost.pomerium.io'

After this, you will have the cert as _wildcard.localhost.pomerium.io.pem and the key as _wildcard.localhost.pomerium.io-key.pem. You will also have a CA in the $(mkcert -CAROOT)/rootCA.pem. You can copy and use the CA on your client to avoid SSL certificate warnings

#1. Install Pomerium Proxy on Linux

Pomerium Proxy can easily be installed on Linux. Begin by setting up the Cloudsmith repository. This can be done with the commands below:

##On Debian/Ubuntu
curl -1sLf \
  'https://dl.cloudsmith.io/public/pomerium/pomerium/setup.deb.sh' \
  | sudo -E bash

##On RedHat/Alma Linux/Rocky Linux
curl -1sLf \
  'https://dl.cloudsmith.io/public/pomerium/pomerium/setup.rpm.sh' \
  | sudo -E bash

Once the repository has been added, install Pomerium Proxy with the command:

##On Debian/Ubuntu
sudo apt update && sudo apt install pomerium

##On RedHat/Alma Linux/Rocky Linux
sudo yum install pomerium pomerium-cli

#2. Configure Pomerium Proxy on Linux

Once installed, you can make the desired configurations to Pomerium Proxy. The default configuration file is stored at /etc/pomerium/config.yaml, but you can still create the config.yaml file in a preferred location.

Open this file for editing:

sudo vim /etc/pomerium/config.yaml

This file stores and determines Pomerium’s configuration settings, routes, and access policies. Pomerium has the ability to create secure connections to your services by creating a TCP tunnel. In this guide, I will demonstrate how to create a TCP route for your services.

Set the bind port, certificate path, base64 shared and cookie secrets:

# To run on :443 set AmbientCapabilities=CAP_NET_BIND_SERVICE
# in a systemd override
address: :443

authenticate_service_url: https://authenticate.localhost.pomerium.io
certificates:
  - cert: /etc/pomerium/cert.pem
    key: /etc/pomerium/key.pem
shared_secret: <provide base64 string here>
cookie_secret: <provide base64 string here> 
idp_provider: "github"
idp_client_id: "REDACTED"       // github application ID 
idp_client_secret: "REDACTED"   // github application secret  

routes:
...

In the above file, provide your

• idp_provider: can be Github, Google, Azure AD, AUth0, Okta, Apple etc. See how to configure your Identity provider here.
• idp_client_id: For Github, this will be your application ID
• idp_client_secret: For Github, this will be your GitHub application secret

For this guide, we have used Github as the Identity provider. To create a GitHub OAuth 2.0 Application, login to your Github account and navigate to Developer settings ➞ OAuth Apps and select New OAuth App. Provide the required information as shown.

Once created, you will have your Client Secret along with the Client ID.

To generate the base64 string with 32 bytes for the shared_secret and cookie_secret, you can use the generate plus site or from the terminal with the command:

echo -n 'my-32-bytes-character-string-here' | base64

For Example

echo -n 'abcdefghijklmnopqrstuvwxyz012345' | base64

Once the secrets have been provided, proceed and create a route.

Create a TCP Route​

To specify a new TCP route, you need to add tcp+ prefix in the from field together with a port. For example:

  - from: tcp+https://ssh.localhost.pomerium.io:22

The To field uses the tcp:// as a protocol, specifying the address and port to listen on. For example:

    to: tcp://127.0.0.1:22

Below is a good example of how to route the SSH service on the host. In the opened file, add/modify the below lines under routes

routes:
.......
  - from: tcp+https://ssh.localhost.pomerium.io:22
    to: tcp://ssh:22
    preserve_host_header: true
    policy:
      - allow:
          or:
            - email:
                is: [email protected]

In the above file, replace the hostname and the email address correctly. below is another example for Redis(with remote access enabled in /etc/redis/redis.conf):

  - from: tcp+https://redis.localhost.pomerium.io:6379
    to: tcp://redis:6379
    policy:
      - allow:
          or:
            - email:
                is: [email protected]

Below is a sample of how my configuration looks:

Once the changes have been made, save the file, proceed and copy the certificates we generated earlier to the set path:

sudo cp _wildcard.localhost.pomerium.io.pem /etc/pomerium/cert.pem
sudo cp _wildcard.localhost.pomerium.io-key.pem /etc/pomerium/key.pem

Set the required permissions for the certs:

sudo chmod 775 /etc/pomerium/cert.pem
sudo chmod 775 /etc/pomerium/key.pem

Also, run the below command to allow Pomerium to bind to port 443(the default HTTPS port)

echo -e "[Service]\nAmbientCapabilities=CAP_NET_BIND_SERVICE" | sudo SYSTEMD_EDITOR=tee systemctl edit pomerium

Now start and enable the service:

sudo systemctl enable --now pomerium

Check the status of the service:

$ systemctl status pomerium.service
● pomerium.service - Pomerium
     Loaded: loaded (/lib/systemd/system/pomerium.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2022-12-01 09:19:50 EAT; 3s ago
   Main PID: 5382 (pomerium)
      Tasks: 15 (limit: 4575)
     Memory: 98.8M
     CGroup: /system.slice/pomerium.service
             ├─5382 /usr/sbin/pomerium -config /etc/pomerium/config.yaml
             └─5391 /tmp/pomerium-envoy3127998534/envoy -c envoy-config.yaml --log-level info --log-format [LOG_FORMAT]%l--%n--%v --log-format-escaped --use-dynamic-base-id --base-id-path /tmp/pomerium-envoy-base-id

If you have a firewall enabled, allow the port through it:

##For UFW
sudo ufw allow 443

##For Firewalld
sudo firewall-cmd --add-port=443/tcp --permanent
sudo firewall-cmd --reload

#3. Install and Configure Pomerium Client

Once the route has been created, you can connect to the service using the pomerium-cli. The CLI can be installed from the added repository above or using binaries from the GitHub release page.

Pull the desired version, by exporting the latest version:

VER=v0.22.0

Now pull the binary:

##For amd64
wget https://github.com/pomerium/cli/releases/download/$VER/pomerium-cli-linux-amd64.tar.gz

##For arm64
wget https://github.com/pomerium/cli/releases/download/$VER/pomerium-cli-linux-arm64.tar.gz

##For armv6
wget https://github.com/pomerium/cli/releases/download/$VER/pomerium-cli-linux-armv6.tar.gz

Once downloaded, extract the archive:

tar -xvf pomerium-cli-linux-*.tar.gz

Move the binaries to your PATH:

sudo mv pomerium-cli /usr/local/bin

Verify your installation:

$ pomerium-cli
Usage:
  pomerium-cli [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  k8s         commands for the kubernetes credential plugin
  tcp         creates a TCP tunnel through Pomerium
  version     version

Flags:
  -h, --help      help for pomerium-cli
  -v, --version   version for pomerium-cli

Use "pomerium-cli [command] --help" for more information about a command.

To know how to use the TPC commands, run:

$ pomerium-cli tcp --help
creates a TCP tunnel through Pomerium

Usage:
  pomerium-cli tcp destination [flags]

Flags:
      --alternate-ca-path string      path to CA certificate to use for HTTP requests
      --browser-cmd string            custom browser command to run when opening a URL
      --ca-cert string                base64-encoded CA TLS certificate to use for HTTP requests
      --client-cert string            (optional) PEM-encoded client certificate
      --client-key string             (optional) PEM-encoded client certificate
      --disable-tls-verification      disables TLS verification
  -h, --help                          help for tcp
      --listen string                 local address to start a listener on (default "127.0.0.1:0")
      --pomerium-url string           the URL of the pomerium server to connect to
      --service-account string        the service account JWT to use for authentication
      --service-account-file string   a file containing the service account JWT to use for authentication

The next thing to do is to ensure that the client resolves to the Pomerium server domain. Modify the /etc/hosts as shown:

$ sudo vim /etc/hosts
192.168.200.51 authenticate.localhost.pomerium.io redis.localhost.pomerium.io ssh.localhost.pomerium.io

Now to establish a TCP tunnel to your service, use the command with the syntax below:

pomerium-cli tcp [hostname]:[port]

For example, for the created SSH route, we will establish the connection with the commands:

• With Trusted SSL certs:

pomerium-cli tcp ssh.localhost.pomerium.io:22 --listen localhost:2222 &

• With Trusted SSL certs and custom port:

The service can as well be started and run in the background. If you use any other port aside from 443, you will have the command as shown:

pomerium-cli tcp tcp+https://ssh.localhost:pomerium.io:8443/ssh.localhost.pomerium.io:2222 --listen localhost:2222 &

• With Self-signed certs:

For this guide, we will use the --disable-tls-verificationflag because we are using self-signed certs:

$ pomerium-cli tcp ssh.localhost.pomerium.io:22 --listen localhost:2222 --disable-tls-verification &
2022/12/01 09:54:12 listening on 127.0.0.1:2222

For Redis, the command will be:

pomerium-cli tcp redis.localhost.pomerium.io:6379 --listen 0.0.0.0:6379 --disable-tls-verification &

#4. Connect to Your Service On the Client

Now make a connection to the service using the Pomerium tunnel.

For SSH, use the command with the syntax:

ssh username@localhost -p 2222

Where “username” is the user available on the Pomerium server or where the tunnel has been directed.

If all is okay, your default web browser will be launched.

You will see this certificate warning, ignore it and proceed by clicking on the advanced option. The next thing to do is to authenticate the service. For example with Github as the Identify Provider, you will have this:

Authorize the application:

The redirection will happen and you should be authenticated as shown:

Back to the terminal, your connection should now happen.

Similar steps can be done for Redis. To make a connection, ensure you have the redis-cli tool and run the command:

redis-cli

Sample Output:

Learn more on how to create TCP routes and view examples here.

You can also log in to the Pomerium dashboard using the URL https://domain_name

Verdict

That is the end of this guide on how to install and configure Pomerium Proxy for your Services. Now you will always have secure and controlled access to your apps using your desired Identity provider. I hope this was helpful.

See other guides:

• How To Setup SSH and MySQL Bastion Server using Warpgate
• Configure Centralized SSH for Linux systems using ShellHub
• Install and Configure Squid Proxy Server Rocky Linux 9