Articles in this section

Restrict Vidyard players to your secure site using JSON Web Tokens

Avatar
Brendan O'Driscoll
  • Updated

Secure Vidyard players to your authenticated website

Important: this article requires some web development knowledge. The following steps are designed to be executed by a programmer.

You can secure Vidyard players to your authenticated web pages so that they can only be viewed by authorized audiences.

Check out this article if you want to secure your player to either Salesforce Chatter or your Vidyard Video Hub. 

If you want to secure your player to any other secure platform or internal site, this is the article for you! 

Overview

In Vidyard, you can secure individual players to a secure site using JSON Web Tokens (or JWTs). Any players you secure using this method will playback only on the secure pages that you set up. If a viewer attempts to view or embed the player on any other site, the player will not load. 

How does it work?

With this method, the web page where your secured Vidyard player is embedded will receive a unique JWT informing it that the viewer who loaded the page is authorized to view that video content.

The Vidyard player on the page will then check for that token. If the token is located,  the player will pass it to the Vidyard platform to validate. If validated, Vidyard will send the video to your player for playback. If it does not find a token, playback will be restricted. 

This is a great solution for any secure communication platforms or intranet-type sites that require authentication to access. Securing players in this way on your site ensures that the video content will not be shareable outside of the authenticated platform. 

How do I set it up?

To secure your players with JSON web token, you must set up the following: 

Step 1: Generate the JWT 

Create a backend application to listen for a call from your webpage requesting a JWT. This application must:

  1. Receive the request
  2. Generate a JWT based on the specifications listed in Step 2
  3. Post the generated token back to your web page

Step 2: Add a script to your webpage to request a JWT

Add a script on your webpage that will call the backend application requesting a JSON Web Token with the following specifications: 

Header:

{
 "alg": "HS256",
 "typ": "JWT"
}
  1. Copy the header of the token exactly as displayed 

Payload:

{
 "iss": "api_token",
 "exp": "1515164623",
 "role_id": "67890",
 "player_uuid": "X34Z4h6QcGHfJJ45VMJ6R5"
}
  1. In the above script, do not change "api_token"
  2. Replace "1515164623" with an expiry value in the form of POSIX time code (UNIX time). This value determines at what point in time Vidyard will no longer accept the JWT as valid.
    • While not required as part of the JWT payload, an expiry value is recommended as a security best practice. 
  3. Replace "67890" with your Role ID. 
    • To find the correct Role ID: from the Vidyard dashboard, click Group > Groups and Users > select Manage next to the appropriate group, then Options > Edit Permissions next to the role to which the API token belongs. 
    • The Role_id is the 5 or 6-digit numerical code at the end of the URLExample of where to find your Role ID in the Vidyard URL
    • For example: https://secure.vidyard.com/organizations/12345/groups/12345/roles/67890/edit
  4. Replace X34Z4h6QcGHfJJ45VMJ6R5 with the UUID of the player you want to load on this page. 
    • To find the player UUID, hover over the player in the Vidyard dashboard. Select Settings > General, then scroll down to the Player UUID field.

Signature:

HMACSHA256(
 base64UrlEncode(header) + "." +
 base64UrlEncode(payload),
 Vidyard API token
)
  1. Replace "Vidyard API token" with the API token for your group
    • To find the API token: first ensure you are in the correct group. If necessary, select Group > Change Group
    • Once in the correct group, select Group > Integrations
    • Insert the API token associated to the Role ID provided above.
      For example: if the ID provided is for the role "user", insert the User API Token.

Vidyard API tokens provided within the Integrations interface

Example:

This is an example of a possible script that you would write to make this request: 

<html>
<head>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
    <script type="text/javascript">
        function getJWT (uuid) {
            // function call to Web App to generate JWT
            return jwt;
        }
        function getEmbedCode(uuid) {
            var token = getJWT(uuid);
            var script=document.createElement('script');
            script.type='text/javascript';            
            script.id='vidyard_embed_code_'+uuid;
            script.src='https://play.vidyard.com/'+uuid+'.js?v=3.1&amp;type=inline&amp;jwt='+token;   
            return script;
        }
    </script>
</head>
<body>
    <div id="video_container"></div>
    <script type="text/javascript">
        window.onload = function() {
            $("#video_container").append(getEmbedCode('INSERT VIDYARD UUID HERE'));
        };
    </script>
</body>
</html>

Step 3: Build the player's embed code

Next, your page must receive the JWT, then build the embed code for your Vidyard player.

Note: If you want to test this out, you can access a test JSON Web Token here. 

  1. Set up your page to receive the JWT
  2. After the page receives the JWT, you can then trigger the Vidyard embed code. The embed code must be set up to dynamically load to include your new JWT.

A Vidyard inline embed code looks like this:

<script type="text/javascript" id="vidyard_embed_code_<UUID>" src="//play.vidyard.com/<UUID>.js?v=3.1.1&amp;type=inline"></script>

When you build a player's embed code, the page must load a standard javascript embed code while dynamically generating two variables: 

  • The UUID of the player you want to load:    
  • A query string which appends the received JWT to the embed code:    
    • Append &jwt=<variable for JWT>
    • Use the <variable for JWT> to load the received JWT. 

The completed embed code would look something like this: 

<script type="text/javascript" id="vidyard_embed_code_<UUID>" src="//play.vidyard.com/<UUID>.js?v=3.1.1&amp;type=inline&amp;jwt=<JSON Web Token>"></script>

Step 4: Enable JWT security on any players you wish to embed

  • Within the security settings for a Vidyard player, click Secure Platform Whitelist to enable JWT security for that player.Restrict to secure platforms option within the security settings of a Vidyard player
  • When a JWT secured player is loaded on your secured page, the Vidyard player will search for a JWT token. 
  • If the player does not find a JWT or the token is not valid, the player will not load your content. 
  • If the player finds a JWT, it will send the token to Vidyard for validation. If validated, the Vidyard platform will send the video to your player.
    Note: Players can be secured individually or as a default setting for all players within a group

Related articles