Overview

Single Sign-On (SSO) is a session/user authentication process that permits a user to enter one name and password in order to access multiple applications. Our system currently offers Single Sign-On through Google Workspace, LDAP, Office 365, or you can use a custom integration. 

Google Workspace

Our Google Workspace integration allows you to leverage your existing Google Workspace accounts for the purposes of Single Sign-On. For more details on how to configure Google Workspace click here.

LDAP

LDAP (Lightweight Directory Access Protocol) is a popular way for organizations to store account information for authentication and other purposes. Our platform can integrate with your LDAP server for authentication and optionally for account creation. For more details on how to configure LDAP click here.

SAML 2.0

SAML (Security Assertion Markup Language) is an XML-based, open-standard data format for exchanging authentication and authorization data between an identity provider and a service provider. Our SAML 2.0 Single sign-on integration allows users to sign-in to our platform through an Identity Provider (IdP).For more details on how to configure SAML 2.0 click here.

Office 365

To configure the Office 365 SSO login, go to Admin/App center, and install the Office 365 SSO app. 

Then click on Configure to start setting up your options.

Enter your Microsoft Office 365 domain, then click Save. Note that you can enter multiple domains separated by a comma.

You can enable an option for Office365 SSO that can auto-create an account on your learning platform if it doesn't already exist. If enabled, it will create a new student with their first name, last name, and email address loaded from Office365.

To edit the domain, click on Edit. To disable the Office 365 SSO, click on Disable.

Now users will see a new option to log in using Office 365 on the portal.

Auth0 integration

Auth0 allows you to authenticate and authorize apps and APIs with any identity provider running on any stack, any device, or in the cloud. Auth0 makes it easy for you to give your users the ability to authenticate with the credentials they are most familiar with.

Configure Auth0

To configure Auth0 integration with your learning portal, you will need an Auth0 account. As a first step, you need to create an application. Log into your Auth0 account, visit the Applications section, and click the "Create Application" button.

Give a name to the application and select "Regular Web Applications", then click Create.

After the application is created, visit its Settings tab and enter the required information.

In the "Allowed Callback URLs" field enter the callback URL. For example https://PortalName.matrixlms.com/auth0/login. You can specify multiple valid URLs separated by a comma. Make sure to specify the protocol, http:// or https://, otherwise the callback may fail in some cases. You also have to enter an URL like this: https://PortalName.matrixlms.com/auth0/logged_in?state=https%3A%2F%2FPortalName.matrixlms.com%2F

Note that if you use a custom URL for your MATRIX portal, make sure to enter it in the "Allowed Callback URLs" field. 

You also have to enter your site's URL in the "Allowed Web Origins" field.

In the "Allowed Logout URLs" field enter your logout URL. For example: https://PortalName.matrixlms.com/log_out/logged_out

After you configured the settings click Save. The newly created application will be listed in the Applications area.

Click on the application and visit the Connections tab to make sure that Username-Password-Authentification is enabled under Database.

The next step is to enable APIs for your app. Go to the APIs tab end click on "Auth0 Management API".

Go to the "Machine to Machine Applications" area and authorize APIs for your app.

After you authorized the APIs, visit the Scopes section by clicking on the ">" icon.

Select All, then click Update.

In case you don't want to select "All" in the Scopes section, here is the list of scopes that you should enable for your Auth0 account:

After you created the app, visit the Users & Roles/Users area. To create new users, click on the Create user button.

Enter the details of the user, then click Save.

Enabling Auth0 integration

To enable Auth0 integration with your MATRIX portal, log into your MATRIX portal, go to Admin/App center, and install the Auth0 SSO app.

After installing the app click the Configure icon.

You will be redirected to the Single sign-on/Auth0 area. Click on the Configure button.

Enter your Auth0 domain, Client ID, Client Secret, and Database name. After you entered the required information, click Save.

You can find all this information in your Auth0 account. To see your Auth0 domain, Client ID, and Client secret visit the Applications/Setting area.

You can see the Database name in the Applications/Connections area.

The mandatory fields are the Auth0 Domain and Client ID. If you enter this information, users will be able to log in using Auth0 SSO. 

The Client Secret is optional and it's used for changing and verifying email addresses. After you enter the Client Secret you will be able to change the email address in the Auth0 database from your MATRIX portal.

The Database Name is also optional and it's used to update/reset passwords. After you enter the Database Name you will able to change/reset the password in the Auth0 database from your MATRIX portal.

If you enable "Auto Login", users can skip our login pop-up and go directly to the Auth0 option. When clicking log in, they will be automatically logged-into their account using Auth0.

If you enable "Silent Authentication" no login pop-up will be displayed when the user is already logged in to Auth0, in this case, they will be automatically logged-into their learning portal. Otherwise, they will get the login pop-up.

To disable the integration visit Admin/Single sign-on and click Disable under the Auth0 tab.

After Auth0 SSO is enabled, users will have the possibility to use Auth0 to log into MATRIX.

Note that in order to log in with Auth0 your email has to be verified. If it isn't verified, click the link to resend the email verification.

Changing email addresses

In case you entered the Client Secret when configuring Auth0, if you update an email address on your MATRIX portal, it will automatically update the address in the Auth0 database. Note that this only works if the old email is in the Auth0 database and the new email isn't.

To change the email address click Edit on the profile page, then select Info.

Change the email address then click Save.

You will receive a notification when the action is complete.

An email will be sent to the new email address, where the user has to verify the account.

The email address will be updated in the Auth0 database.

Note that this feature only works in case of individual updates. In the case of bulk updates (for example importing the email addresses from a CSV file), you have to make the updates separately in the Auth0 database.

Reset passwords

In case you entered the Database Name when configuring Auth0, you will be able to change the password in the Auth0 database from your MATRIX portal.

To change the password, go to the profile page and click Reset password.

The user will receive an email to confirm the password change request.

Enter the new password then click Save.

Auto create account on MATRIX if it doesn't exist

You can enable the "Auto create account if it doesn't exist" option when configuring Auth0 integration. If this option is enabled a learner account will be created for the visitors who don't have an account on your MATRIX portal and they try to log in using the Auth0 SSO and their Auth0 credentials.

In order to create a new account on your MATRIX portal that contains the visitor's given and family name, you will have to set up custom fields as the user's metadata that contains the given name and family name. The custom fields can be defined for each user individually on their Auth0 profile page. 

If these fields are set up on the Auth0 side, then the new user will be created with the defined given name and family name, otherwise, we parse the email address for the new user.

After you added the custom fields to the user's metadata on the Auth0 profile, go back to your MATRIX portal and visit the Admin/Single sign-on/Auth0 section then enter the name of the fields.

Note that in order create the new account on your MATRIX portal the user's email has to be verified. If it isn't verified, users can click the link to resend the email verification.

After the users verify their email they can try to log in once again.

If the email is verified, then a new account will be created for the user.

Auto create Auth0 user when creating new MATRIX user

If you enable the "Auto create Auth0 user when creating new MATRIX user" option, then an Auth0 account will be automatically created for every newly added account on your MATRIX portal.

Before you enable this feature, go to your Auth0 account and visit the Clients/Your app/Connections and make sure Database is enabled.

Also make sure to enable APIs for your app and select the "create:users" scope as well. 

After you configured your Auth0 account, go to your MATRIX portal and visit the Admin/Single sign-on/Auth0 section and enable the  "Auto create Auth0 user when creating new MATRIX user" feature. Also, make sure that the Database Name is entered.

If you enable this feature, you can also enable an option to require email verification when creating an Auth0 user.

Note that currently, we only create an Auth0 user account if an email address is available. You can make email a required field if you want to enable Auth0 user account creation. To make email a required field go to Admin/Accounts/Fields, edit the email field and click "No" under "Optional on sign up".

Note that if the user signs up and enters a password, that password is transmitted to Auth0 as it is. If the account is created by an upload, CSV, or another mechanism, then the password is automatically generated and is transmitted to Auth0, and users are required to change the password on the first login.

OAuth 2.0 SSO

You can now connect to generic OAuth 2.0 SSO providers using OAuth 2.0 for authorization and OpenID Connect (OIDC) for authentication.

IMPORTANT NOTE: OAuth 2.0 is not supported as an organization-level SSO provider.

To use OAuth 2.0, you must first install it from the App Center. To do so, navigate to Admin/App Center and search for OAuth 2.0. Click Install on the appropriate tile.

Next, enter the appropriate credentials for the integration. 

Once complete, you can access OAuth 2.0 SSO by clicking Admin and then Single sign-on.

From here, click the appropriate tab at the top of the screen to access the credentials.

Custom single sign-on

To configure the Custom SSO login, go to Admin/App center, and install the Custom SSO app. 

Then click on Configure to start setting up your options.

Enter the required details, then click Save. 

Warning! If the private key is reset, it needs to be changed also into the third party settings, otherwise, users will not be able to log in anymore.

The login can be made in two ways:

When accessing this URL we identify the business and create a time stamp valid for 5 minutes. After this the user will be redirected to the Remote authentication URL that you provided also sending the business id, business URL, time stamp, and a “from” parameter which can be used to go after log in at a specific location in our platform( ex: ?from=/teacher_lessons/list/[id] and the user will be sent to the class with the specific id ).

On the Remote URL, the user will be authenticated by the third party, and the data will be prepared and encrypted to be sent back to us.

PHP

Here is a small PHP example of a code of how you should prepare and send the data:

// get data sent by us
$from = $_GET["from"];
$school_id = $_GET["schoolid"];
$school_url = $_GET["schoolurl"];
$timestamp = $_GET["timestamp"];

// get the private key from your system
$private_key = "d6e461d05af9e17bf8a5a25d2d1d5bcfc54d9579";

// get user username and email
$username = "peter.pan";
$email = "peter.pan@wonderland.com";

// get last and first name - MANDATORY IF THE AUTO-CREATE OPTION IS ACTIVATED
$first_name = "Paul";
$last_name = "Peterson";

// create an array with all the data except the private key
$params = array(
  'from' => $from,
  'schoolurl' => $school_url,
  'schoolid' => $school_id,
  'timestamp' => $timestamp,
  'username' => $username,
  'email' => $email,
  'first_name' => $first_name,
  'last_name' => $last_name
);

$params = array_filter($params);

// first create a string with the array data
$hash_msg = implode('', array_values($params));

// then create md5 hash from the private key and the string that you just created
$hash = md5($private_key . $hash_msg);

// generate the query string
$query_params = array();

foreach($params as $key => $value)
{  $query_params[] = $key . '=' . rawurlencode($value);
}

$query = implode('&', $query_params);

// create the redirect url where the data will be check
$url = $school_url . '/sso/login?' . $query . '&hash=' . $hash;

// redirect back to us
header("Location: " . $url);

?>

JavaScript

Here is a small JS example of a code of how you should prepare and send the data:

const urlParams = new URLSearchParams('');

// get data sent by us
from = urlParams.get('from');
school_id = urlParams.get('schoolid');
school_url = urlParams.get('schoolurl');
timestamp = urlParams.get('timestamp');

// get the private key from your system
var private_key = "";

// get user username and email
var username = "";
var email = "";

// get last and first name - MANDATORY IF THE AUTO-CREATE OPTION IS ACTIVATED
var first_name = "";
var last_name = "";

// create an array with all the data except the private key
var params = {'schoolurl': school_url,'schoolid': school_id,'timestamp': timestamp,'username': username,'email': email,'first_name': first_name,'last_name': last_name};

// if 'from' contains no data, do not add it to the array
if (from != null){
params['from'] = from;
}

// first create a string with the array data
var paramsStr = Object.values(params);var hash_msg = paramsStr.join().replace(/,/g,'');

// then create md5 hash from the private key and the string that you just createdvar hash = md5(private_key + hash_msg);

var urlEncodedData = "";

// create the redirect url where the data will be check
var properties = Object.keys(params);
var size = properties.length - 1;
$.each(properties, function (index, name) {
urlEncodedData += encodeURIComponent(name) + '=' + encodeURIComponent(params[name])
 + (size === index ? '' : '&');
});

var url = school_url + '/sso/login?' + urlEncodedData + '&hash=' + hash;

// redirect back to us
window.location.replace(url);

After this, we will check if the data is valid and encrypt everything to check if the hashes match. If everything is ok the user will be logged into the system. Otherwise, the user will be redirected with an error message to the return URL or to the business URL.

To edit the custom SSO settings, click Edit. To disable the custom SSO, click Disable.

Single Sign-On per Org

To begin, install the applicable SSO app from the App Center. See the sections above for the applicable SSO for your organization and the steps to enable each.

Once your chosen SSO app or apps are installed, navigate to Organizations / <Org Name>.

From the organization landing page, click Admin/Portal.

The Single Sign-On section appears if the portal is created and enabled.

In the Single Sign-On section, the available SSO options are displayed.

The “Inherit” option is the default. This will use the same provider or providers configured at the school/business level (under Admin / Single sign-on).

Once you select an SSO provider for this organization, the Enabled and Configure columns are populated for this provider.

The Enabled column shows if a SSO provider is enabled.
In the Configure column, you can click the cog icon to open the SSO provider configuration page.

Additionally, once you select a SSO provider, a new tab will appear at the top of the page.

Click the tab name to open the configuration page. (You can also click the cog icon.)

Click Configure to set up the SSO configuration.

ADDITIONAL NOTES:

By default, the SSO policy for organizations is “Inherit”, which applies the school/business level SSO settings to the organization. If there are multiple providers set up at the school/business level (Admin / Single sign-on), they will all be available for the organization.

When choosing a specific SSO provider for the organization, you can only choose one provider at the same time, unlike at the school/business level where multiple providers can be active at the same time.

Setting the SSO policy to “None” will disable SSO for the Organization, no matter what the school/business level setting is.

Multi-organization configuration is not available for LDAP.