Search

Google Single Sign-On (SSO) Integration Guide

Gretchen
Gretchen
  • Updated

This guide explains how to set up Google Single Sign-On (SSO) so your users can access Emtrain with their existing login credentials, rather than a separate login process. 

Requirements 

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

  • An active Emtrain account.
  • An unique email address for every user.
  • An active Google account.
  • A valid email address for all users in Google.
  • The API key for your account: Obtain your API key by navigating to Site Config from the Manage menu. Select the Integrations tab and then the option to Enable SSO.

Each user’s email address in Emtrain must match their primary email address 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.

Once you save the integration, username and password authentication will be disabled on your Emtrain account. This means that when you or your team members go to access your Emtrain account, you'll be redirected to complete the SSO authentication process instead of entering a username and password.
This change happens immediately after you complete the integration setup, so make sure your team is prepared for the new login process.

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.

  1. From the main page of the Google Admin Console, select the Users tile.
    Google1.png
  2. In the Users section, select the More menu button and select Manage custom attributes.
    Google2.png
  3. Select the ADD CUSTOM ATTRIBUTE link.
    Google3.png

  4. In the Add Custom Fields dialogue, enter 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

    Google4.png

  5. 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

  1. In the Google Workspaces dashboard, select the Web and mobile apps tile.
    Google5.png
  2. In the Web and mobile apps section, select the Add App menu button, then select the Add Custom SAML App menu item.
    Google6.png

App Details 

  1. On the App Details screen, enter Emtrain in the App Name text field.
  2. Upload an Emtrain logo in the App Icon field.
  3. Select Continue.
    Google7.png

Google Identity Provider Details

  1. On the Google Identity Provider Details page, copy/download the Certificate and SSO URL/Entity ID URL.
  2. Select the Continue button once you have saved these details.
    Google8.png

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 each example URL below. 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://yourcompany.ai-api.emtrain.com/authentication/saml?API_KEY=[00000000000000000000000000000000]
  • Entity ID: https://yourcompany.app.emtrain.com
  • Start URL: https://yourcompany.app.emtrain.com/saml

Once you have filled in the URLs, select the Continue button.
Google9.png

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.
Google10.png

  1. In the Attributes section, select Add Mapping.
  2. Add the following 4 mappings, making sure to use the capitalization shown in the App attributes section below.
    • 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
  3. Select the Finish button after all 4 attributes have been mapped.
    Google11.png

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 field located in Site Config. Navigate there via the Manage menu by selecting Site Config, then the Integrations tab.

We offer Just-in-Time (JIT) provisioning, which works with SSO. This enables automatic user profile creation the first time a user logs into Emtrain via SSO. Learn about Just-in-Time Provisioning with SSO.

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.

  1. 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 selecting 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:
    Google12\.png
  2. 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:
    Google13.png
  3. 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

To begin, log into your Emtrain account as your Account Administrator User.

  1. Navigate to the Site Config area via the Manage menu.
  2. Select the Integrations tab.
  3. Check the box to Enable Single Sign-On (SSO), select Google as the SSO provider.
    Google14.png
  4. Paste the contents of the certificate in the Certificate text field. Include only the certificate values. Do not include the “Begin” and “End” content: ---BEGIN CERTIFICATE--- and ---END CERTIFICATE---
  5. Paste the SAML 2.0 Endpoint value into the SSO Entry Point text field.
    Google15.png
  6. Optionally, if you wish to redirect your users to a specific URL when they log out of Emtrain, enter that URL in the SSO Logout Redirect URL text field. If this field is left blank, users will be redirected to an Emtrain Logged Out page upon logging out.
  7. Select the Save button to finalize the integration.

Testing SSO

  1. 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.
  2. 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.
  3. 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.
  4. 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.
    Google16.png
  5. Upon authenticating, the user should be logged into Emtrain as their test user.

How Users Log into Emtrain

Be sure to assign the Emtrain app to all users via Google. We recommend working with your IT team to assign access just before you deploy training (fewer than 12 hours prior) to prevent users from exploring Emtrain too soon.

As long as users are signed into your SSO, they can access Emtrain:

  • Through the Emtrain tile in your Single Sign-On access panel.
  • Via links in notification emails.
  • From your account URL.

If a user isn’t yet signed into SSO, they’ll be redirected to your SSO login.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request