Custom OIDC

Got an OIDC-compatible identity provider that isn’t covered by the other guides? The custom option handles it. Authentik, Keycloak, Authelia, Dex, and anything else that speaks standard OIDC all plug in here.

Your redirect URI

Whatever provider you use, the redirect URI is your hub’s URL with this exact path:

https://your-hub-url/api/auth/custom/callback

Provider guides

Authentik

Self-hosted Authentik.

Keycloak

Realms and clients in Keycloak.

Authelia

Config-file client registration.

Dex

OIDC bridge in front of other backends.

Generic setup

If your provider isn’t listed above, here’s the manual path:

Create an OIDC client

In your provider, create a new OAuth / OIDC client and set its redirect URI to https://your-hub-url/api/auth/custom/callback.

Copy the credentials

Grab the Client ID and Client Secret.

Fill in the Custom OIDC card

Open the Custom OIDC card in Perch (Admin → Auth) and add the Client ID, Client Secret, and these URLs:

Authorization URL: where users get sent to sign in
Token URL: where Perch swaps the auth code for tokens
Userinfo URL: where Perch fetches the user’s profile
Scopes: space-separated, and you need at least openid email (Perch defaults to openid email profile)

Enable it

Flip the toggle and you’re live.

Finding the URLs

Most providers publish an OIDC discovery document at /.well-known/openid-configuration. Open that URL in your browser and you’ll see every endpoint:

https://auth.example.com/.well-known/openid-configuration

The fields Perch wants map to these keys in the discovery doc:

Perch field	Discovery doc key
Authorization URL	`authorization_endpoint`
Token URL	`token_endpoint`
Userinfo URL	`userinfo_endpoint`