From source

Prerequisites

Download

Retrieve the latest copy of pomerium's source code by cloning the repository.

git clone https://github.com/pomerium/pomerium.git $HOME/pomerium

Make

Build pomerium from source in a single step using make.

cd $HOME/pomerium
make

The command will run all the tests, some code linters, then build the binary. If all is good, you should now have a freshly built pomerium binary in the pomerium/bin directory.

Configure

Environmental Configuration Variables

Create a environmental configuration file modify its configuration to to match your identity provider settings. For example, env:

#!/bin/bash

# Main configuration flags
# export ADDRESS=":8443"                      # optional, default is 443
# export POMERIUM_DEBUG=true                  # optional, default is false
# export SERVICE="all"                        # optional, default is all
# export LOG_LEVEL="info"                     # optional, default is debug

export AUTHENTICATE_SERVICE_URL=https://authenticate.corp.example.com
export AUTHORIZE_SERVICE_URL=https://authorize.corp.example.com

# Certificates can be loaded as files or base64 encoded bytes. If neither is set, a
# pomerium will attempt to locate a pair in the root directory
export CERTIFICATE_FILE="./cert.pem"        # optional, defaults to `./cert.pem`
export CERTIFICATE_KEY_FILE="./privkey.pem" # optional, defaults to `./certprivkey.pem`
# export CERTIFICATE="xxxxxx"                 # base64 encoded cert, eg. `base64 -i cert.pem`
# export CERTIFICATE_KEY="xxxx"               # base64 encoded key, eg. `base64 -i privkey.pem`

# Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
export SHARED_SECRET=9wiTZq4qvmS/plYQyvzGKWPlH/UBy0DMYMA2x/zngrM=
export COOKIE_SECRET=uPGHo1ujND/k3B9V6yr52Gweq3RRYfFho98jxDG5Br8=
# If set, a JWT based signature is appended to each request header `x-pomerium-jwt-assertion`
# export SIGNING_KEY="Replace with base64'd private key from ./scripts/self-signed-sign-key.sh"

# Identity Provider Settings

# Azure
# export IDP_PROVIDER="azure"
# export IDP_PROVIDER_URL="https://login.microsoftonline.com/REPLACEME/v2.0"
# export IDP_CLIENT_ID="REPLACEME
# export IDP_CLIENT_SECRET="REPLACEME"

# Gitlab
# export IDP_PROVIDER="gitlab"
# export IDP_PROVIDER_URL="https://gitlab.onprem.example.com" # optional, defaults to `https://gitlab.com`
# export IDP_CLIENT_ID="REPLACEME
# export IDP_CLIENT_SECRET="REPLACEME"

## GOOGLE
export IDP_PROVIDER="google"
export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
export IDP_CLIENT_ID="REPLACE-ME.googleusercontent.com"
export IDP_CLIENT_SECRET="REPLACEME"

# IF GSUITE and you want to get user groups you will need to set a service account
# see identity provider docs for gooogle for more info :
# export IDP_SERVICE_ACCOUNT=$(echo '{"impersonate_user": "bdd@pomerium.io"}' | base64)

# OKTA
# export IDP_PROVIDER="okta"
# export IDP_CLIENT_ID="REPLACEME"
# export IDP_CLIENT_SECRET="REPLACEME"
# export IDP_PROVIDER_URL="https://REPLACEME.oktapreview.com/oauth2/default"

# OneLogin
# export IDP_PROVIDER="onelogin"
# export IDP_CLIENT_ID="REPLACEME"
# export IDP_CLIENT_SECRET="REPLACEME"
# export IDP_PROVIDER_URL="https://openid-connect.onelogin.com/oidc" #optional, defaults to `https://openid-connect.onelogin.com/oidc`

# export SCOPE="openid email" # generally, you want the default OIDC scopes

# Proxied routes and per-route policies are defined in a policy provided either
# directly as a base64 encoded yaml/json file, or as a path pointing to a
# policy file (`POLICY_FILE`)
export POLICY_FILE="./policy.example.yml"

policy.yaml

Next, create a policy configuration file which will contain the routes you want to proxy, and their desired access-controls. For example, policy.example.yaml:

- from: httpbin.corp.beyondperimeter.com
  to: http://localhost:8000
  allowed_domains:
    - pomerium.io
    - gmail.com
  cors_allow_preflight: true
  timeout: 30s
- from: external-httpbin.corp.beyondperimeter.com
  to: httpbin.org
  allowed_domains:
    - gmail.com
- from: weirdlyssl.corp.beyondperimeter.com
  to: http://neverssl.com
  allowed_users:
    - bdd@pomerium.io
  allowed_groups:
    - admins
    - developers
- from: hello.corp.beyondperimeter.com
  to: http://hello:8080
  allowed_groups:
    - admins

Certificates

Place your domain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included script generates one from LetsEncrypt.

Run

Finally, source the the configuration env file and run pomerium.

source ./env
./bin/pomerium

Assuming your configuration file ready to go, you can simply use this one-liner.

make && source ./env && ./bin/pomerium

Browse to httpbin.your.domain.com. You should see something like the following in your browser.

Getting started