If our built-in SAML or WordPress SSO plugin solutions do not fit your system, you may use this guide to implement and use SSO in your Learnworlds school. In LearnWorlds, you can enable multiple custom SSO solutions simultaneously.
The concept is to authenticate school users via an authentication provider that would implement the Single Sign-On mechanism. So the user would be redirected to an external authentication page (that you need to implement based on this guide). When successfully authenticated, the user would be returned to the school as a logged-in user.
What you need is a page that the user will be able to:
- Login - provide email and password to be authenticated in your system.
- Sign-up - if you wish to allow the users to self-sign-up into your system.
Password reset - a mechanism that allows users to reset their password.
When you set up your SSO, the LearnWorlds platform will redirect the aforementioned user's actions to your custom page. Thus, any links pointing to these system forms will be redirected to your HTML page.
The custom page that you will create will need to accept 2 URL parameters:
- action - with three possible values: login, signup, and password reset.
- redirectUrl - this is the page where the user was before the authentication request. You need to use this parameter to redirect the user after successful authentication in your system. The redirectUrl is encoded and will need to be decoded before redirecting the user to the URL.
An example URL that your system might accept is http://www.example.com/sso-learnworlds?action=login&redirectUrl=https%3A%2F%2Fsoftomotive.getlearnworlds.com
Below, you will see a more detailed explanation of implementing each workflow.
Login Workflow
1. User clicks on Sign-in and chooses the Custom SSO solution.
2. Learnworlds system redirects to the SSO provider URL with parameters ‘action=login’ and ‘redirectUrl=<current page>’
3. SSO provider opens a login form.
4. User enters their credentials.
5. If Authenticated correctly, the SSO provider uses the Learnworlds API to perform the following:
a. Use the Learnworlds SSO API method to login the user to Learnworlds school https://www.learnworlds.dev/docs/api/58052c1c3066e-single-sign-on (this method would also take the redirectUrl to send the user to the school).
b. The aforementioned method returns a URL that you need to use to redirect the user's browser (that will automatically login the user) and Learnworlds user_id. If the user is new, then you might need to store this user_id in your system for future use. Also, you might need to use the user update method (https://www.learnworlds.dev/docs/api/af37cf519afd1-update-a-user) to provide more info for the user.
6. The user is logged in back to the page that they started.
It is better to use the Learnworlds User_id for existing SSO users since it is possible to change the email on the SSO Provider platform. Sign-up Workflow
The sign-up is always performed on the SSO provider’s platform.
1. User clicks on Sign-up and chooses the Custom SSO solution.
2. Learnworlds system redirects to the SSO provider URL with parameters ‘action=signup’ and ‘redirectUrl=<current page>’.
3. SSO provider opens a sign-up form.
4. SSO provider finishes the registration of the user and triggers the above login mechanism to SSO the user to Learnworlds.
Password Reset Workflow
The sign-up is always performed on the SSO provider’s platform.
1. User clicks on the password reset button.
2. Learnworlds system redirects to the SSO provider URL with parameters ‘action=passwordreset’ and ‘redirectUrl=<current page>’
3. SSO provider opens a password reset form.
4. SSO provider finishes the password reset workflow and triggers the above login mechanism to SSO the user.
Set up your SSO URL
Once you have your custom page ready, you may set up your school to use this custom SSO solution.
1. Navigate to Website Settings → Authentication → Custom SSO.
2. Create a new Custom SSO.
3. Activate user authentication through your Custom SSO solution
4. Add a name for this Custom SSO solution.
5. Enter your custom page’s URL and press Test URL to validate your implementation.
6. Click on Create to save the settings, so your users will now be authenticated via your own custom SSO page.
If you're using Custom SSO as an authentication method, it's mandatory to change the Site Navigation settings in the Payment Flow section for Logged-out users, as they will need to sign up/log in before proceeding to the payment page.
Also, you need to ensure that in all Payment Sections of your school's pages, 1-click Sales funnels, or the Payment Page of your school, the Sign in/up form option is set to hide since the user will not be able to sign in/up via the Learnworlds system.
-Mechanisms related to authentication would be removed from the LearnWorlds school. For instance, the email and password-changing forms found in a user's profile will be removed.