ERPNext single sign-on with Keycloak

How ERPNext single sign-on with Keycloak works

The supported route for staff to sign in to ERPNext with a central identity is OpenID Connect through a custom Social Login Key that points at a Keycloak client. ERPNext does not authenticate against Keycloak directly. The Social Login Key tells ERPNext which identity provider to send the user to, which client to identify as, and which endpoints to use for the authorization and token exchange. Once Keycloak confirms the user, ERPNext matches that login to a local User record, so the Keycloak sign-in becomes the way in while ERPNext keeps the user account.

ERPNext's documented fairlogin integration follows this pattern. Fairlogin is a Keycloak-based OAuth provider configured as a custom Social Login Key, and the ERPNext documentation notes that because it is built on Keycloak, its parameters are similar for any custom OAuth setup using Keycloak. In practice, the setup is an OpenID client in the realm whose root, base and redirect URLs point to your ERPNext instance, with the client credentials copied into the Social Login Key. Confirm the exact redirect URI format and the endpoint paths against the fairlogin documentation and your ERPNext version before you configure anything, since small differences in the callback path cause most first-time failures.

Decide early how user records are created and who owns them. Confirm whether the Social Login Key should create new users on first sign-in or only accept users that already exist in ERPNext, and who will remove access when someone leaves. Those answers determine whether Keycloak is the source of identity or only a sign-in gate, and they shape the LDAP versus OIDC decision covered below.

What you need before you configure ERPNext and Keycloak

Five things have to be in place before any client or redirect setting is touched. They can be prepared in parallel, but the Keycloak version, the public hostname and the user decision all shape the configuration that follows.

A supported ERPNext version

Confirm that your site runs ERPNext on a version still listed as supported. According to Frappe's supported versions page, version 14 reached end of life on January 31, 2026, so it is not a valid starting point. Version 15 is planned for support until the end of 2027 and version 16 until the end of 2029. Check the exact patch level of your bench, since both supported lines receive frequent minor releases.

A Keycloak server on a supported release

Run Keycloak on a current release, such as 26.8.1, and plan its upgrade cadence before go-live. Keycloak plans four minor releases a year, and breaking changes in a minor release are opt-in, so read the release notes for each step. Confirm the release against your own change calendar rather than assuming the latest build is approved for your environment.

A supported production database

Keycloak should use a production database from its supported list, such as PostgreSQL 14 to 18, MariaDB, MySQL, Oracle Database or Microsoft SQL Server. The default dev-file database is for development only. Ask who owns backup, restore and patching for that database, because a Keycloak outage stops every ERPNext login that depends on it.

A public HTTPS hostname for ERPNext

The OpenID client must redirect back to a stable, publicly resolvable HTTPS address for the ERPNext site. Settle the hostname before creating the client, because the root, base and redirect URLs all depend on it. Changing the hostname later means editing the client and the Social Login Key together, and users may see mismatched redirect errors until both match.

Admin access to Keycloak and ERPNext

You need administrator rights in the target Keycloak realm to create the OpenID client, its redirect settings and any role or group mappers. You also need System Manager access in the ERPNext Desk to create the Social Login Key. Confirm early who holds these rights, since the two administrations are often run by different teams.

A decision on pre-provisioned users

Decide whether ERPNext users must already exist before their first Keycloak login. If accounts are created in advance, administrators control roles and permissions up front. If not, confirm how new users are created on first sign-in and which default roles they receive. Test the realm and users on a non-production site first, so role mistakes do not reach live accounting or stock data.

Choosing between LDAP and OIDC for ERPNext logins

With LDAP, ERPNext checks the user's password against Active Directory or OpenLDAP itself, using the LDAP Settings document. ERPNext holds the bind account, the search base and the field mappings, so the login path depends on a direct network connection from the ERPNext application servers to your domain controllers or LDAP servers. The ERPNext LDAP integration documentation describes SSL/TLS options for encrypting that connection, and it maps LDAP groups to ERPNext roles automatically at each login.

What the directory team provides: a read-only bind account, the base distinguished name for users and groups, a certificate chain the ERPNext hosts trust for LDAPS or STARTTLS, and firewall rules from every ERPNext application server to the directory.
Where role logic lives: in group membership in the directory, translated into ERPNext roles by the mapping in LDAP Settings. Changing the mapping changes access on the next login.
Disabled accounts: an account disabled in Active Directory or OpenLDAP fails the bind on the next sign-in attempt. Existing ERPNext sessions and API tokens are not ended by the directory, so confirm how your session lifetime and token policy handle that gap.
Operational coupling: if the directory or the network path is unavailable, ERPNext logins fail for every user, so check how the team plans for directory outages.

Confirm with your directory team whether the bind account and group structure can be governed as you need before you commit to this path.

Configure the Keycloak client and ERPNext Social Login Key

This sequence sets up an OpenID Connect client in Keycloak, registers a matching custom Social Login Key in ERPNext, and proves that a test user signs in to the correct ERPNext account. Each step ends with a check so that a misconfigured redirect or endpoint is caught before users depend on it.

Choose the realm and confirm the Keycloak endpoints
The Keycloak administrator selects an existing realm for ERPNext users or creates a dedicated one, then records the realm's OpenID Connect discovery URL from the realm settings. Copy the endpoint values from the current Keycloak server administration guide and the ERPNext fairlogin documentation rather than from memory, because path formats change between Keycloak releases. The step is complete when the discovery URL returns a JSON document in a browser or with curl, and the issuer value in that document matches the realm you intended.
Create the OpenID client in Keycloak
In the realm, the Keycloak administrator creates a client with the OpenID Connect protocol and sets the client type and client authentication according to the fairlogin guidance. Enter the root URL, base URL and valid redirect URI using the public address of your ERPNext site, so that the redirect path matches what ERPNext sends during login. Confirm the redirect URI character for character, including the scheme, host, port and trailing slash, because a single mismatch causes Keycloak to reject the login. The step is complete when the client is saved and its client ID and secret are available to copy.
Assign scopes and mappers for user attributes
The Keycloak administrator confirms that the client returns the standard OpenID scopes and that the email claim, along with any name claim ERPNext needs, is included in the ID token or user information response. Test the claims with a user who already exists in the realm. Confirm which claim will serve as the unique user key in ERPNext, since the Social Login Key maps the returned identity to an ERPNext user by that value. The step is complete when a test token or user information response shows the expected claims for that user.
Create the custom Social Login Key in ERPNext
An ERPNext administrator opens Social Login Key and creates a custom provider, entering the Keycloak client ID and client secret, along with the authorization, token and user information endpoints from the realm's discovery document. Set the provider name, base URL and any user ID property that matches the claim confirmed in the previous step. Use the endpoint values copied from current documentation so that paths match your Keycloak version. The step is complete when the Social Login Key record saves without validation errors.
Enable the provider on the login page
The ERPNext administrator enables the new Social Login Key so that its button appears on the login page, and keeps password login available for the time being so that administrators can recover access if the provider is unavailable. Decide whether self-registration through the provider is permitted, because that choice determines whether an unknown identity creates a new user or is refused. The step is complete when the login page shows the provider button in a private browser session.
Test sign-in with one known account
A test user who already has an ERPNext account signs in through the Keycloak button and returns to ERPNext. Confirm that the session opens under the expected user, that the user's roles and permissions match the account they should have, and that no second user was created by accident. Repeat the test with a user in a different role if your access model depends on roles. The step is complete when the test user lands in the correct ERPNext account and the login is recorded in the user's activity.
Confirm the redirect and error paths
Test a login with a Keycloak user who has no matching ERPNext account, and a login attempted after the client secret is changed, to see how ERPNext reports each failure. Check the Keycloak event log and the ERPNext error log for the exact messages. Record the redirect URI and endpoint values in your configuration notes so that a future Keycloak upgrade or ERPNext domain change can be checked against them. The step is complete when each failure produces a clear message and the team has a written record of the working values.

Mapping Keycloak claims to ERPNext users and roles

This table lists each Keycloak source that can feed an ERPNext user record, what ERPNext does with it, and the decision the owner must make before go-live. Read it as a checklist: settle the matching key and the new-user path first, then decide how group membership becomes ERPNext roles.

Keycloak source	ERPNext field or behavior	Decision for the owner
Email claim (email)	Matching key for an existing User record through the Social Login Key flow	Confirm that every ERPNext user has a unique, verified email in Keycloak, and agree who corrects mismatches before cutover.
Preferred username or subject (sub)	Not used as the matching key in the standard fairlogin setup, so logins stay tied to email	Decide whether any user accounts must match on another identifier, and confirm this with the fairlogin and Social Login Key configuration before you rely on it.
Given name and family name claims	Full name on the User record, where the configured mapping populates it	Choose whether Keycloak remains the source of names or ERPNext users may edit them, and document the choice.
Keycloak account enabled state	Whether the ERPNext User record can sign in; disabling in Keycloak does not automatically disable the ERPNext user unless your process does it	Define the offboarding step: disable in Keycloak, disable in ERPNext, or both, and who performs it and how often access is reviewed.
Users with no matching ERPNext record	Behavior on first login depends on the Social Login Key settings and whether user creation is allowed	Decide whether new users are created automatically, created by an administrator in advance, or refused. Confirm the behavior in your version before choosing.
Group membership in Keycloak	No built-in mapping to ERPNext roles is assumed in this setup; roles remain ERPNext Role assignments	Choose the group-to-role model, such as one Keycloak group per ERPNext role, and keep the mapping in a written table owned by a named person.
Role assignment (manual)	Administrator assigns Roles on the User record in the Desk	Acceptable for small user counts, but every joiner, mover and leaver change depends on a person remembering to act.
Role assignment (scripted)	A Server Script or hook sets roles at login or on a document event	Server Scripts are disabled by default from version 15 and must be enabled with server_script_enabled, and Frappe Cloud public shared benches do not allow them. Confirm hosting rules before choosing this path.
LDAP comparison	LDAP Settings map LDAP groups to ERPNext roles automatically at each login	If your directory already holds the group model and you need automatic role sync, compare LDAP with OIDC before committing to Keycloak-only identity.

Security settings for the Keycloak and ERPNext link

Single sign-on moves the login decision to Keycloak, so the security of ERPNext now depends on how Keycloak and the ERPNext site are configured together. The cards below cover transport, client credentials, token lifetimes, administration, MFA, a fallback login path and the operational choices that keep Keycloak current.

HTTPS on both hosts

Serve Keycloak and the ERPNext site over TLS only, and confirm that the base and redirect URLs in the Keycloak client use ` addresses that match the public hostnames. Mixed schemes or an internal hostname in the base URL cause redirect failures that teams often work around by weakening settings. Check certificate chains and renewal for both hosts before go-live, since a single expired certificate blocks every ERPNext login.

Confidential client and stored secret

Create the ERPNext OpenID client as a confidential client so Keycloak issues a client secret that ERPNext uses during the token exchange. Store that secret in your secrets manager or the site configuration on the server, never in a Git repository, exported customization or ticket. Plan rotation as a documented task, because changing the secret in Keycloak without updating the Social Login Key breaks sign-in for all users at once.

Exact redirect URI matching

Register only the exact callback URL that the Social Login Key generates for your ERPNext site, including the path and scheme. Avoid wildcard redirect URIs and broad root URLs in the Keycloak client, because they let an attacker who controls a path under the same host receive authorization codes. Review the list whenever a site is renamed, added or moved to a new domain.

Token and session lifetimes

Set access token, SSO session idle and SSO session maximum lifetimes in the Keycloak realm to match your policy for financial and HR data. Short access tokens limit the window for stolen tokens, while session limits decide how long a user stays signed in across ERPNext and other applications. Confirm the values with your security team and document them, because ERPNext keeps its own session and the two timers do not always end together.

Realm administration and MFA

Limit the Keycloak admin console to a small named group, use separate accounts for administration, and enable multi-factor authentication through a Keycloak required action or conditional authentication flow. Treat MFA as a Keycloak control: ERPNext trusts the identity that Keycloak returns, so an ERPNext two-factor setting does not protect logins that bypass the Keycloak flow. Review admin events and the users who hold realm admin roles on a fixed schedule.

Break-glass ERPNext administrator

Keep one local ERPNext Administrator account with a strong password stored in a sealed, audited location, and test that it still signs in after each change to the Social Login Key. This is the recovery path if Keycloak is unavailable, misconfigured or its certificate expires. Review ERPNext login policies, password rules and two-factor settings for every user role, so that the fallback account is not the weakest entry point to the system.

Keycloak operator updates

If you deploy Keycloak with the Keycloak Operator on Kubernetes, set the operator to manual approval mode so that a new operator version does not upgrade Keycloak without review. Schedule each upgrade in a change window, test it against a copy of the realm and confirm the ERPNext login flow afterward. Unplanned automatic upgrades are the most common way a working single sign-on setup breaks without an obvious cause.

Database migration method

Keycloak applies database schema changes automatically at startup by default. On Kubernetes, that is convenient for small deployments but means a pod restart can change the schema during a rollout. For larger deployments, the upgrading guide suggests manual migration, where your database team reviews and applies the SQL before the new version starts. Choose the method before the first upgrade, record it in the runbook and back up the database before each change.

Deciding who provisions ERPNext accounts and roles

The first decision in this section is whether ERPNext user accounts are created on first Keycloak login, pre-created by administrators, or synchronized from a directory. With a custom Social Login Key, ERPNext can match an incoming OpenID Connect identity to an existing user, and the Social Login Key settings decide whether an unknown user is created automatically. Auto-creation is convenient, but it means every person who can authenticate in the Keycloak realm also gets an ERPNext user, usually with few or no roles, until someone assigns them. Pre-created accounts keep ERPNext as the list of people allowed to work in the books, at the cost of a request-and-approval step for each joiner. Directory-driven provisioning, which in practice means keeping Keycloak and the upstream directory as the source of truth, is the option that most affects offboarding. Disabling the Keycloak user stops new logins, but it does not disable an existing ERPNext user or revoke active sessions, so you need a documented step that disables the ERPNext account too. Confirm how your chosen approach behaves in your ERPNext version, and test a disabled Keycloak user against a live session before go-live.

Role assignment is the harder half of provisioning. If you want role logic to run automatically at login, for example mapping a Keycloak group to ERPNext roles, a Server Script is the obvious tool, but Server Scripts are disabled by default from version 15 and must be enabled with the server_script_enabled setting. Frappe Cloud public shared benches do not allow Server Scripts at all, so a hosting choice made early can rule this design out before any Keycloak work begins. On self-hosted benches, enabling Server Scripts is an administrative decision with its own review, since they run Python with broad access to the site. The alternative is to keep role mapping out of code, assigning roles from an approved list by an administrator or through a reviewed import, and to treat the Keycloak group as an input to that process. Whichever path you choose, confirm the exact behavior of Social Login Key and role handling for the ERPNext version you run, and record the decision alongside your hosting plan.

Common Keycloak and ERPNext login failures and fixes

This table pairs each common symptom in the Keycloak to ERPNext login flow with its likely cause and the configuration step to check. Work through the rows in order, and check the Keycloak event log and the ERPNext error logs before changing anything, because both usually name the failing step. The main takeaway is that most failures trace back to a mismatched URL, a missing claim, or a stale secret set during client setup.

Symptom	Likely cause	Fix
Redirect URI mismatch after the callback	The valid redirect URI on the Keycloak OpenID client does not exactly match the callback URL ERPNext sends, often because of a trailing slash, http versus https, or a different hostname.	Set the client's redirect URI to the callback path shown in the Social Login Key, using the exact scheme and host of the ERPNext site. Then check the Keycloak event log for the rejected redirect.
Login succeeds in Keycloak but no ERPNext session is created	The root, base or redirect URL on the client points to a different site than the ERPNext instance, or the Social Login Key is not enabled or not linked to the user's login flow.	Confirm the client's root and base URLs point to the ERPNext instance, enable the custom Social Login Key, and check the ERPNext error log for the token exchange and user lookup entries.
User is rejected or created with the wrong identity because the email claim is missing or different	The Keycloak client does not include the email scope or mapper, so the email claim is absent, or the Keycloak account email differs from the ERPNext user email.	Add the email claim to the client's token mappers, confirm it appears in the ID token, and make sure the Keycloak email matches the existing ERPNext User record before first login.
Certificate or hostname error on the back-channel token request	ERPNext cannot verify the TLS certificate of the Keycloak server when it calls the token endpoint, usually because of a private certificate authority or a hostname that does not match the certificate.	Install the internal certificate authority on the ERPNext host, confirm the Keycloak hostname in the provider URLs matches the certificate, and retest the token request from the ERPNext server.
Login fails with an invalid client error after a secret rotation	The client secret was regenerated in Keycloak, but the Social Login Key in ERPNext still holds the old value.	Copy the new secret into the Social Login Key client secret field, save, and retest. Remove any cached copies or scripts that still reference the previous value.
Users keep their old roles after a group change in Keycloak	ERPNext assigns roles from the mapping at login, so a user who keeps an existing session or whose role mapping was never updated retains earlier permissions.	Confirm the group or role claim reaches ERPNext, update the role mapping, and ask the user to sign out and sign in again. Verify the change in the user's Role Profile on the ERPNext User record.

Questions buyers ask before setting up Keycloak SSO for ERPNext

What drives the cost of setting up Keycloak SSO for ERPNext?

The cost follows the identity design more than the login button itself. The main drivers are how many user populations need to sign in (employees, contractors, external auditors), how roles in Keycloak map to ERPNext roles, how many environments must be tested (development, staging, production), and whether the Keycloak instance is already running in a production-grade setup. A quote should separate the one-time work (realm and client design, Social Login Key configuration, role mapping, testing, cutover) from any recurring work (Keycloak upgrades, certificate renewal, ERPNext upgrades that change the login flow). Ask the provider to state who performs each item and which hosting constraints it assumes, since those details shift effort in either direction.

Can our own team set up Keycloak SSO for ERPNext without a partner?

Yes, if your team already runs both Keycloak and ERPNext and has the skills listed in the prerequisites: administering a Keycloak realm and OpenID Connect clients, configuring an ERPNext site with bench or Docker, and understanding how Frappe Social Login Keys and user roles behave. Teams that lack one of these areas usually take longer and are more likely to make mistakes in redirect URLs or role mapping. A useful self-assessment is whether someone on the team can read the ERPNext site logs and the Keycloak event log during a failed login and explain what went wrong. If not, plan for training or outside help before the cutover date.

How long does Keycloak SSO for ERPNext take, and what sets the duration?

The duration depends on the decisions that have to be made before any configuration starts. Agreeing the realm structure, client settings and role mapping with the people who own those decisions is usually the longest step, and it is not controlled by the technical setup. Other factors include the number of ERPNext sites that will share the login, whether roles need approval from more than one owner, how many test accounts and scenarios must pass, and whether the change must fit a fixed maintenance window. No fixed duration is stated here. Ask any provider for a timeline built from the written scope, with each milestone tied to a named approval or test.

What does the business need to provide for this integration?

Three inputs matter most. First, owners of the directory or user source, who confirm which people should be able to sign in and how accounts are created, disabled and renamed. Second, a named approver for role design, who decides which Keycloak groups or roles map to ERPNext roles such as accounting, stock or manufacturing users, since mistakes here expose financial data. Third, test accounts for each user population, including at least one account that should be denied access. Your team should also confirm the public URLs for the ERPNext site and the Keycloak server, plus who can approve a change to the production client configuration.

Does Keycloak need a production database and high availability before it can serve ERPNext?

Yes, for a production login service. Keycloak's own documentation lists supported production databases, including PostgreSQL, MariaDB, MySQL, Microsoft SQL Server, Oracle Database and Azure SQL, and states that the default dev-file database is for development only. For high availability, Keycloak documents a single cluster optionally spread across availability zones and a multi-cluster design, and both supported designs need a synchronously replicated database. If Keycloak is down, nobody can sign in to ERPNext, so the availability requirement should be set by the business owner of ERPNext. Confirm the exact database version and cluster design against the current Keycloak documentation before you commit to a build.

Should we use LDAP or OpenID Connect for ERPNext login?

Choose OpenID Connect through a Social Login Key when Keycloak is your identity provider and you want the login flow, token claims and role decisions controlled in one place. ERPNext also supports LDAP login against Active Directory or OpenLDAP, with SSL/TLS options and automatic mapping of LDAP groups to ERPNext roles at each login. LDAP suits organizations whose identity source is a directory that ERPNext can reach directly, while Keycloak suits organizations that want brokering across several identity sources. Questions to settle first: where the authoritative user list lives, whether ERPNext can reach that directory from its network, how group changes should take effect, and who will support the chosen path after go-live.

What do we need to check after go-live to keep the login working?

Plan for recurring checks rather than a one-time setup. Watch failed login attempts on both Keycloak and ERPNext, confirm that role changes in Keycloak appear correctly in ERPNext after the next login, and retest the sign-in flow after each Keycloak or ERPNext upgrade. Keycloak plans four minor releases a year, and its Operator documentation recommends manual approval for operator updates to avoid unplanned upgrades, so an upgrade calendar should be part of the operating plan. Ask the implementer to document the client settings, redirect URLs and the break-glass administrator account so that a single person's absence does not block sign-in.

How DeployOpen scopes and delivers ERPNext SSO with Keycloak

DeployOpen plans, implements, integrates, documents and supports self-hosted open-source platforms inside your own infrastructure, including ERPNext single sign-on with Keycloak. We start from a written scope that settles the Keycloak realm, the ERPNext site URLs and the LDAP versus OIDC decision before any configuration changes are made.

How we scope

Confirm which Keycloak version, realm and database your identity team already runs or plans to run.
Record the ERPNext version, site name and public base URL that the OpenID client must reference.
Decide in writing whether OIDC login, LDAP login or both will apply to each user group.
Agree which roles, login policies and fallback local accounts are in scope before build starts.

How we build

Create the OpenID client in the realm with root, base and redirect URLs pointing to your ERPNext instance.
Configure the custom Social Login Key in ERPNext and map Keycloak claims to user fields and roles.
Test sign-in, sign-out, first-login user creation and role assignment on a non-production site first.
Review TLS, secret storage and client settings against the hardening points agreed in the scope.

How we hand over

Deliver a runbook covering client settings, redirect URL rules, claim mappings and the recovery path if Keycloak is unavailable.
Document each configuration key and the environment where it lives so your team can audit changes.
Walk your identity and ERP administrators through a test login, a role change and a deprovisioning case.
Record which decisions were made, who approved them and what remains open for your team to own.

How we support

Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
Ongoing support, upgrades for ERPNext and Keycloak, and continuous testing are available as a retainer.
Plan Keycloak upgrades with a staged approach and confirm the operator update mode your environment uses.
Ask for a quote based on the written scope, which sets the cost of build, handover and any retainer.