Get Started With Pomerium
Welcome to Pomerium Fundamentals - Get Started! This is your starting point to learning the essentials of how Pomerium works so you can use it effectively to secure your own web apps and services.
To set expectations, we estimate the full Fundamentals course will take more or less an hour of your time, resulting in a fully deployed, production-level Pomerium instance.
This tutorial teaches you how to set up Pomerium using Docker and Docker Compose.
In a later tutorial, we will cover how to self-host and run Pomerium in a virtual machine environment. For now, we will work in containerized environments so we can easily configure Pomerium and run it alongside other services, which you can access behind Pomerium.
Step 1: Create a new project
For the purposes of this guide, we’ll call this project pomerium_quickstart (but name it whatever you want).
Your project will contain all the files and configurations you need to run Pomerium Core.
The directory structure will look like this:
- The
config.yamlfile configures Pomerium itself - The
docker-compose.yamlfile configures and runs your Docker containers
We’ll configure these files together in the next section.
Pomerium Core is our open-source, identity-aware reverse gateway. Pomerium consists of 4 service identities (that can be deployed together or independently), including the:
- Proxy service — the red-linen rope
- Authentication service — the bouncer checking the user's ID to see if they are who they say they are
- Authorization service — the bouncer checking if the user is authorized to do what they want to do
- Databroker service — the waiter remembering the user’s current session to offer the best user experience
When you run Core, these services work together to secure your apps and connect your users to them.
Step 2: Set up Pomerium
Create a YAML file called config.yaml.
Add the following configuration settings to config.yaml:
authenticate_service_url: https://authenticate.pomerium.app
routes:
- from: https://verify.localhost.pomerium.io
to: http://verify:8000
policy:
- allow:
or:
- email:
is: user@example.com
Update user@example.com to use your desired email address – otherwise, the example won’t work! (Unless, of course, your actual email address is user@example.com, in which case, carry on.)
Understanding the configuration file
The authenticate_service_url setting provides an externally accessible URL that Pomerium’s Authentication Service uses to manage client authentication. It works like this:
- You request to access an app protected behind Pomerium
- The Authentication Service receives the request, and uses the
authenticate_service_urlto redirect you to the Identity Provider to sign in
(If it helps to understand why, it’s because our waiter, Pomerium, needs to cross-reference with a list of users to go, “Ah, I see you’re on our list. Right this way, please.”)
Pomerium relies on an Identity Provider (IdP) to authenticate users and authorize requests (it’s the list we just mentioned, except the IdP gives you a token badge so Pomerium recognizes you).
You probably noticed this configuration file doesn’t include an Identity Provider – that’s because you’re using Pomerium’s Hosted Authentication Service, which provides a preconfigured identity provider for you.
This way, you can just plug and play. (Don’t worry; we’ll show you how to configure your own identity provider later!)
We’ll learn more about routes in the next section, but for now, just know that the from route is the externally accessible URL that Pomerium will redirect you to after authenticating with your identity provider.
Step 3: Set up Docker Compose
Create a YAML file called docker-compose.yaml.
Add the following configuration settings to docker-compose.yaml:
version: '3'
services:
pomerium:
image: cr.pomerium.com/pomerium/pomerium:latest
volumes:
- ./config.yaml:/pomerium/config.yaml:ro
ports:
- 443:443
verify:
image: cr.pomerium.com/pomerium/verify:latest
expose:
- 8000
This file includes the Docker images and instructions to run Pomerium and the Verify service in Docker containers.
Step 4: Run Pomerium
Go into your project’s root directory and run the following command:
docker compose up
Now, go to the Verify service in your browser.
You may have some questions, like:
Why is the URL insecure?
If you don’t provide certificates to verify the upstream service, Pomerium will generate self-signed certificates for you. Because the certificates are self-signed, your browser will throw a self-signed certificate warning.
To bypass this warning:
- Click anywhere in the browser window
- Enter
thisisunsafe(no spaces) and hit enter - Repeat step 2 if you’re prompted with the same error
Later, we will cover how to self-host Pomerium using Autocert, which will automate the process of managing certificates for your upstream services.
Identity verification failed, why?
The simple answer is: You haven't configured Pomerium to handle JWTs yet. The Verify service expects a cryptographically signed JWT, which contains identifying information about the user in the form of JWT claims. Without the JWT itself (and a way to verify the signature), the Verify service can't identity the user.
In a later tutorial, you will configure Pomerium and the Verify service to successfully verify a user’s identity.
Summary
Great job! If you got this far, then you have everything you need to run Pomerium and continue on with our guided tutorials.
In the next section, we will dive deeper into Routes with Pomerium.
Configuration file state:
By now, your configuration files should look similar to this:
authenticate_service_url: https://authenticate.pomerium.app
routes:
- from: https://verify.localhost.pomerium.io
to: http://verify:8000
policy:
- allow:
or:
- email:
is: <your-email>@example.com
Docker Compose:
version: '3'
services:
pomerium:
image: cr.pomerium.com/pomerium/pomerium:latest
volumes:
- ./config.yaml:/pomerium/config.yaml:ro
ports:
- 443:443
verify:
image: cr.pomerium.com/pomerium/verify:latest
expose:
- 8000