This article guides you through the creation and testing of a Single Sign On (SSO) application that allows users in your Okta instance to log into their Emtrain Learner Portal from a link in their Okta portal, using SAML 2.0 authentication. These features are not enabled by default, if you are interested in using this feature, please contact your account representative or support for more information.
To complete the tasks outlined in this article, you will need to have Administrator privileges in your Okta instance, and either Administrator access to your Emtrain account or contact with the administrator of your Emtrain account to obtain your account's API key.
Before creating a SSO app in Okta, the following prerequisites are required:
- Active Emtrain account (Complete/Enterprise level plan)
- Active Okta account
- Your Okta x.509 certificate
- 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
- 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 (Okta and Emtrain)
- User's Email Addresses must match in Okta and in Emtrain.
- The Okta 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 Okta.
Create the Emtrain SSO app:
Step 1: Create a new SSO app in Okta
- Sign into Okta as an administrator. Click the Admin button, then hover over Applications and select Applications in the menu.
- Click the Add Application button
- Click the Create New App button
- In the Create a New Application Integration modal, select SAML 2.0 as the Sign On Method, then click the Create button
Step 2: Name the app, and configure SAML for the Emtrain SSO app
1. General settings:
In the General Settings section, you will enter the name of the application, as it will appear in your employee's Okta portal, add the Emtrain logo, and set the app's visibility.
- Enter the Name of the application as it is to appear in the user’s Okta portal. You can choose your own name, but be descriptive! Emtrain Training is the suggested standard name for the Okta app.
- Upload Emtrain’s logo for the App Logo. A properly sized PNG is located here.
- Set the App Visibility per your policies/requirements.
- Click Next to move on to SAML configuration
2. Configure SAML:
In the Configure SAML section, you will enter the URLs, Name ID format, Application Username format, and create some custom attributes in part A. You can preview the SAML assertion XML in part B.
- Single Sign On URL (check “Use this for Recipient URL and Destination URL"): https://lms.emtrain.com/lms/sign-on/okta/index.php?acs&key=Your API Key
- Audience URI (SP Entity ID): https://lms.emtrain.com/lms/sign-on/okta/metadata.php
- Default RelayState: https://lms.emtrain.com/lms/sign-on/okta/index.php
- Name ID format: EmailAddress
- Application Username: Email
Once you have completed the fields above, and they match the screenshot above, you need to add 4 custom attribute statements.
- Attribute Name: API_KEY
- Format: Basic
- Value: Enter your Emtrain API key here. (To obtain the API key, log into Emtrain as an administrator, click the Developer Integration section, and copy the API/HR Sync FTP Key out of the Your Account's API / HR Sync FTP Credentials section)
- Format: Basic
- Value: user.lastName
- Format: Basic
- Value: user.firstName
- Format: Basic
- Value: user.email
Download Okta x.509 certificate
Download the x.509 certificate for your Okta account. The certificate will be used to set up SSO on your Emtrain LMS dashboard. In the sidebar next to the Configure SAML dialog, click the Download Okta Certificate button and save the .cert file.
Preview the SAML assertion XML
Once you've finished entering the URLs and creating the attribute statements, preview the SAML assertion XML to verify your attributes are correct. The XML markup will open in a new tab.
Click the Next button when you are done previewing
Okta asks you for some basic information about the app you are creating. Select the following options
- Select “I'm an Okta customer adding an internal app”. If desired, fill out the optional questions:
- Which app pages did you consult to configure SAML?: http://support.emtrain.com/hc/en-us/articles/212913686
- Did you find SAML docs for this app?: http://support.emtrain.com/hc/en-us/articles/212913686
Configuring SSO in Emtrain
Once your SSO app is created, you will set the SSO link to be used in your announcement and reminder emails and upload your x.509 certificate.
- In the Okta admin dashboard, navigate to the Emtrain SSO app in your Applications page, and select the General tab. Copy the App Embed Link from the App Embed Link section at the bottom of the page.
- In the Emtrain LMS, navigate to the My Account section, and click the Developer Integration link
- Select Okta for the SSO Identity Provider. In the Enter App Embed Link field, paste in the App Embed link you copied from Okta, then click Save.
- Upload the x.509 certificate. Click the Browse button, select the certificate and click the Upload button.
Once configured as shown above, the training announcement and reminder emails sent from your Emtrain account will use the App Embed Link in the login instruction portion of the email. When the learner receives the training email and clicks the link, they will be logged into their Emtrain Learner Portal if they have an active Okta session open, or will be prompted to log in to their Okta account.
Testing your newly created Emtrain SSO app:
To test that the SSO application is functioning correctly, the Okta administrator will provision the application to test users who have valid user profiles in both Okta and Emtrain. Typically, the Emtrain administrator should have a user profile in both platforms, but you may need to create a test user in both Emtrain and Okta. The email address must match across both platforms.
To assign the app for testing:
- From the Okta admin dashboard, hover on the Applications link, and select Applications from the menu. Navigate to the Emtrain SSO app.
- On the application page, navigate to the People tab, and click the Assign to People button.
- Click the Assign button for the user who will be testing the app.
- Click the Save and Go Back button, then click the Done button.
When the test user logs into their Okta portal, they will see the Emtrain SSO app linked, clicking the app will log them into their learner portal, or administrator dashboard, depending on their Emtrain permissions.