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

Integrating the Video Platform into Shibboleth with SAML

Avatar
YuJa Product Support
  • Updated

Shibboleth is a free and open-source product that provides a federated identity solution to connect users to applications, both within and outside institutions. The Video Platform's flexible SSO Module Provider framework is designed to support a wide variety of identity solutions, enabling full integration of Shibboleth into your infrastructure in a few simple steps.

Overview

This document is intended to guide users on how to integrate their institution's Shibboleth IDP server as an SSO system to log users into the Video Platform (“Service Provider”) (SP) using the SAML 2.0 protocol. Once configured properly, users should be able to perform an SP-initiated login on the Video Platform side, be redirected to the Identity Provider (IDP) and prompted for credentials, get successfully authenticated, then redirected back to the Video Platform where they will be signed in as a user.

Shibboleth Setup

Setup involves creating the SP metadata for the Video Platform and adding it as an SP metadata provider for the Shibboleth IDP. Then configuring things on the Video Platform side to communicate with the IDP will allow you to test and activate the new SSO system.

For instructions on Building the SP Metadata click here. 

 

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 the SP Metadata

  1. Navigate to https://www.samltool.com/sp_metadata.php.
  2. Enter the following parameters:

    Parameter

    Value

    EntityId

    https://<organization>.yuja.com

    Attribute Consume Service Endpoint

    (HTTP-POST)

    https://<organization>.yuja.com/D/SamlReceiveResponse

    NameId Format

    urn:oasis:names:tc:SAML:1.1:nameid-format:email

    AuthnRequestsSigned

    False

    WantAssertionsSigned

    True
  3. Leave the rest of the fields empty then click BUILD SP METADATA.
  4. Copy the text in the SP Metadata text field.
  5. Open any text editor. Paste the copied text and save it as a .xml file. Save the .xml file in a convenient location, as it will be required in the next step.

Shibboleth IDP Configuration

  1. In your Shibboleth IDP directory, open %IDP_HOME%/conf/metadata-providers.xml in any text editor.
  2. Inside the <MetadataProvider> element with xsi:type=”ChainingMetadataProvider”, add the following element where <someId> is replaced by any appropriate identifier string: <MetadataProvider id="<someId>"  xsi:type="FilesystemMetadataProvider"  metadataFile="C:\path\to\YuJa\metadata" />
  3. Ensure the IDP releases the following attributes to the Video Platform in the SAML response:
      • Principal Name (i.e. Username)
      • First Name
      • Last Name
      • Email
      • Role

    The attribute names used in the SAML response are needed by the Video Platform to provision and create users. Provide these values to the Video Platform after configuration.

    The Role claim 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.

     

  4. The Video Platform does not encrypt Authentication Requests, and does not recognize encrypted responses. Thus, the IDP must be configured to make encryption optional:
    • Open %IDP_HOME%/conf/idp.properties in any text editor.
    • If required, add the following line to the properties file: idp.encryption.optional = true
  5. Open the IDP metadata file, located in %IDP_HOME%/metadata/idp-metadata.xml. This will be needed to configure the Video Platform side. 

Video Platform Side SAML Configuration

Once the IDP has been configured, the SP must be configured to communicate with the IDP. Some of the configuration parameters are found in the IDP metadata. Follow the steps below to integrate Shibboleth with the Video Platform.

  1. Login to your Video Platform Zone as an IT Manager and navigate to Admin Panel → Integrations.
  2. Under Select an API to configure, choose SSO – Shibboleth (SAML).
  3. Enter the following information. When first creating the SSO system, you can leave the User Provisioning fields blank so that you can first perform a Test SAML Login to retrieve the values. You can always enter the values later and save your configuration.

    Attribute

    Required?

    Description

    Shibboleth SSO URL

    Yes

    The URL used for SSO. This is where the Video Platform will send AuthnRequest tokens.

    Found in the Shibboleth IDP metadata under:

    <IDPSSODescriptor> → <SingleSignOnService>

    Locate the one with the “SAML:2.0:bindings:HTTP-Redirect” binding, and use the “Location” attribute of that tag.

    For example: https://idp.example.com/idp/profile/SAML2/Redirect/SSO

    Name ID Format

    Yes

    The format to be used by the SP and IDP when communicating about a subject.

    Found in Shibboleth 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

    Currently not supported

    Leave this value blank.

    Shibboleth Signing Certificate Thumbprint

    No, but strongly

    recommended

    The unique fingerprint of the IDP’s certificate used when signing SAML responses.

    The thumbprint is not explicitly located in the metadata, but the certificate used to sign either the SAMLResponse or the Assertion is.

    See the section titled How to Derive the Fingerprint of a Certificate of this document for more details.

    For example: 7j2mka9cfe2d09j23eefe01442f6a49d1222391f

    Given Name Attribute

    No

    The name of the attribute in the SAML Response** describing the user's given name (i.e. first name).

    For example: urn:oid:2.5.4.42

    Family Name Attribute

    No

    The name of the attribute in the SAML Response** describing the user's family name (i.e. last name, surname). - For example: urn:oid:2.5.4.4

    Email Attribute

    No

    The name of the attribute in the SAML Response** describing the user's email address.

    For example: urn:oid:0.9.2342.19200300.100.1.3

    Role Attribute

    No

    The name of the attribute in the SAML Response** describing the user's role.

    For example: urn:oid:1.3.6.1.4.1.5923.1.1.1.5

    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 Instructor,Teacher,TA

    Automatically sync data on user login

    No

    If enabled, whenever a user logs in via Shibboleth, their basic information will be updated based on the data received in the SAML response token.

     

    To obtain a sample SAML Response, first follow the instructions under Useful Chrome Plugin for Debugging SAML Tokens in the Additional Tools section of this document. After installing the plugin, perform a Test SAML Login as described in step 7 of this this section, making sure the plugin is open before logging in so that it can read the SAML Response token.
  4. Click Create.
  5. Click OK in the confirmation dialog popup.
  6. If required, you can update the configuration settings if you made a mistake. Simply click Save to keep the changes.
  7. To test if the configuration is correct, click Test SAML Login. This should open a new tab and navigate to your Shibboleth server, prompting a login.
  8. Enter valid login credentials and Login.
  9. You should be redirected back to the Video Platform, signed 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 – Shibboleth (SAML).
  10. Once you have verified that the Shibboleth SSO works, you can choose to activate the new authentication scheme for your institution. 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. To do so, click Activate, then click OK in the confirmation dialog. 

Dual Integration with LTI

If your organization has enabled both LTI and SAML SSO access, then you have the choice to link the two integrations. By default, a user logging in via both LTI and SAML receives a separate Video Platform account for each login. If your LTI provider is configured to authenticate users via their SAML credentials, it is possible to link the two accounts as the LTI provider will give the Video Platform a unique identifier for the user in the SAML system.

  1. Configure your LMS to pass a custom LTI parameter called lis_person_sourcedid which contains the cross-matching SSO value.  This can be an email, employee ID, or another field. The Video Platform will make use of this feature to link the two login techniques 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. For example, if the unique identifier is the user's sAMAccountName, then the linkage attribute might be 'urn:oid:1.2.840.113556.1.4.221'. Refer to your IDP attribute configuration for a list of the possible values.
  3. Enter this value into the Linkage Attribute
  4. Click Save.
  5. Now, when logging in for the first time via Shibboleth (SAML), the Video Platform system will search for a link with an LTI account using the value of the linkage attribute. If found, the Shibboleth-linked account will be linked to the existing LTI-linked account.  Otherwise, a new account will be provisioned as normal.  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 (https://<organization>.yuja.com) and press Login. This should redirect the user to the Shibboleth IDP server’s login page.
  2. Enter valid credentials and sign in.
  3. Once authenticated, the user should be redirected back to the Video Platform.

Additional Tools  

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, navigate 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. The fingerprint should be an array of 20 bytes for “sha1”.

Useful Chrome Plugin for Debugging SAML Tokens

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