Kaltura MediaSpace™ SSO Integration Guide

This guide describes how to implement single sign-on (SSO) in Kaltura MediaSpace™.

Understanding MediaSpace Authentication and Authorization

MediaSpace includes a low-level authentication mechanism. When a user attempts to access MediaSpace, MediaSpace checks whether the user is logged in. If the user is not logged in or the login is expired, the user is redirected to another URL. 

As part of the authentication mechanism, MediaSpace determines the user's application role following a successful login. The application role determines the MediaSpace actions that the user is authorized to do. To learn more about the MediaSpace application role, refer to the article Understanding Application Roles.

Understanding the SSO Gateway

In the SSO Gateway, an expired login causes the user to be redirected to the SSO Gateway’s login page. 

On the login page, the user logs into your user management system using your methodologies (you are responsible for writing the login code).

When a user logs in successfully, the login page generates a unique session key using a secret shared between the login page and MediaSpace (which you define for MediaSpace on the Configuration Management panel of the Kaltura MediaSpace Administration Area. Refer to Configuring SSO Gateway Authentication and Authorization in the Kaltura MediaSpace Setup Guide. The session key also securely encapsulates user information that is passed to MediaSpace.

After successfully logging into your system, the user is redirected to the MediaSpace authentication URL. The session key is passed as a URL parameter.

The MediaSpace authentication URL uses the secret to validate the session key. If the session key is valid, the MediaSpace authentication URL logs the user into MediaSpace. If the session key is not valid, the MediaSpace authentication URL redirects the user back to your login page.

Constructing the MediaSpace Authentication URL

In the SSO Gateway, the MediaSpace authentication URL logs in a user based on the customer user management's session key.  The following is the URL structure: pid.mediaspace.kaltura.com/user/authenticate/…

If you are setting the SSO Gateway for pid.mediaspace.kaltura.com (SaaS), mediaspace_domain would be ‘pid.mediaspace.kaltura.com’, and you do not need to use the (mediaspace_path) element.

The URL consists of the following elements:

• mediaspace_domain – the host name of the server that hosts your MediaSpace. Replace mediaspace_domain with the actual value in your environment.
• mediaspace_path – the URI of MediaSpace, if MediaSpace is installed under a subfolder. Replace mediaspace_path with the actual value in your environment. For example: http://mediaspace_domain/mediaspace_path/user/authenticate/sessionKey/{secure hash string}
• user – the controller that handles all user-related actions in MediaSpace. This element is hard coded.
• authenticate – the action within the user controller that handles the authentication. This element is hard coded.
• sessionKey – the parameter name in the URI for the secure hash string. This element is hard coded.
• secure hash string – the token that your login page creates and then passes to MediaSpace in the redirect URL.

Generating and Validating a Secure Hash String

A secure hash string is generated in your login page and is passed to MediaSpace in the redirect URL.

As part of the MediaSpace authentication process, MediaSpace validates the secure hash string received from the login page.

Sample Code for Generating a Secure Hash String

The following pseudo code demonstrates how to generate a secure hash string. 

   info = “userId;userRole;extraUserInfo;expiry;random”
   salt = {MEDIA_SPACE_LOGIN_SECRET}
   signature = sha1(salt+info)
   stringToHash = signature+”|”+info
   hashedString = base64_encode(stringToHash)

• userId – the ID of the user in your system as you use want it to be identified in Kaltura.
• userRole – the application role that you assign the user in MediaSpace.
• extraUserInfo –a key-value string in which pairing is specified using colons (:) and pairs are separated by commas (,). For example: extraUserInfo = "firstName:John,lastName:Doe,email:JohnDoe@mail.com"
• expiry – a Unix-timestamp after which the hashed string is no longer valid.
• random – a randomly generated number from 0-32000.
• MEDIA_SPACE_LOGIN_SECRET – the secret string shared by MediaSpace and the login page.

Sample Code for Validating a Secure Hash String

The following pseudo code demonstrates how the secure hash string passed in the sessionKey URL parameter is validated.

   decodedString = base64_decode(hashedString)
   separate decoded string by |, first part is signature second is  info
   salt = {MEDIA_SPACE_LOGIN_SECRET}
   validateSignature = sha1(salt, info)
   IF validateSignature = signature AND expiry < current unix time
       hash is valid
   ELSE
       hash is not valid

The validation code mirrors the token generation actions in reverse order:

1. The secure hash string is decoded from its base64 encoding.
2. The decoded string is separated into two parts: the signature and the information.
3. The code creates a signature using the information provided and the SSO secret, which is defined in the MediaSpace configuration.

If the signature created by the code matches the signature provided by the redirect URL and the expiration date did not pass, the secure hash string is valid and the user is successfully authenticated.

Configuring the SSO Gateway in MediaSpace

To learn how to configure the SSO Gateway for authentication and authorization in MediaSpace, refer to Configuring SSO Gateway Authentication and Authorization in the Kaltura MediaSpace Setup Guide.