If our built-in SAML, OpenID, 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.
- If you set up an SSO solution and disable the LearnWorlds login, all the users will be redirected to the SSO provider to authenticate, LearnWorlds passwords will no longer be valid. The users need to exist or sign up with the SSO authentication provider. The change of the authentication provider will only change the authentication mechanism, all the user data as well as their roles (admin, instructor, etc.) will be intact.
- The SSO mechanism uses the user’s email address to identify the user (unique key); therefore, to change the user's email address, you need to manually update the new email both in your school and on your IDP.
Furthermore, you may use the bulk import (and enroll) functionality in case you need to import users that already exist in your SSO provider.
- If you revert to LearnWorlds authentication, users created via the SSO authentication will need to create a new password. Passwords can be changed:
- By the user via the forgot password mechanism
- By the admin reset and/or update password mechanisms
- The LearnWorlds password update/reset functionality as well as sign-up are only available for the Default LearnWorlds Authentication mechanism. Any other SSO authentication mechanisms will need to handle these functionalities.
- In case you misconfigure the custom SSO setup and this is the only available authentication mechanism, then only the Learnworlds School Owner account will be able to sign in to your school via our Learnworlds account sign-in page (https://account.learnworlds.com/login)
- The built-in Affiliate Management program can not be used for users who use SSO providers to sign in
- If you want to use more than three custom SSO, SAML, or OpenID solutions in total, please contact us at support@learnworlds.com. In case you are on the Learning Center plan you can also add 3 more by purchasing our scale package.