Go to YuJa
  1. YuJa Help Center
  2. Enterprise Video Platform
  3. Admin Panel
  4. SSO Platform Integration

Integrating the Video Platform into Google Apps with SAML

Avatar
YuJa Product Support
  • Updated

Google Apps is a product that provides a federated identity solution to connect users to applications, both within and outside organizations. The Video Platform's flexible SSO Module Provider framework is designed to support a wide variety of identity solutions, enabling full integration of Google Apps into your infrastructure.

This document is intended to guide users on how to integrate the Video Platform as a Service Provider (SP) using Google as the Identity Provider (IDP). Once configured properly, users attempting to access Video Platform services will first be redirected to Google, prompting for credentials to log in. Once authenticated, the browser will again redirect back to the Video Platform, logged in as a new or existing user.

Setup

Setup involves creating a new SAML app in the Google admin console, then configuring things on the Video Platform side by integrating with Google as an IDP, testing and activating the SAML SSO for users of the institution.

For some steps, <organization> is to be replaced by the wildcard DNS of the organization associated with the Video Platform. As an example, for “https://hudson.yuja.com”, organization would be replaced by “hudson”.

 

Create a New SAML App for the Video Platform in the Google Admin Console

The steps to create a new SAML app are found at: https://support.google.com/a/answer/6087519?hl=en

Follow the instructions under the following sections: Set up your own SAML app, Turn on SSO to your new SAML app, and Verify SSO between Google Apps and your new SAML app, referring back to this document for specific instructions on certain steps.

Referencing the Section: Set up your own SAML app

  1. Download the IDP metadata. This will be used to configure things on the Video Platform side.
  2. Enter the following information:
    Parameter Value
    ACS URL https://<organization>.yuja.com/D/SamlReceiveResponse
    Entity ID https://<organization>.yuja.com
    Start URL **leave this blank**
    Name ID Basic Information, Primary Email
    Name ID Format Email
  3. Check Signed Response. This increases security when the SP and IDP are communicating.
  4. Create four mappings:
    Application Attribute Category User Field
    Given Name Basic Information First Name
    Family Name Basic Information Last Name
    Email Basic Information Email
    Role Job Details Job Title (or another appropriate field). This field is used to determine if users are provisioned as students (the default) or are given enhanced privileges (Instructor/IT Manager). The suggested values for this field are IT Manager and Instructor (for users you wish to have IT Manager/Instructor privileges respectively), but you can use existing/custom values (see below for a discussion of IT Manager and Instructor mapping) 

Video Platform Side SAML Configuration

  1. Go to https://<organization>.yuja.com and log in as an IT Manager for your institution.
  2. Navigate to the Admin Panel tab in the Main Menu.
  3. In the left sidebar, go to Integrations.
  4. In the dropdown under Select Integration, select SSO – Google Apps (SAML).
  5. Enter the following information listed in the following: 
    Attribute Required? Description
    Google SSO URL Yes

    The URL used for SSO. This is where the Video Platform will send AuthnRequest tokens.
    Found in Google IDP Metadata under: <IDPSSODescriptor> → <SingleSignOnService>
    as the “Location” attribute. Note that for the Video Platform, an HTTP-Redirect binding is used.

    For example https://accounts.google.com/o/saml2/idp?idpid=B05pakw7
    Name ID format Yes

    The format to be used by the SP and IDP when communicating about a subject.
    Found in Google IDP Metadata under:
    <IDPSSODescriptor> → <NameIDFormat>
    as the value of that tag. Note that, if available, emailAddress should be prioritized and used.

    For example: urn:oasis:names:tc:SAML:1.1:nameid- format:emailAddress
    Remote Logout URL Not Currently Supported Leave blank
    Google Signing Certificate Fingerprint No, but Strongly Recommended

    The unique fingerprint of the IDP’s certificate is used when signing SAML responses.
    See the section titled How to Derive the Fingerprint of a Certificate in this article for more details.

    For example: 7j2mka9cfe2d09j23eefe01442f6a49d1222391f
    Given Name Attribute No

    (Case Sensitive)Enter the following value: First Name

    This is the exact value used in the Application Attribute field when creating attribute mappings.
    Family Name Attribute No

    (Case Sensitive)Enter the following value: Last Name 

    This is the exact value used in the Application Attribute field when creating attribute mappings.
    Email Attribute No

    (Case Sensitive)Enter the following value: Email

    This is the exact value used in the Application Attribute field when creating attribute mappings.
    Role Attribute No

    (Case Sensitive)Enter the following value: Title

    This is the exact value used in the Application Attribute field when creating attribute mappings.
    IT Manager No A comma separated list of values can be used.
    If the value received in the Role Attribute matches any of these values, the user will be provisioned as an IT manager.
    For example: IT Manager
    Instructor No

    A comma-separated list of values can be used
    If the value received in the Role Attribute matches any of these values, the user will be provisioned as an instructor.

    For example: Instructor or Teacher, TA
    Automatically sync data on user login No If checked, whenever a user logs in via Google SAML Apps their basic information will be updated based on the data received in the SAML response.
  6. Click Create. In the confirmation dialog, click OK.
  7. If required, you can update the configuration settings if you made a mistake. Simply click
    Save to keep the changes.
  8. To test if the configuration was done correctly on both sides, click Test SAML Login. This should open a new tab and navigate to Google, prompting for credentials.
  9. Login using a valid Google account.
  10. After successfully logging in, you should be redirected back to the Video Platform, logged in as a new user.
    Logging in as a new user will log the original account out. Log out of the newly created account and log back in as an IT Manager. Then navigate back to the Admin Panel → Integrations → SSO – Google Apps (SAML).
  11. Once you have verified that the Google SAML Apps SSO works, you can choose to activate the new authentication scheme for your organization. To do so, click Activate, then click OK.
    Important Note: Only activate the new authentication scheme after successfully performing a test login and are ready to make it available for all users in your institution.

Dual Integration with LTI

If your organization has enabled both LMS Integration via LTI and also SSO access, then you have the choice to link the two integrations. We generally recommend this because it means that irrespective of whether your user's login via their LMS or their SSO, they will be presented with the same Video Platform account information. In contrast, if Dual Integration with LTI is not set up, a user who uses both their LMS and SSO with the Video Platform will be provisioned with two separate accounts which in many cases isn’t ideal. If your LTI provider within your LMS can be configured to provide the Video Platform with a unique identifier for the user in the SAML system, it is possible to link the two accounts.

  1. Configure your LMS to pass a custom LTI parameter to the Video Platform tool called lis_person_sourcedid which contains the cross-matching SSO value. This can be an email, employee ID, or another field. You may need to consult your LMS platform’s product documentation on how to set custom LTI parameters. The Video Platform will make use of this feature to link the two login methods to the same account.
  2. Obtain the specific attribute name used in the SAML Response token whose value corresponds to the unique identifier used by the LTI provider (in Step 1 above). For example, if the unique identifier is the user's email address, then the linkage attribute would be “email”. The possible values you can use are specifically those set in the Google Admin Console when configuring the SAML App. They are the names used in the Attribute Mapping step.
  3. Enter this value into the Linkage Attribute field. This textbox will only appear if your institution has enabled LTI access.
  4. Click Save.
  5. Now, when logging in for the first time via ADFS (SAML), the Video Platform system will search for a link with an LTI account using the value of the linkage attribute. If found, the SAML account will be linked to the existing account. Otherwise, a new account will be provisioned as normal.
  6. All logins past the first one will continue to link to the Video Platform account created or found on the first login.

Usage

Once both sides have been configured and the SAML SSO has been activated, it is easy to test and see if everything was done properly.

  1. Go to the organization’s Video Platform domain (i.e. https://<organization>.yuja.com) and press Login. This should redirect the user to the SSO server’s login page.
  2. Enter valid credentials and sign in.
  3. Once authenticated, the user should be redirected back to the Video Platform and the login was a success.

How to Derive the Fingerprint of a Certificate

The fingerprint of the IDP’s certificate is used for additional security purposes when the SP is verifying a SAML response from the IDP. To derive the certificate’s fingerprint, follow the instructions below:

  1. In the Google IDP metadata, extract the X509 certificate. This should be located under:
    <IDPSSODescriptor> → <KeyDescriptor use=”signing”> → <KeyInfo> → <X509Data> →
    <X509Certificate>
  2. Once you have the certificate, go to the following website: https://www.samltool.com/fingerprint.php
  3. Paste the certificate in the X509 cert textbox.
  4. Make sure sha1 is selected as the Algorithm.
  5. Click Calculate Fingerprint.
  6. Copy the Fingerprint value generated. This is the value used in the database. Note: The fingerprint should be an array of 20 bytes for sha1.

Useful Chrome Plugin for Debugging SAML Token

  1. If you are using Chrome as your web browser, you may want to install a useful SAML plugin at:
    https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace?hl=en
  2. Once installed, simply open the developer tools in the browser (F12) and click on the SAML tab. Now, when doing an SP-initiated login, the SAML tokens sent by the browser will be shown in detail. This tool can be very useful in debugging SAML requests and responses.

Related articles