Self-Hosted Authenticate Service
Pomerium's Self-Hosted Authenticate Service allows you to configure Pomerium with the identity provider of your choice.
The self-hosted authenticate service is available for open-source Pomerium, Pomerium Zero, and Pomerium Enterprise.
The authenticate service is one of the four logical services that make up Pomerium. The authenticate service is unique in that Pomerium can either run this service itself, or instead use the Hosted Authenticate Service.
How the self-hosted authenticate service works
To configure the self-hosted authenticate service, you will need to set up:
- a URL for the authenticate service
- an identity provider (IdP)
Authenticate service URL
The authenticate service URL is a public-facing URL that should resolve to your Pomerium instance. (If running in split service mode, this URL should resolve to the authenticate service.) Whenever a user is required to log in to access a route, Pomerium will redirect the user to the authenticate service using this URL.
This URL should not contain a path or query parameters. For example, https://authenticate.corp.example.com.
This URL must be different from any of the route URLs you use with Pomerium.
See the Authenticate Service URL reference page for details on how to configure this setting.
In a typical OIDC authentication flow, all redirect URLs must be pre-registered with the IdP. Pomerium uses a single authenticate service URL so that you need to register only one redirect URL with your IdP. This way, Pomerium can protect multiple upstream services without requiring you to update your IdP client whenever you add a new service.
Identity provider
Pomerium relies on an IdP to authenticate users. Pomerium can use any IdP that implements the OpenID Connect (OIDC) protocol.
The steps to configure your IdP will vary depending on the specific provider. See Identity Providers for a list of guides to configure commonly-used IdPs.
You will generally need to configure your IdP client to allow an OAuth redirect URL based on your chosen authenticate service URL, with the path /oauth2/callback appended to it.
For example, if your authenticate service URL is https://authenticate.corp.example.com, you should configure your identity provider to allow the redirect URI https://authenticate.corp.example.com/oauth2/callback.
If you require a different callback path than /oauth2/callback, you can use the Authenticate Callback Path setting to change the callback path.
Once you have set up an IdP client, you will need to configure Pomerium with the IdP name, client ID and client secret, and possibly a URL assigned to your individual IdP client.
See the Identity Provider Settings reference page for details on how to configure these settings.