Single sign-on for ERPNext and Prometheus: options and pitfalls

The short answer

You have three realistic ways to add single sign-on (SSO) to ERPNext or Prometheus:

1. OpenID Connect (OIDC) or OAuth sign-in through the framework's built-in Social Login Key feature, which supports Microsoft, Google and custom providers. This is the right starting point for most organisations using Microsoft Entra ID or Google Workspace.
2. SAML, when your identity team standardises on it or your provider (for example, some Okta or other enterprise set-ups) prefers it. SAML is not one of the standard social login options, so it is delivered through a custom app or an identity broker.
3. LDAP, for on-premises Active Directory. ERPNext's LDAP settings can also map directory groups to ERP roles.

Pick the protocol your identity provider supports best, then spend most of your effort on user matching, role mapping and offboarding. That is where SSO projects succeed or fail.

Choosing between OIDC, SAML and LDAP

Microsoft describes OpenID Connect as an extension of OAuth 2.0 that enables SSO using an ID token, and SAML as an XML-based standard for exchanging authentication data between an identity provider and an application. Both are well supported. LDAP gives you one password, which is useful, but it is not single sign-on in the modern sense, and it does not bring your provider's multi-factor prompts or conditional access with it.

The pitfalls we see most often

Matching users by email, carelessly. Most set-ups match the incoming identity to an ERP user by email address. If someone's email changes after a name change, or the directory uses a different domain alias, they either cannot sign in or a duplicate user is created. Agree which attribute is the identifier before go-live.

Creating users automatically with too much access. Auto-creating ERP users at first sign-in is convenient. Doing it with a generous default role means anyone in your tenant can wander into accounting. New users should arrive with no roles, or a minimal one, until someone approves access.

Roles that drift from the directory. If a person moves from sales to purchasing, their ERP roles should follow. With LDAP group mapping, roles can be rechecked at each sign-in. With OIDC or SAML, decide whether groups or app roles in your identity provider drive ERP roles, or whether roles are managed in the ERP by a named administrator. Mixing both is how drift starts.

Offboarding that does not end access. Disabling someone in Entra ID stops new sign-ins, but an existing ERP session can stay valid until it expires. Offboarding should also disable the ERP user, end their sessions and revoke any API keys they created. We tie this to the onboarding and offboarding checklist.

Password sign-in left open. If SSO is added but password login stays available for everyone, staff keep their old ERP passwords and your MFA policy is bypassed. Decide who, if anyone, still signs in with a password.

No break-glass account. If your identity provider is down or misconfigured, someone must still be able to reach the ERP. The same applies when your internet link drops and the ERP cannot reach a cloud identity provider, which matters where connectivity can be patchy. Keep one or two local administrator accounts with long, stored passwords and MFA, and record who can use them.

Secrets that expire quietly. Client secrets and signing certificates have expiry dates. When one lapses, everyone is locked out at once. Record the dates and set reminders, or use certificates with a documented renewal process.

Customers and suppliers caught up in it. Portal users (customers, suppliers) usually should not sign in through your staff directory. Keep their sign-in separate, and make sure the SSO button does not confuse them.

Integrations using personal accounts. Integrations should use dedicated API credentials with limited roles, not a person's account that SSO will later disable.

A pre-launch checklist

How we build it

We set up SSO in a test site first, never straight in production. Where the standard Social Login Key or LDAP settings are enough, we configure them. Where you need SAML, role mapping from directory groups or custom provisioning rules, we build that in a separate custom app under version control, so it is not overwritten by ERPNext upgrades and is tested again with each new release. You receive documentation of the configuration, the role mapping and the offboarding steps. See ERPNext and Prometheus customisation for the wider range of work we do.

When to bring in help

If you run a single company on Google Workspace or Entra ID, with a handful of users and simple roles, a capable administrator can configure OIDC sign-in using the documentation above. Bring in help when roles must follow directory groups, when SAML is required, when you have several companies or portals, or when an auditor or insurer will ask how access is granted and removed. Those are the cases where a small configuration mistake leaves a door open that nobody notices until it matters.

Sources and further reading

Product capabilities and guidance change. These are the primary sources this article relies on, checked on the review date above.

1. Social Login Key, Frappe Framework documentation
2. Setting up LDAP, ERPNext documentation (Frappe)
3. OpenID Connect (OIDC) on the Microsoft identity platform, Microsoft Learn
4. SAML authentication with Microsoft Entra ID, Microsoft Learn
5. Role Based Permissions, ERPNext documentation (Frappe)

This article is general information, not legal, accounting or security advice for your specific situation. Examples are hypothetical unless stated otherwise.