Zero Fundamentals: Configure a Custom Identity Provider

So far, you've been using our Hosted Authenticate service, which provides a hosted authenticate service URL (authenticate.pomerium.app) and Pomerium's hosted identity provider to authenticate users.

In this guide, you'll replace Pomerium's hosted identity provider with your own custom identity provider to handle authentication.

Before you start

Make sure you've completed the following tutorials:

• Build a Simple Route
• Build a Simple Policy
• Single Sign-on with JWTs
• Build Advanced Policies
• Build Advanced Routes
• Build TCP Routes

Each tutorial builds on the same configuration files. In this guide, you'll replace our hosted identity provider solution with your own custom identity provider.

Choose an identity provider

You can integrate Pomerium with any identity provider (IdP) that supports the OAuth2.0 and OIDC protocols. For the purposes of this guide, we will use GitHub as the IdP (the configuration is simpler than other IdPs).

If you prefer to use another IdP instead of GitHub, feel free to do so. You can refer to our identity provider guides for setup instructions.

• Apple
• Auth0
• Microsoft Entra ID (Azure AD)
• Cognito
• GitHub
• GitLab
• Google
• Okta
• OneLogin
• Ping Identity
• OIDC

Configure your identity provider

In the Zero Console:

1. select Settings
2. Scroll to Identity Provider
3. Select Custom Identity Provider
4. In the Identity Provider dropdown, select GitHub
5. Enter your Client ID and Client Secret
6. Enter your Authenticate Service URL

If you still want to use Pomerium's authenticate service URL instead of your own, enter a URL with this format:

authenticate.<CLUSTER_SUBDOMAIN>.pomerium.app

Skip the advanced settings (unless you need to configure these for your IdP) and save your changes.

Test the IdP integration

Now, when you access a route:

1. Pomerium will redirect you to the configured IdP to authenticate.
2. Upon successful authentication, the IdP will redirect you back to Pomerium's authenticate service with the Pomerium-managed service URL.
3. Pomerium's proxy service will forward your request to the upstream service.

Next Steps: Add a Custom Domain

That's it for our Pomerium Zero courses, but if you want to continue learning how to use Pomerium Zero, try adding a Custom Domain.

From there, you can also check out any of our Guides to learn how to secure common apps and services behind Pomerium.