Connect Keycloak to Kanroo

Configure SSO for an existing Kanroo organization. These steps were manually tested with Keycloak 26.7.3. Installing Keycloak is outside this guide.

For account linking, settings access, and everyday sign-in questions, see Personal sign-in and SSO sign-in.

Before you start

• SSO must be available: any hosted plan or self-hosted Enterprise.
• Sign in to Kanroo personally by email as the organization owner. Keep that mailbox accessible.
• Have administrator access to the intended Keycloak realm and a user for the Kanroo owner.
• The realm’s HTTPS endpoints must be reachable and trusted by both the browser and Kanroo server. Self-hosted operators must configure the OIDC encryption keyring before storing a client secret; private-network issuers and issuers on a port other than 443 additionally require OIDC_ALLOW_PRIVATE_ISSUERS=true. HTTPS remains required. Hosted Kanroo accepts only port 443; expose the realm on 443, for example through a reverse proxy.

1. Register Kanroo in Keycloak

In Kanroo, open Settings → SSO and copy the displayed Redirect URL.

In the intended Keycloak realm, open Clients → Create client:

Setting	Value
Client type	OpenID Connect
Client ID	kanroo
Client authentication	On
Authorization	Off
Authentication flow	Standard flow only; disable Direct access grants and other flows
Valid redirect URIs	The exact Callback URL copied from Kanroo, without wildcards
Other URL fields, including Web origins	Leave empty

Save the client. Under Settings → Capability config, set Require PKCE to On and PKCE Method to S256, then save. In Keycloak 26.7.3 these controls are not in the Advanced tab.

Under Credentials, use Client Id and Secret as the client authenticator and copy the Client Secret. Keep the secret private.

2. Connect the organization

(enlarge)

Back in Kanroo’s Settings → SSO, check that the Redirect URL (box 1) is the one you registered, then enter these values in the provider fields (box 2):

Field	Value
Issuer URL	Your realm URL, for example https://login.example.com/realms/company
Client ID	kanroo, matching the client above
Client Secret	The secret copied from Keycloak

Use the realm’s issuer URL, not its /.well-known/openid-configuration URL.

Choose Save draft (box 3), then select Test and connect. Sign in with the owner’s Keycloak user, then complete the email verification code sent by Kanroo to link the accounts. The provider should show Connected. Leave Require SSO off until you have tested member access.

3. Admit members and test sign-in

Invite members to the organization, or enable automatic joining (JIT). With JIT enabled, users who can authenticate through this Keycloak client can join as Members, subject to the organization’s limits; restrict access at Keycloak accordingly.

Members select Continue with SSO on the Kanroo sign-in page and enter the organization’s slug, or open the SSO sign-in link you copy from Settings → SSO, which preselects the organization. Their first login requires email verification to link the account. If Keycloak supplies no email claim, Kanroo asks for an address first. Later logins with the same linked identity do not repeat this verification.

A SSO-only session shows Personal verification required in place of API keys, security activity, and Webhooks. Select Verify personal account and enter the emailed code when you need those settings; the session stays. The organization role is unchanged.

4. Require SSO and retain recovery access

As the owner, generate Recovery codes, complete the requested email verification, save the codes securely, and acknowledge that they are saved. Then enable Require SSO and confirm. Personal email sign-in alone will no longer grant access to this organization.

If Keycloak is unavailable, sign in personally as the owner and open /auth/company/recovery on your Kanroo instance. Select the organization and submit a fresh email verification code together with one recovery code. This disables Require SSO, consumes that recovery code, and keeps the provider configured.

Remove departing members in Kanroo as well as disabling their Keycloak access. JIT does not automatically restore a removed membership; an explicit invitation allows the member to rejoin.

Multiple Kanroo organizations can use the same realm and client. A linked member signs in to each organization once in the same browser session, then switches between them in the organization selector without repeating account linking. Each organization’s SSO proof lasts 24 hours; afterwards another Keycloak round trip is required.

Reference: Keycloak client configuration.