Pomerium Core using Docker
In this quickstart guide, you'll run Pomerium Core with Docker containers.
Prerequisites
- A configured identity provider
- Docker and Docker Compose
Configure
Create a configuration file (e.g. config.yaml
) for defining Pomerium's configuration settings, routes, and access policies.
# See detailed configuration settings: https://www.pomerium.com/docs/reference/
authenticate_service_url: https://authenticate.localhost.pomerium.io
##################################################################################
# Identity provider settings : https://www.pomerium.com/docs/identity-providers/ #
# The keys required in this section vary depending on your IdP. See the #
# appropriate docs for your IdP to configure Pomerium accordingly. #
##################################################################################
idp_provider: google
idp_client_id: REPLACE_ME
idp_client_secret: REPLACE_ME
# Update the signing key: https://www.pomerium.com/docs/reference/signing-key
signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSURRemVZWDZyT2tuemFnTjRJVTYxaEtRc3pzY1EvRllmbzZPcXhWd2YvdGZvQY9HQ0NxR1NNNDkKQXdFSG9VUURRE0FFc1V0V2psYXZ3eHprSU9DVUNDeFVnTDJza2NjL3QxSTFmQXlxUDgrMWw5YU1CWDlzdm1pYgpRajJxcWFUbUJZZWhuQzhmak5LODZmVXhpc3d1SXN5bnp3PT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
# https://pomerium.com/reference/#routes
routes:
- from: https://verify.localhost.pomerium.io
to: http://verify:8000
policy:
- allow:
or:
- email:
is: user@example.com
pass_identity_headers: true
Update signing key
Generate a signing key:
# Generates an P-256 (ES256) signing key
openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem
# Prints the base64 encoded value of the signing key
cat ec_private.pem | base64
Add the base64-encoded signing key to the signing_key
variable in your config.yaml
file.
Keep track of the path to this file, relative to the docker-compose.yaml
file created in the next step. docker-compose.yaml
will need the correct relative path to your config.yaml
.
Copy the following docker-compose.yaml
file and modify it to include the correct path to your config.yaml
file:
version: "3"
networks:
main: {}
services:
pomerium:
image: pomerium/pomerium:latest
volumes:
## Mount your config file: https://www.pomerium.com/docs/reference/
- ./config.yaml:/pomerium/config.yaml:ro
ports:
- 443:443
## A network alias is only required when using `localhost.pomerium.io`
networks:
main:
aliases:
- authenticate.localhost.pomerium.io
## https://verify.localhost.pomerium.io --> Pomerium --> http://verify
verify:
networks:
main: {}
image: pomerium/verify:latest
expose:
- 8000
Run
Run Docker Compose:
docker compose up
Docker will automatically download the required container images for Pomerium and verify. Then, Pomerium will run with the configuration details set in the previous steps.
You should now be able to access the routes (e.g. https://verify.localhost.pomerium.io
) as specified in your policy file.
Handle self-signed certificate warning
When navigating to the https://verify.localhost.pomerium.io
route defined in your policy, you may encounter the following self-signed certificate warning:
To resolve this error:
- Select Advanced
- Select Proceed to verify.localhost.pomerium.io (unsafe)
Your browser will redirect you to the verify
route.
Under Signed Identity Token, you will see a list of JWT claims with your user details:
Next Steps
Now, you can experiment with adding services to Docker and defining routes and policies for them in Pomerium. See Guides for help or inspiration.
This is a test environment! If you followed all the steps in this doc your Pomerium environment is not using trusted certificates. Remember to use a valid certificate solution before moving this configuration to a production environment. See Certificates for more information.