Keycloak

Use Keycloak as the identity provider for Perch sign-ins.

Your redirect URI

Add this exact URL as a valid redirect URI in Keycloak:

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

Setup in Keycloak

Create a client

Open the Keycloak Admin Console, select the realm you want to use, then go to Clients → Create client.

Configure it as OIDC

Set Client type to OpenID Connect, give it a Client ID (like perch), and click Next.

Turn on client authentication

Enable Client authentication to make it a confidential client, then click Next.

Add the redirect URI

Under Valid redirect URIs, add https://your-hub-url/api/auth/custom/callback, then click Save.

Copy the secret

Go to the Credentials tab and copy the Client secret.

Setup in Perch

Open the Custom OIDC card in Perch (Admin → Auth) and add the Client ID and Client Secret. For the URLs, use the realm’s discovery document:

https://keycloak.example.com/realms/<realm-name>/.well-known/openid-configuration

Swap <realm-name> for your realm, open the URL in your browser, and copy the values across:

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

Set Scopes to openid email, then enable the provider.

Mind your realm

Each Keycloak realm has its own clients and its own discovery URL. If you run more than one realm, create the Perch client in the realm your users actually belong to.