Configuring SAML SSO with Centrify

Follow

This article guides you though setting up SAML-based Single Sign On for your Emtrain account using a Centrify custom SAML application.

Prerequisites

  • Active Emtrain account (Whole Culture/Enterprise level plan)
  • Active Centrify account
  • Your Centrify 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 that is consistent between their Centrify and Emtrain users.
    • 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 (Centrify and Emtrain)
  • The Centrify administrator creating the SSO app should have a Emtrain learner profile to test the integration.

Adding a custom SAML app in Centrify

First, create the SAML app in Centrify's admin panel.

  1. Click the Apps link.
    centrify_admin_1.png

  2. Click the Add Web Apps button.
    centrify_admin_2.png


  3. In the Add Web Apps modal, click the Custom tab, scroll to find SAML, then click the Add button to generate the app. centrify_admin_3.png

  4. Click the Yes button to confirm that you want to add the app.
    centrify_admin_4.png

  5. On the Settings screen of the newly created app, fill in the Name, Description and Category fields, upload the logo (attached at bottom of this article) and enter any other relevant settings per your organization's specifications.
    centrify_admin_5.png

  6. Identity Provider Configuration:
    Click on the Trust link in the left sidebar of the app page. On the app's Trust screen, check the Manual Configuration checkbox in the Identity Provider Configuration section.

    Download the Centrify SHA256 Tenant Signing Certificate, and copy the IdP Entity ID/Issuer and Single Sign On URL so they are at hand when you set up the Emtrain portion of the SSO app, as described later on in this article.
    centrify_admin_6.png

  7. Service Provider configuration:
    In the Service Provider Configuration section, check the Manual Configuration checkbox. To create the ACS URL, you must have your Emtrain account's API key to append to the end of the URL. The API key is located in the My Account > Developer Integration link in the Emtrain admin dashboard. Fill out the fields in this section as follows:

    Field Value
    SP Entity ID/Issuer/Audience https://lms.emtrain.com/lms/sign-on/centrify/metadata.php
    Assertion Consumer Service (ACS) URL* https://lms.emtrain.com/lms/sign-on/centrify/index.php?acs&key=your_emtrain_api_key
    Recipient Check "Same as ACS URL"
    Sign Response or Assertion Response
    NameID Format Unspecified
    Single Logout URL Leave "Single Logout URL" blank
    Encrypt SAML Response Assertion Leave "Encrypt SAML Response Assertion" unchecked
    Relay State Leave "Relay State" blank
    Authentication Context Class Unspecified

    *Your Emtrain account's API Key can be found in the My Account > Developer Integration link in the Emtrain admin dashboard. Craft the ACS URL by pasting your API key after the "&key=" parameter. Do not wrap it in parentheses or brackets!

    Click the Save button.

    centrify_admin_7.png

  8. Creating SAML attributes
    The SSO app requires two custom attributes for the SAML assertion. To create these attributes, click the SAML Response link in the app configuraton screen's left hand sidebar. In the Attributes section of the SAML Response screen, click the Add button.
    centrify_admin_8a.png

    For the Attribute Name, enter API_KEY (All uppercase, with underscore between the words). For the Attribute Value, paste in your Emtrain API key.
    centrify_admin_8b.png

    Create another custom attribute. For the Attribute Name, enter Email (Title case). For the Attribute Value, click the dropdown menu, select LoginUser, and select Email.
    centrify_admin_8c.png

    Note: The attribute names must match exactly. For example, if the Email attribute name is set to "email" or to "EMAIL", the sign in attempt would fail.

    Click the Save button to save your attributes before exiting.

Connecting your SSO app to your Emtrain account

Second, you must connect your newly created SSO app to your Emtrain account. To finish configuration of Single Sign On, you will need to designate the identity Provider, enter the IdP Entity ID/Issuer and Single Sign On URLs, and upload your Centrify SHA256 Tenant Signing Certificate in the Developer Integration section of your Emtrain admin dashboard.

Note: Upon completing this step, the Single Sign On application replaces the existing username/password authentication on your account. To avoid disrupting your user's progress, it is advisable to complete the process outlined here before rolling out training to your learners.

  1. In the My Account section of your Emtrain dashboard, click the Developer Integration link. 
    centrify_emtrain_admin_1.png
  2. Select the Configure SSO tab, and select Centrify from the Select SSO Identity Provider dropdown. Click Save to advance to the next step.
    centrify_emtrain_admin_2.png

  3. Enter the following URLs from step 6 of the "Adding a Custom SAML app in Centrify" section of this article.
    Emtrain field name Value Location in Centrify
    IdP Entity ID/ Issuer IdP Entity ID/Issuer URL generated by Centrify App> Trust> Identity Provider Configuration
    Single Sign On URL Single Sign On URL generated by Centrify App> Trust> Identity Provider Configuration

    The SAML 2.0 Endpoint URL will replace the Emtrain login links/username and password information in email notifications sent to users.

    centrify_emtrain_admin_3.png

    Click the Save button to advance to the next step.

  4. In the Upload x509 Cert section, upload the Centrify SHA256 Tenant Signing Certificate you downloaded in step 6 of the "Adding a Custom SAML app in Centrify" section of this article. If you have the certificate in multiple formats, use a PEM encoded certificate.

    centrify_emtrain_admin_4.png

Single Sign On is now complete and is configured as the login method for your Emtrain account. Admins who have set up passwords to log into the dashboard to configure SSO can continue to use their username/password logins.

Verifying the SSO integration

To verify that the SSO integration is functioning correctly, you or your testers will need the following:

  • An active learner on the target Emtrain account, where the Email address on the learner profile matches the email on the user's Centrify Email Address value.
  • An active Centrify account where the user's email address matches the email address on the user's Emtrain learner profile.
  • The tester's Centrify user must be provisioned with the Single Sign On app in Centrify.

To test the integration:

  1. Log into the Centrify User Portal. Click the Emtrain app tile. The user should be redirected to a Centrify intermediate URL, then redirected to their Emtrain Learner Portal (or admin dashboard if the user is an administrator on their Emtrain account).
  2. Open an incognito window/ private browsing window and ensure you do not have an open Centrify session in this window. Paste the Single Sign On URL into the browser's URL bar. Verify that you are prompted to log into Centrify, and are redirected to your Emtrain learner portal or admin This emulates the learner clicking on the Centrify login link included in a training notification.

Follow these troubleshooting steps if you receive a "Something seems to have gone wrong. You do not have access to this app" error message.

error2.png

  1. Verify that the email addresses on the Emtrain and Centrify user accounts you are testing with match exactly.
  2. Verify that your custom Email attribute created in step 8 of the "Adding a Custom SAML app" section of this article is named correctly (Email, with a capital "E"), and that it's value is set to LoginUser.Email.

Follow these troubleshooting steps if you receive a "Something seems to have gone wrong." error message, try the following troubleshooting steps:

error1.png

  1. Verify that the ACS URL is configured correctly:
    1. The API key needs to be added after the &key= portion of the base URL provided in this article.
    2. Make sure there are no extra characters or spaces between the "=" and the start of the API key
    3. Compare the API Key displayed in the My Account> Developer Integration> API Keys tab of your Emtrain admin dashboard matches exactly with what was added to the end of the ACS URL and is not missing any characters at the beginning or end
  2. Verify that the certificate that you uploaded is PEM encoded (.pem or .cer). Do not use a binary (DER) encoded certificate.
  3. Verify that the API_KEY attribute was constructed correctly
    1. Attribute Name should be in all caps, with an underscore ( _ ) between "API" and "KEY"
    2. Verify no characters were accidentally truncated or added to the API Key in the Attribute Value.

 

 

 

Comments