Skip to main content
Version: vNext (upcoming release)

Generic OIDC

This guide covers how to configure a generic OpenID Connect (OIDC) provider to work with Pomerium.

Background

Pomerium provides default identity provider settings that allow you to seamlessly connect with a number of well-known identity provider (IdP) solutions. However, Pomerium can also connect with any generic OIDC provider if both Pomerium and the OIDC provider are properly configured.

To learn how a generic OIDC implementation works with Pomerium, you will configure Keycloak as your OIDC provider.

Before you start

This guide requires you to self-host the Keycloak server. To minimize set up time, you will deploy Pomerium, Keycloak, and the Pomerium Verify service in Docker containers.

To complete this guide, you need:

Set up Docker Compose

Create a docker-compose.yaml file and add the following configuration:

docker-compose.yaml
services:
mykeycloak:
image: quay.io/keycloak/keycloak:22.0.1
command:
- start-dev
environment:
- KEYCLOAK_ADMIN=admin
- KEYCLOAK_ADMIN_PASSWORD=admin
ports:
- 8080:8080
networks:
default:
aliases:
- keycloak.localhost.pomerium.io
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
environment:
JWKS_ENDPOINT: https://pomerium/.well-known/pomerium/jwks.json

Note the following points about this configuration:

  • start-dev runs the Keycloak server in Development mode
  • The admin console username and password are both admin
  • The Keycloak server is assigned a network alias (keycloak.localhost.pomerium.io) so Pomerium can generate a sign-in redirect URL that resolves to the Keycloak container on the host machine

Set up Keycloak

In your terminal, run Docker Compose:

docker compose up

When Keycloak is ready, navigate to http://localhost:8080 to access the Administration Console:

Access the Keycloak admin console

Sign in with the admin credentials.

Create a realm

Keycloak uses realms to manage sets of users, credentials, roles, and groups. When you start Keycloak, your instance comes with an admin realm called master.

To create a new non-admin group, create a new realm in the admin dashboard:

  1. Select the master dropdown
  2. Select Create Realm
  3. In the Realm name field, enter a name, like "Pomerium"
  4. Select Create

Create a new realm

Create a user

Your realm has no users at first. To add a user:

  1. Go to the admin console (http://localhost:8080/admin)
  2. Select Users
  3. Select Add users
  4. Enter a Username, a First name, and Last name
  5. Select Create

Create a user

Now, assign the user a password:

  1. Select the Credentials tab
  2. Select Set password
  3. Enter a password and confirm it
  4. Set Temporary to Off so the user doesn't have to reset the password at the first login
  5. Select Save

Set the user's password

Create a client

Lastly, you need to create a Client for the realm you just created:

  1. Go to the admin console (http://localhost:8080/admin)
  2. Select Clients, then Create client
  3. Keep Client type as OpenID Connect
  4. In the Client ID field, enter a name like mynewclient
  5. In the Authentication flow field, select Standard flow and Direct access grants
  6. Leave Login settings empty, and select Save

Create a client

Update the client you created:

  1. Under General Settings in the Name field, enter your Client ID in template literals (for example, ${mynewclient}) Enter client ID
  2. Go to Access settings
  3. In Root URL, enter ${authBaseUrl}
  4. In Home URL, enter /realms/<your_realm>/<your_client_id>/
  5. In Valid redirect URIs, enter https://authenticate.localhost.pomerium.io/oauth2/callback
  6. In Web Origins, enter https://authenticate.localhost.pomerium.io Add access settings
  7. Under Capabilities config, turn on Client authentication Turn on client authentication

Save your settings.

Get the client secret

In the client details page:

  1. select the Credentials tab
  2. Copy the Client secret Get client secret

You need to include the client secret in your Pomerium configuration file.

Set up Pomerium

Create a YAML file and add the following configuration:

config.yaml
authenticate_service_url: https://authenticate.localhost.pomerium.io

idp_provider: oidc
idp_client_id: 'mynewclient'
idp_client_secret: 'your_client_secret' # enter your client secret here
idp_provider_url: 'http://keycloak.localhost.pomerium.io:8080/realms/Pomerium'

signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSVA2TUN5UFI5OUNmSEVkU0s4cVdzbk51Q0RyMVZ3ay93RER1RVhyQitELzZvQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFQ0JTK3gyQnJRNVJqNHJFcU5PSEVsUFVESXJiRlNhRitoWEhEL1RYby9rQWVKU1lJSjJHVwpZMnE0a0NPNTU4RmdoYmxDTUplYVdjV1luT3JuZkpxeXRnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=

routes:
- from: https://verify.localhost.pomerium.io
to: http://verify:8000
allow_any_authenticated_user: true
pass_identity_headers: true

First, add your client secret to the configuration file.

Note the following points:

  • The idp_provider_url should match the Keycloak network alias in your Docker Compose file. So that it's valid, add the protocol (http://) and the correct path (/realms/<your_realm>) to the URL.
  • The signing_key is used by Pomerium to cryptographically sign the user's JWT, and is required for identity verification
  • The pass_identity_headers setting forwards the JWT Assertion Header to the upstream application
caution

Do not use the signing key in the example above in a production environment. See Signing Keys for more information on generating and using signing keys.

Access the Verify app

Access the Verify URL in your configuration file.

tip

If you notice a self-signed certificate warning, see Handle Self-Signed Certificate Warning to bypass it.

Pomerium should redirect you to the sign-in page of the Keycloak realm you created. Sign in with your user's credentials.

Sign in to Keycloak Realm

Once you sign in, you can verify that Pomerium handled the JWT and included the OIDC claims from Keycloak:

Access Verify app