Overview

Single sign-on (SSO) is an authentication process that allows users to access multiple applications using a single set of login credentials. The platform supports SSO through several providers, including Google Workspace, LDAP, and Microsoft 365/Office 365. You can also configure SSO using SAML 2.0, Auth0, or OAuth identify providers, or set up a custom integration. 

Google Workspace

The 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, visit the Google Apps article.

LDAP

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

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. The SAML 2.0 single sign-on integration allows users to sign-in to the platform through an Identity Provider (IdP). For more details on how to configure SAML 2.0, visit the SAML 2.0 SSO article

Microsoft 365/Office 365

To configure the Microsoft 365/Office 365 SSO login:

1. Click Admin from the primary navigation menu.
   
2. Click App center from the fly-out menu.
   
3. Install the Microsoft Entra ID app from the Authentication section. 
   

1. Click the Configure  icon on the app tile.
   
2. Enter your Microsoft Office 365 domain.
   
1. Note that you can enter multiple domains separated by a comma.
3. Click Save. 
   

Once single sign-on with Office 365 is enabled, additional options display:

1. Select the Auto create account if it doesn't exist checkbox if you would like to allow Office 365 SSO to auto-create accounts on your learning platform if they don't already exist.
   
1. If enabled, this feature will create a new learner account using the first name, last name, and email address from Office 365.
   
2. Click Edit to edit the SSO domain information.
   
3. Click Disable to disable the Office 365 SSO.
   

After enabling SSO with Microsoft Office 365, a new button displays on the Log in pop-up that allows users to log-in using their Offie 365 credentials.  

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 an Auth0 integration with your learning portal, you will need an Auth0 account. As a first step, you need to create an application.

1. Log into your Auth0 account.
   
2. Access the Applications section.
   
3. Click the Create Application button.
   

The Create application pop-up displays.

1. Name the application.
   
2. Select Regular Web Applications.
   
3. Click Create.
   

The application will be created. Once it is created:

1. Click the Settings tab.
   
2. Complete the form. 

1. In the Allowed Callback URLs field enter the callback URL.
   
1. For example -  https://PortalName.matrixlms.com/auth0/login - replacing 'PortalName' with your URL portal name.
   
2. 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.
   
3. Include a URL for the logged in state as well. For example: 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 portal, include it in the Allowed Callback URLs field. 

1. Enter your site's logged out URL in the Allowed Logout URLs field.
   
1. For example: https://PortalName.matrixlms.com/log_out/logged_out
   
2. Enter your site's URL in the Allowed Web Origins field.
   
3. After configuring the application settings, click Save.

1. Click the application.

The Application displays.

1. Click the Connections tab.
   
2. Ensure the Username-Password-Authentification setting is toggled on. 
   

The next step is to enable APIs for your app.

1. Click APIs on the left menu.
   
2. Click Auth0 Management API.
   

1. Click the Machine to Machine Applications tab.
   
2. Turn the toggle on for your application to authorize APIs for your app.
   

To configure the permissions/scope of your application's API authorization:

1. Click the down arrow  next to the Authorized toggle. 
   

The API permissions display.

1. Click All if you would like to authorize permission for all APIs.
   
1. If you do not want to select All in the Permissions/Scopes section, you can select the following scopes to enable:
1. read:client_grants
2. read:users
3. update:users
4. create:users
5. read:users_app_metadata
6. update:users_app_metadata
7. create:users_app_metadata
8. read:clients
9. read:connections
   
2. Click Update.

1. Click Users in the User Management section of the left menu.
   
2. Click Create User.
   

Enter the details of the user:

1. Select the database connection to use to authenticate the user.
   
2. Enter the user's email address.
   
3. Enter the user's password. There is no maximum limit for the password length.
   
4. Click Create.
   

Enabling Auth0 integration

To enable Auth0 integration with your platform, you must first install the Auth0 SSO app. To install the app:

1. Click Admin from the primary navigation menu.
   
2. Click App center from the fly-out menu.
   
3. Click Install on the Auth0 SSO app in the Authentication section. 

To configure the app:

1. Click the Configure  icon on the Auth0 SSO app tile.
   

You will be redirected to the Auth0 tab for Administrator Single sign-on settings.

1. Click Configure.
   

The Configure Auth0 page displays.

1. Enter your Auth0 Domain, Client ID, Client Secret, and Database Name. 
   
1. This information can be located in your Auth0 account, covered in more detail below.

To locate your Auth0 Domain, Client ID, and Client Secret:

1. Login to your Auth0 account.
   
2. Click your application.
   
3. Click the Settings tab.
   
1. Your Domain, Client ID, and Client Secret display.

To locate your Database name:

Complete the fields in the Configure Auth0 tab in the Admin Single sign-on section of your CYPHER platform.

After Auth0 SSO is enabled, users will see a Log in with Auth0 button on the Log in pop-up.

1. Click Admin from the primary navigation menu.
   
2. Click Single Sign-on from the fly-out menu.
   
3. Click the Auth0 tab.
   
4. Click Disable.

Changing Auth0 email addresses

If you entered the Client Secret when configuring Auth0 (shown in the screenshot below), you can update your email address in your learning platform, and it will automatically update the email address in the Auth0 database. 

Note that this only works if the old email is in the Auth0 database and the new email is not.

To change your email address:

1. Click your profile picture in the upper right corner.
   
2. Click Edit on your profile page.
   
3. Click Info. 
   

Your profile information displays.

1. Update your email address.
   
2. Click Save. 
   

You will receive a notification when the Auth0 email action is complete.

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

The email address will be updated in the Auth0 database.

Note that this feature only works in case of individual updates, and not in the case of bulk updates (for example importing the email addresses from a CSV file).

Auto create platform accounts

If enabled, the platform can create new accounts based on a user's Auth0 credentials. To enable the creation of new accounts on your CYPHER learning platform:

1. Click Admin from the primary navigation menu.
   
2. Click Single sign-on from the fly-out menu.
   
3. Click the Auth0 tab.
   
4. Select the Auto create account if it doesn't exist checkbox.
   
1.  If this option is enabled a learner account will be created for visitors who don't have an account on the platform when they log in using the Auth0 SSO and their Auth0 credentials.
   

In order to create a new account on your platform that contains the visitor's first and last name, you must set up custom fields on Auth0 that contain the given name (first name) and family name (last name) of the user. The fields can be defined for each user individually on their Auth0 profile page. 

If these fields are set up in Auth0, then the new user will be created with a first and last name, otherwise, the platform parses the email address for the new user.

Now, your platform will create new accounts for visitors with Auth0 credentials. Visitors:

1. Access your platform.
   
2. Click Log in.
   
3. Click Log in with Auth0.

If the credentials are verified with Auth0, a new account will be created for the user.

Auto create Auth0 user when creating news users on your platform

If enabled, the platform can also create new Auth0 user accounts when you add new users to your platform. Before you enable this feature:

1. Click Admin from the primary navigation menu.
   
2. Click Single sign-on from the fly-out menu.
   
3. Click the Auth0 tab.
   
4. Ensure the Database Name is entered
5. Select the Auto create Auth0 user when creating new MATRIX user checkbox.
   
1. If you enable this feature, you can also select the Require email verification when creating Auth0 user checkbox to require email verification when creating an Auth0 user.
   

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.

Note that 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 install the app:

1. Click the Configure  icon on the OAuth 2.0 SSO tile.
   
2. Or, click Admin from the primary navigation menu.
   
1. Click Single sign-on from the fly-out menu.
   
2. Click the OAuth 2.0 tab.
   
3. Click Configure.

1. Enter the Authorization URL, Token URL, and Userinfo URL from OAuth 2.0.
   
2. Enter the Client ID and Client secret from OAuth 2.0.
3. Silent Authentication: If you enable Silent Authentication, no login pop-up will be displayed when the user is already logged in to OAuth 2.0, in this case, they will be automatically logged-in to their learning portal. 
   
4. Click Save.

Custom single sign-on

The platform also offers a Custom SSO option. To set up a Custom SSO, you must first install the app. To install the app,

1. Click the Configure  icon on the Custom SSO tile.
   
2. Or, click Admin from the primary navigation menu.
   
1. Click Single sign-on from the fly-out menu.
   
2. Click the Custom tab.
   
3. Click Configure.

The Custom Configure page displays with the following fields:

Users can login in two ways:

Users will be authenticated by the third party at the Remote authentication URL, and the data will be prepared and encrypted to be sent back to your platform.

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, the CYPHER platform will check if the data is valid and encrypt everything to check if the hashes match. If the user is authenticated, they 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.

Once you have enabled a Custom SSO, two new buttons will appear. 

1. Click Disable to disable the custom SSO.
2. Click Edit to edit the custom SSO settings.
   

Single sign-on per Organization

The platform allows you to create custom visitor portals for organizations, and determine which single sign-on provider you want to use for the organization portal. 

To access the organization to configure SSO settings:

1. Click Organizations from the primary navigation menu.
   
2. Click the Organization name from the fly-out menu. 
   

The Organization page displays.

1. Click Admin from the Organization menu.
   
2. Click Portal from the fly-out menu.

If you have enabled a custom visitor portal for the organization, multiple sections display, including the Single sign-on section (shown in the screenshot below).

The Single sign-on section shows available SSO providers. Available options include:

1. By default, the Inherit business-level provider option is selected. Selecting this setting means your organization will offer the same SSO provider or providers configured at the business or school level.
   
2. Select None if you do not want to offer single sign-on for your organization visitor portal.
   
3. Select a specific provider if you would like to offer one specific SSO provider on your organization's visitor portal.
   
1. Please note that if you select a specific SSO provider for the organization, you can only choose one provider for the organization.
   

If you select a specific SSO provider for the organization, the Enabled and Configure columns are populated for the provider.

1. Click the Configure  icon in the Configure column to access the SSO provider settings.
2. The Enabled column shows if a SSO provider is enabled.
   

Additionally, if you select a specific SSO provider, a new tab will appear for the SSO provider.

1. Click the SSO provider tab.
   
2. Click Configure to set up the SSO configuration.
   
3. Follow the configuration instructions for the SSO provider that are provided in this article.

Note: Multi-organization configuration is not available for LDAP.