English Español Français
Go to YuJa
  1. YuJa Help Center
  2. Lumina Video Platform
  3. Admin Panel
  4. SSO Platform Integration

Integrating Lumina into Shibboleth with SAML

Avatar
YuJa
  • 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. Lumina'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 Lumina using the SAML 2.0 protocol. Once configured properly, users should be able to perform an Service Provider (SP)-initiated login, be redirected to the Identity Provider (IDP) and prompted for credentials, get successfully authenticated, then redirected back to Lumina where they will be signed in as a user.

Shibboleth Setup

Setup involves creating the SP metadata for Lumina and adding it as an SP metadata provider for the Shibboleth IDP. Then configuring things on Lumina 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. 

Note: For some steps, <organization> is to be replaced by the wildcard DNS of the organization associated with Lumina. 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:emailAddress
    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 Lumina in the SAML response:
    • Principal Name (i.e. Username)
    • First Name
    • Last Name
    • Email

    • Role

      Note: The attribute names used in the SAML response are needed by Lumina to provision and create users. Provide these values to Lumina 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. Lumina 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 Lumina side. 

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

Shibboleth Guide.png
  1. Login to Lumina as an IT Manager and navigate to Admin Panel → Integrations.
  2. Under Select Integration, 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 Lumina 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.

    Note: 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 in the upper right corner. 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 Lumina, logged in as a new user. Log out of the new user account and log back in as an IT Manager, then navigate back to 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 Lumina 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 Lumina 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. Lumina 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 Lumina 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 Lumina 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 Lumina 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 Lumina.

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

Contact Support