Requirements and Overview

These are the requirements for using the Google/Emtrain SSO integration:

• Active Emtrain account, and the Emtrain account's subdomain
• The Emtrain account’s API Key (obtain this by navigating to the Site Config area of the Manage Tools and choose the Integration tab.)
• Active Google Account
• Any user who will be signing into Emtrain via Google must have an email address
• Email addresses must be unique per user
• The user must have the Emtrain SSO app assigned/available to them in Google

The SSO integration uses the SAML 2.0 protocol. Setup of the integration consists of creating a custom SAML connector in Google, taking the SAML endpoint and X.509 certificate generated for the custom SAML app and entering these into the SSO configuration form on the Emtrain account.

Completing the SSO integration disables username/password based authentication on the Emtrain account.

Emtrain uses email address to match the email in the SAML assertion to the learner's corresponding Emtrain user.

Creating the Custom API_KEY User Attribute

It is more convenient to set up the custom API_KEY user attribute before starting the process of creating the custom SAML App. If you leave this process for later you will have to finish creating the SAML app without the API_KEY attribute, add it per the steps below, then edit the SAML application to add the API_KEY attribute.

• From the main page of the Google Admin Console, click the Users tile.

• In the Users section, click the More menu button and select Manage custom attributes.
• Click the ADD CUSTOM ATTRIBUTE link.

• In the Add Custom Fields dialogue, add the following values and then click the Add button. For the custom field Name, be sure to use the capitalization shown below:
  • Category: SAML
  • Description: Emtrain SAML API_KEY
  • Custom Fields:
    • Name: API_KEY
    • Info Type: Text
    • Visibility: Visible to user and admin
    • No. of Values: Single Value

• For any test users who will be testing the application, enter the value of your Emtrain account's API Key into this new API_KEY field on their user profile.

Creating the Custom SAML App

• In the Google Workspaces dashboard, Select the Web and mobile apps tile.

• In the Web and mobile apps section, click the Add App menu button, then select the Add Custom SAML App menu item.

App Details

• On the App Details screen, enter Emtrain in the App Name  text field. Upload the provided logo image in the App Icon field. Click the Continue Button.

Google Identity Provider Details

• On the Google Identity Provider Details page, copy/download the Certificate and SSO URL/Entity ID URL. Click the Continue button once you have saved these details.

Service Provider Details

On the Service Provider Details page, enter the following URLs into the corresponding text fields. To create the URLs for your account using the examples below, replace the "example" subdomain with your account's subdomain in all 3 example URLs. Additionally, replace the example API_KEY value (shown as all zeros here) in the ACS URL with your account's API key.

• ACS URL: https://example.ai-api.emtrain.com/authentication/saml?API_KEY=00000000000000000000000000000000
• Entity ID: https://example.app.emtrain.com
• Start URL: https://example.app.emtrain.com/saml

Once you have filled in the 3 URLs, click the Continue button.

Attribute Mapping

In the Attribute mapping page, you will map the attributes included in the SAML assertion to the appropriate field on the Google user profile.

In the Attributes section, click Add Mapping. Add the following 4 mappings, making sure to use the capitalization shown in the App attributes section below. Click the Finish button after all 4 attributes have been mapped.

Google Directory Attributes: API_KEY

App Attributes: API_KEY

Google Directory Attributes: Primary Email

App Attributes: Email

Google Directory Attributes: First Name

App Attributes: FirstName

Google Directory Attributes: Last Name

App Attributes: LastName

Note: The API_KEY attribute is a custom attribute that you will need to create in the Users section of the Google Admin Console and assign the value of your Emtrain Account's API key to the SSO app's users. If. you have not already done so, follow the instructions in the Create the custom API_KEY user attribute section located at the beginning of this article.

Enabling SSO in your Emtrain Account

Enabling the Google SSO application in your Emtrain account consists of creating an SSO Entry Point URL, and entering the SSO entry point URL and the Certificate provided by Google into the SSO integration form in the Emtrain Manage Dashboard.

Creating the SSO Entry Point URL

The SSO Entry Point URL is a URL that your users will be directed to when they visit your Emtrain account page. Unlike most identity providers, Google does not provide an easily accessible URL for this when creating the custom SAML application, so you must construct it.

• Isolate the idpid from the SSO URL/Entity ID URL provided by Google. If you did not copy it down at the beginning of this process, it can be found by clicking the Download Metadata button. The idpid is the alphanumeric text located after "idpid=" in the Google Entity ID or SSO URL. It is shown in the modified screenshot below as 22222222222:

• Isolate the spid. This is the identifier of your custom SAML app, and can be found in the URL of the custom SAML app's overview page, after /apps/saml. It is shown in the modified screenshot below as 111111111111:

• Create the SSO Entry Point URL by replacing the idpid and spid shown below with the idpid and spid specific to your account: https://accounts.google.com/o/saml2/initsso?idpid=22222222222&spid=111111111111

Configuring the Emtrain Account to Use the Custom SAML Application

Log in to your Emtrain account as your Account Administrator User. In the Manage Section, click the Site Config button in the left sidebar.

Note: completing the steps described below will disable Username/Password authentication on your Emtrain account.

• Select the Integrations tab.
• Check the box to Enable Singe Sign-On (SSO), select Google as the SSO provider.

Paste the contents of the certificate between the --BEGIN CERTIFICATE---/---END CERTIFICATE--- lines in the Certificate text field. Note: Do not include the ---BEGIN CERTIFICATE---/---END CERTIFICATE--- lines in the Certificate text field!

• Paste the SAML 2.0 Endpoint value into the SSO Entry Point text field.

• SSO Logout Redirect URL is optional.
• Click the Save button to finalize the integration.

Note that once you have saved the integration, Username/Password authentication is disabled on your Emtrain account, and visiting your Emtrain account will redirect the visitor into the Google SAML authentication flow instead of prompting the visitor to log in with their username and password.

Testing SSO

• In the Google Admin console, add the application to the test user(s). Add the Emtrain API Key value to the API_KEY field if you have not already done so.
• In Emtrain, create user(s) with the same email address as the test user(s). The email address is used as the identifier to match the email address on the SAML assertion to a user on the Emtrain account and must match in both platforms.
• The test user should test the application tile in their Google Apps menu and verify that they are logged into Emtrain as their test user.
• The test user should open a new incognito/private browsing session and visit the Emtrain account home URL. The user should be redirected to the SAML 2.0 Endpoint URL and prompted to authenticate with their Google account.

• Upon authenticating, the user should be logged into Emtrain as their test user.