Using Frappe as an identity provider for single sign on (SSO)

Hi everyone,

I recently configured my ERPNext installation to act as an OAuth identity provider. When you see websites suggesting things like “Log in with Facebook”, that’s OAuth. These “social logins” can be handy, but they’re inherently public. That didn’t work for us because we wanted to limit access to our web applications to just the people in our company.

Using Frappe as an OAuth identity provider, on the other hand, allows you to grant access to third-party applications only to people with a Frappe account. This has been really lovely, as it allows everyone in our company to use a single sign-on account to access a number of other web services we use (in our case, Nextcloud, Drupal, and Zulip).

The process was quite simple, but it took me a while to get set up because I am very new to how OAuth works. In this post, I am just going to share the process I used in case it helps anyone else to get started.


Step 1: Setting up your Social Login Key

Navigate to the Integrations > Social Login Key doctype, and create a new document. Set Social Login Provider as “Frappe”, and then enter your ERPNext install under Base URL. Those Client URLs will be set automatically, and they define the API endpoints that your other applications will use to authenticate user credentials.

In the end, your Social Login doc should look something like this:

Step 2: Define your OAuth client
The next thing you’re going to do is define the client parameters for the other application you want to log-in to using your ERPNext installation. In this case, I’ll be using Nextcloud, a file sharing platform that’s kind of like a self-hosted Dropbox.

Navigate to Integrations > OAuth Client, and create a new document. The only thing you should need to fill in here is App Name, which can be anything you want, and Redirect URIs/Default Redirect URI. These URIs will be different for each application you use, and to find out what you need to put here you’ll need to check the documentation of the application you’re using. In this case, we’re using Nextcloud, which expects Frappe to direct authentication details to the URL https:///apps/sociallogin/custom_oidc/Frappe

The text in Redirect URIs and Default Redirect URIs should be the same. Frappe will automatically generate your App Client ID and App Client Secret, and we’ll need those values in the next step.

Step 3: Set up your client app
Every client app will be a little bit different, but in this case we’re looking at Nextcloud. Go to the Nextcloud app store and download the app “Social Logins”. Go to the Social Logins section of the administrator settings. There, we’ll be using the “Custom OpenID Connect” section. (OpenID Connect is a specification on top of the OAuth protocol used specifically for SSO functionality). Enter the following values:

Internal Name: <whatever you want; “Frappe” works>
Title: <whatever you want again; this will show up on the Nextcloud login screen>
Authorize URL: https://<your_erp_site>/api/method/frappe.integrations.oauth2.authorize
Token URL: https://<your_erp_site>/api/method/frappe.integrations.oauth2.get_token
User info URL (optional): https://<your_erp_site>/api/method/frappe.integrations.oauth2.openid_profile
Client ID:
Client Secret:
Scope: openid

In the end, it should look something like this:

Step 4: test it out!
From here, when people hit your Nextcloud login page, they should see a button that says “Member Login” (or whatever you put in Title from the previous step). Anyone who clicks on that should be logged in automatically using their Frappe/ERPNext credentials (assuming they’re already logged in) or prompted for their Frappe/ERPNext credentials if they’re not.

I’ve demoed Nextcloud here, but most major self-hosted web applications these days have OAuth features already built in. Consequently, adapting these instructxions for whatever your company uses should be relatively simple.

Anyway, I’m sure this is all pretty basic to most people on this board, but I thought I’d post it because it would have helped me when I started trying to figure this all out a while back.

Cheers!

19 Likes

Thanks this is excellent. Have you tried or tested using Microsoft Active Directory as SSO login to ERPNext? Let me know if you did.

Active Directory should work fine with Frappe’s LDAP integration, though I’ve never tried using it myself. LDAP does the opposite of what I’m trying to do, since I want Frappé to be the identity provider, not the identity client.

Thanks for this. I was vaguely aware of Frappe’s SSO capabilities but hadn’t appreciated that you could use it in this manner.

I’m sure your write up would be useful documentation for the community. Perhaps you can submit it to the docs or the wiki somewhere so it doesn’t get lost on the forum.

That’s a great idea. I’ll leave it up here for a bit for comment and then adjust it for the wiki, perhaps with a bit more background information. I agree, though: it’s a very powerful feature that I had no idea existed!

1 Like

Logged in user can revoke access to signed in third party apps from following url :

https://erp.site.com/third_party_apps

7 Likes

Wow, that’s great! I didn’t know about that.

Thanks for all your hard work on the OAuth backend @revant_one!

1 Like

I’m trying to get multiple Frappe instances for sso-ing and this seems to be the answer. However, I keep getting Mismatching redirect URI error on the client app side.

How are you guys sso-ing multiple Frappe instances?

In your OAuth Client, add multiple Redirect URIs separated by space as redirect_uris.

Or add multiple OAuth Clients.

2 Likes

Got it working! This is awesome. Thank you!!

However, there are couple of issues with it. First, when the “provider” Frappe creates the user on the “consumer” Frappe instance, it does not transfer website user info, instead the consumer creates “system user”. Maybe there is a “default registration settings” I’m missing…? Also, secondly, the consumer does not get the mobile no info from the provider.

Other than that, it’s a bliss!

Now, how can I correct the above 2? :sweat_smile:

If there is no system user in system the first user frappe creates will be system manager. Add first system manager manually, then try sso with fresh website user

So, there are multiple system managers on both instances. We’re trying to let our “website users” (from the provider instance) to be able to log in to the consumer instance as well. But then they get “system user” on the consumer instance.

On client/consumer instance the “Social Login Key” feature is used.

Social Login Key creates user with no role for any provider added. It makes the user “Website User”.

2 Likes

Gotcha. I’m gonna fiddle with this file above (in an override mode) and expand on it.

Thank you Revant!