EspoCRM single sign-on with Keycloak over OpenID Connect

The most common cause is a mismatch in client authentication method. EspoCRM does not support the client_secret_jwt or private_key_jwt methods, but Keycloak may default to a JWT-based method for the client. Open the client in the Keycloak admin console, check the client authentication setting for the token exchange, and make sure client_secret_post is enabled so that EspoCRM sends the client ID and secret in the request body. Then confirm that the client secret in EspoCRM matches the one shown in Keycloak. Re-save the EspoCRM OIDC settings after any change, because a stale secret produces the same error.

Keycloak only redirects to URIs listed in the client's valid redirect URIs, and the value must match the callback EspoCRM sends exactly, including scheme, host, port and path. A common mistake is registering http when the site runs on https, or registering a bare domain when EspoCRM is reached at a subdirectory or a different hostname. Copy the redirect URI from the EspoCRM OIDC settings page rather than typing it from memory, and keep one entry per public hostname. Avoid wildcards for production clients unless your security review accepts them.

Team mapping depends on the group claim. If the claim is missing from the ID token or access token, or if its name in EspoCRM does not match the claim Keycloak sends, EspoCRM has no groups to map and users land without teams. Add a group membership mapper to the Keycloak client (or a client scope) that emits the groups claim, confirm the claim name in the EspoCRM OIDC settings, and check the exact group paths, since Keycloak can send full paths such as /sales/emea depending on mapper settings. Then sign in as a test user and inspect the claims to confirm the output before relying on the mapping for access control.

The most likely cause is that Keycloak cannot reach the EspoCRM backchannel logout endpoint, which is served at api/v1/backchannelLogout on the EspoCRM host. Keycloak sends the logout request from its own server, so a private hostname, a firewall rule, a proxy that blocks POST requests, or a certificate that Keycloak does not trust will all stop it. Confirm that the client has the backchannel logout URL set and that Keycloak can reach it from the network where it runs. Check the Keycloak event log and the EspoCRM logs for rejected requests. Test with a short-lived session so you can see the result quickly.

A sign-in loop usually means EspoCRM builds its URLs with the wrong scheme or host, so the redirect it sends back does not match what the browser used, or the session cookie is not accepted. Behind a TLS-terminating proxy, EspoCRM often sees plain http and an internal host name. Configure the proxy to forward the original Host header and X-Forwarded-Proto set to https, and make sure the site URL in EspoCRM uses the public address. Confirm the proxy configuration against the EspoCRM deployment documentation for your web server, and check that the cookie domain and secure flag match the public hostname.

Most of these failures are configuration issues that an experienced administrator can diagnose with the Keycloak admin console, the EspoCRM logs and a test account. Your team can work through them if it has access to both systems, can change the reverse proxy and can read the claims a token carries. A partner is more useful when the setup involves multiple hostnames, high availability, several identity brokers or strict change control. Engagements at DeployOpen are fixed-scope, so the scope for troubleshooting and the environment you want covered are agreed in writing before work starts, and the quote follows from that scope.

The time depends on which failure you hit and how much access your team has. A redirect URI or client secret error can often be resolved in a short session once the logs are visible. Team mapping and backchannel logout take longer because they require checking claims, network paths and proxy rules across two systems. Ask for the scope, the environments involved and the access needed in the written proposal, because those factors drive the schedule more than the error itself. No duration is given here because none has been established for your environment.

The main drivers are how many groups must map to EspoCRM teams, whether Keycloak already has a realm you can use or whether a new one must be designed, whether users come from LDAP or an upstream identity provider that Keycloak must broker, and how much testing the rollout requires. Each added group needs a naming decision, a membership rule and a test case. Brokering an upstream provider adds configuration on both sides and more failure modes to verify. A written scope should state which of these apply, because they change the work far more than the EspoCRM settings themselves.

Yes, a team with Keycloak and EspoCRM administration skills can follow the documented steps, provided it has time to test them. The EspoCRM OIDC documentation covers the settings, including the client authentication method, group claim, user creation on first login and backchannel logout. The harder part is the surrounding design: deciding the group structure, confirming how the group claim appears in tokens, handling existing local accounts and proving logout behavior. Teams without prior OIDC experience usually spend most of their effort on those checks rather than on configuration.

You need administrator access to the Keycloak realm and client settings, administrator access to EspoCRM, and a decision owner for group design. Group design means agreeing which Keycloak groups correspond to which EspoCRM teams and who approves changes. You also need a set of test users covering each role and team, including at least one user who should be denied access. Network paths between the browser, EspoCRM, and Keycloak must be open for the redirect and token exchanges, and you should confirm the hostnames and TLS certificates in advance.

Keycloak publishes four minor releases a year and a major release every two to three years, and the project states that breaking changes in a minor release are opt-in. That lowers the risk of a surprise break, but each upgrade still needs a regression check of login, group sync, token lifetime and logout on a staging copy. Your upgrade plan should name who runs the check and which EspoCRM version is paired with which Keycloak version. Read the Keycloak upgrading guide before each planned upgrade.

The one-time work is the initial client setup, group mapping, testing and documentation. Recurring work includes re-testing after Keycloak and EspoCRM upgrades, reviewing group membership rules when the organization changes, rotating the client secret on your schedule, and monitoring failed logins. Because EspoCRM's own two-factor authentication is not compatible with OIDC, multi-factor enforcement must be handled in Keycloak, which adds a recurring policy review. Ask any partner to state which of these items are included in fixed-scope delivery and which fall under a retainer.

Ask for a scope that lists the Keycloak version and deployment model, the EspoCRM version, the number of groups to map, whether an existing realm or LDAP source is involved, and the number of test users and scenarios. Request a list of deliverables, including the configuration record, a test report and a runbook for user creation and logout. Ask what is excluded, such as upstream identity provider changes, certificate management or Keycloak high availability. Confirm acceptance criteria, the change process for scope additions and how post-launch support is priced.

Yes. If users are stored in Active Directory or another directory, Keycloak may need user federation or identity brokering before EspoCRM sees any group claims, so both the upstream and Keycloak configuration must be tested. Attribute mapping, group name formats and account linking are common sources of rework. EspoCRM also documents its own LDAP authentication, so the team should decide whether OIDC through Keycloak or direct LDAP best fits the directory design. That choice should be settled in the scope, since it determines which configuration and tests are needed.