This support article will walk you through the prerequisites and process for setting up IdP-initiated Single Sign On between your Emtrain account and Azure AD Premium using SAML 2.0.
In order to set up this integration, you will need the following:
- An Azure AD Premium tenant (Global Administrator level access required for setup)
- An Emtrain account with Complete/Enterprise package (Administrator level access required for setup)
- The certificate generated by Azure when the application is set up.
- Your Emtrain API key (Found in the Developer Integration link under the My Account section of your dashboard)
- All users of the Emtrain SSO app must have a valid, unique Email address that is consistant in Azure and on Emtrain.
- A single email address cannot be used by more than one user
- Any user who is to use the SSO app must have an email address in their Emtrain learner profile
- User's email addresses must match across both platforms (Azure and Emtrain)
- The Azure administrator creating the SSO app should have a Emtrain learner profile to test the integration.
After you have confirmed that the above requirements are met, you can begin to create an Emtrain SSO app in Azure AD using the procedure below.
Creating the Azure SSO Application
- In the Active Directory section of your Azure instance, click into the AD instance you are adding the SSO app to and click the Applications tab. Click the New icon, then select Add an Application from the gallery. Select Custom, then select "Add an unlisted application my organization is using" and enter Emtrain as the name of the application. Click the checkbox button in the bottom right corner to proceed with configuring the application.
- After the app has been added, click the Configure single sign-on button.
- On page 1, select the "Microsoft Azure AD Single Sign-On" option and click the right arrow button.
- On page 2, enter the Identifier URL and the Reply URL. The Identifier URL is https://lms.emtrain.com/lms/sign-on/azure/metadata
To create the Reply URL you will need to obtain your Emtrain account's API key from the Developer Integration section of the LMS. If you do not have Administrator access to your Emtrain account, contact your Emtrain Administrator. The Reply URL is created by appending your Emtrain account's API key as a parameter to this base URL after the "=" symbol:
https://lms.emtrain.com/lms/sign-on/azure/index.php?acs&key=your API key here
Click the right arrow button after entering the URLs.
- On page 3, download the Base 64 certificate, and copy the Issuer URL and Single Sign-on Service URL and save them. You will need those items later to finish configuring the application. Check the confirmation checkbox and click the arrow button to move on to the next page.
- On page 4 click the check button to compete app configuration.
- Click the Attributes tab for your newly created application.
Some default SAML token values will be present. We will add one more attribute here, email. This attribute will be used in authenticating the user. The user's user.mail value in AD must match the user's email value in Emtrain in order for authentication to be successful. Click the Add User Attribute button. Enter email (all lowercase) into the Attribute Name field.
For the Attribute Value, select user.mail. Click the check button on the Attribute modal to create the attribute, then click the Apply Changes icon on the Attributes page to save it.
- To clearly identify the application in your users' Active Directory applications portal, upload the Emtrain logo as the Application Tile Logo on the Configure page. Download the Emtrain tile logo HERE, then upload the logo by clicking the Upload Logo icon at the bottom of the page and selecting the logo.
- The last step for this this stage of setup is to copy and save the Single Sign-on URL, you will need that URL later to finish configuring the application. Click the Dashboard tab and copy the Single Sign-on URL.
Configuring Single Sign On in your Emtrain Account
In this stage you will be entering the SSO URLs and uploading your certificate in your Emtrain account. This requires Administrator level access. If you do not have administrator level access to your organizations Emtrain account, please contact the administrator of your account.
- Click the Developer Integration link, then click into the Configure SSO tab.
- Select Azure as the SSO Provider from the dropdown menu.
- Paste the Issuer URL and Single Sign-on Service URL values into the appropriate fields. Click the Save button.
- Upload the Base 64 certificate into the x509 certificate section.
Once those steps have been completed, you will see confirmation that your Azure SSO application has been configured on your Emtrain account. Note that the Single Sign On URL will replace the Emtrain sign on links in email notifications sent from Emtrain.
Testing the SSO Application
Now that you have configured single sign on, assign the application to a test user. The test user must have a valid email address, an active Emtrain learner profile and an Active Directory user profile.
The test user should be able to log in by clicking the tile in your Active Directory Applications portal, and by pasting the Single Sign On URL into your browser. If the application was configured correctly and they have an active AD session open, they will be redirected to their Emtrain Learner Portal or Admin Dashboard, depending on their level of access. If they have logged out of Active Directory and attempt to log into their Emtrain portal via the Single Sign On URL, they should be prompted to sign in with their AD credentials, and will be redirected to your Emtrain Learner Portal/Admin Dashboard after signing in.
If testing turns up an error, please refer to the list of common errors below:
Error Message: "Something seems to have gone wrong. The following error occurred: You do not seem to have access to this app."
This error indicates that the email address in "email" attribute cannot be matched to a user on your account. Typical causes include:
- The user's Email in the Emtrain LMS does not match the user's primary email address in Azure. To resolve, update the user's email address in Emtrain to match their primary email address.
- The user's Email in the Emtrain LMS is misspelled or formatted incorrectly. To resolve, correct the user's email address in Emtrain
- The user's Emtrain profile is currently set to Inactive status. To resolve, set the user's Learner Access status to Active.
- The user does not have an email address associated with their Active Directory profile.
Error Message: "Something seems to have gone wrong. Contact your Azure administrator for more information."
This error indicates that the application is not configured correctly. There are several causes for this error:
- Reply URL is incorrectly formatted or missing the API Key parameter. To resolve:
- Ensure that on page 2 of the Azure app configuration dialog you have pasted your Emtrain account's API Key after the "=" symbol at the end of the base URL. Your API key should be formatted like this example URL: https://lms.emtrain.com/lms/sign-on/azure/index.php?acs&key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
- When generating your Reply URL, ensure that you have copied every character of the API key and have not accidentally truncated the API Key.
- Issuer URL is missing or incorrect. To resolve:
- On the Configure SSO tab of the Developer Integration page of your Emtrain account, confirm that the Issuer URL entered into Emtrain matches the Issuer URL provided on page 3 of the Azure app configuration dialog.
- Single Sign On Service URL is missing or incorrect. To resolve:
- On the Configure SSO tab of the Developer Integration page of your Emtrain account, confirm that the Single Sign On Service URL entered into Emtrain matches the Single Sign On Service URL provided on page 3 of the Azure app configuration dialog.
- Certificate cannot be authenticated. To resolve:
- On the Configure SSO tab of the Developer Integration page of your Emtrain account, confirm that a certificate has been uploaded as part of the the setup process.
- Do not open or edit your certificate after downloading it from Azure. If you have opened or edited the certificate prior to uploading it to your Emtrain account, download a new copy of the certificate and upload it to your Emtrain account.