Enabling Secure Token Authentication with Dolby.io Millicast Streaming

Dolby.io Millicast provides the WebRTC infrastructure and expertise to deliver content to tens of thousands of viewers at real-time speeds, creating an engaging environment for interactivity and communication. Whilst the platform has the capacity to deliver content to large audiences, it doesn’t necessarily mean you want to. Hence, in this guide, we will be outlining how to set up secure streams where account owners can control who can publish or access content via their stream. 

Why Secure Viewers and Broadcasters with an Access Token?

Setting up a secure stream requires an extra verification step on the viewer’s part in the form of a secure subscriber token and an extra step on the streamer’s part in the form of a secure publishing token. These secure tokens allow the account holder to add restrictions to the kinds of domains, IPs, and countries users might be interacting with the stream from, as well as when people can publish to or view the stream. It is best practice to utilize secure access tokens for any public-facing or production environment as a way of protecting your credentials from exposure. Because Dolby.io Millicast is billed by bandwidth, stolen credentials could potentially be used at the expense of the account holder. 

Depending on your use case you might be interested in creating a Publisher token and/or creating a Subscriber token. Publisher Tokens are useful for controlling the origins, users, and countries that can stream through your account. Alternatively, Subscriber tokens are used for controlling the origins, users, and countries that can view streams published through your account. Depending on the product or tool you are building you might only need to opt for one, the other, or both.

There are two methods for creating, managing, and deleting these secure access tokens that we’ll outline below.

Method 1: Creating Secure Access Tokens Through the Dashboard

To create a secure token through the Dolby.io Millicast Dashboard, log into your Millicast account and navigate to the Live Broadcast page where you will see a list of your Publisher tokens. If you are interested in creating a secure subscriber token you can instead navigate to Subscribe Tokens where you will see a list of your Subscriber tokens. 

Click the + symbol adjacent to the Stream Token or Subscribe Token header to add a new token of that type. This will open the Add Token page where you have a number of useful parameters to adjust based on your stream use case. On the Basic tab make sure to set Secure Viewer to true by clicking on the lock icon.

Note: You can use the Temporary Token parameter towards the bottom of the Add Token page, which allows you to set a time to expiration. By creating a temporary token, the potential fallout if the token is exposed is limited, providing only a set window of opportunity for use.

Under the Advanced tab there are a number of settings to adjust depending on your use case:

• Allowed Origins: This input expects a list of string values, representing the domains and or subdomains, in which to restrict where a user publishes from and or where a user views from. eg. mydomain.com
• Allowed IP Addresses: Similar to allowed origins, allowed IPs is an array of IP addresses a user can view or broadcast from. eg. 777.888.99.001
• Cluster Region: This feature allows the token creator to specify a server region and can be useful depending on the use case. For use cases involving medical or sensitive data, it may be more advisable to use a cluster within the country in which you operate. eg. San Francisco – Legacy
• Geo-Blocking: By clicking on the Geo-blocking button you can add countries to either your allow countries list or your deny countries list. This feature can be useful if you are streaming content that needs to be location locked such as a sports game or a news broadcast. 

With your settings adjusted press the OK button to create your new secure token. To confirm the token is secure, click on it to open the token details page where the Secure Viewer should have a lock symbol next to it. Stored in the API tab is your publisher token.

You can test out your secure stream by broadcasting from the dashboard. To join the now secure stream you’ll need to create a Subscribe Token associated with that stream name and append the token to the end of your stream URL.

https://viewer.millicast.com?streamId=<YOUR_ACCOUNT_ID>/<YOUR_STREAM_NAME>&token=<SUBSCRIBE_TOKEN>

Preventing Stream Sharing

One downside of creating tokens through the dashboard is that although they are secured with a token, the token can still be copied and shared with others, even if the link is embedded in an <iframe>. To combat this, it is recommended that you use the Allowed IP Addresses parameter to lock tokens to particular users. Depending on the number of users you have, locking each token to a particular IP via the dashboard can be very inefficient. Rather than use the dashboard, you should refer to method 2 below for a programmatic solution.  

Method 2: Creating a Secure Access Token Programmatically 

Creating a secure token through the dashboard is fine for testing, however, for customer-facing use cases, the programmatic solution is more elegant. Luckily for us, the workflow is almost identical, bar the addition of the API Secret Key. The API Secret Key is required for all programmatic token actions and can be found in the Account portal under the Security tab.

Note: It is important that you don’t expose the API Secret in production as this jeopardizes the security of all your tokens. The best practice is to create a Token Server, where you can handle all token requests and serve temporary access tokens to your production environment.

With the API Secret Key, we can now programmatically create tokens. Before we do this, it is worth understanding the five kinds of operations we can do on each the Publisher Token and the Subscribe Token:

1. Create Token: Creates a new token for either publishing or subscribing.
2. Delete Token: Deletes token specified by the tokens id.
3. List Tokens:   List all tokens with specific sorting and pagination. 
4. Read Token:     Gets token specified by token id.
5. Update Token: Updates token stream information as well as updating the token itself.

So when we want to serve the user a token that allows them to view a secure stream we Create Token, where we can use the same parameters that we specified when creating on the dashboard. The JavaScript example below highlights how this feature might be formatted for creating a publisher token, including parameters such as allowedOrigins, allowedIPs, allowedCountries, expires, etc. 

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_API_SECRET'
  },
  body: JSON.stringify({
    streams: [{isRegex: false, streamName: 'Stream_Name'}],
    allowedOrigins: ['www.mydomain.com'],
    allowedIpAddresses: ['777.888.99.001'],
    allowedCountries: ['AUSTRALIA'],
    subscribeRequiresAuth: false,
    record: false,
    multisource: false,
    expires: 3600,
    label: 'EXAMPLE_TOKEN',
    originCluster: 'San Francisco - Legacy'
  })
};
 
fetch('https://api.millicast.com/api/publish_token', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

If you are interested in a deeper dive on the parameters you can alter, or want code examples in different languages, check out the Dolby.io Millicast Token API reference.

If the request is formatted and authenticated correctly the server will return a JSON object with your new token stored under data:

{ 
  "status":"success", 
  "data":{ 
    "Id":44, 
    "Label":"allow_me", 
    "Token":"YOUR SUBSCRIBER TOKEN", 
    "addedOn":"2020-05-22T16:00:06.269683Z", 
    "expiresOn":null, 
    "isActive":true, 
    "streams":[{"streamName":"unique2445","isRegex":false}] 
  } 
}

Preventing Stream Sharing

As mentioned in Method 1, if users can find the subscriber token they can share the secure stream. To prevent stream sharing, you can lock the token to a user’s IP address with the Allowed IP Addresses parameter. For an example of how to implement locking a token to a user’s IP address, check out this guide here.

What’s Next with Dolby.io Millicast?

It is important to carefully consider how you manage your Dolby.io Millicast tokens and how you secure your streams against misuse and bad actors. Best practice dictates that you should use secure temporary tokens whenever possible and carefully manage traffic on your streams. If you are interested in learning about different types of streams you can set up, check out this guide for building a Livestream viewer in JavaScript or this tutorial showing how you can publish streams from within the Unreal Engine 5, using the Dolby.io Millicast publisher plugin. 

Feedback or Questions? Reach out to the team on Twitter, LinkedIn, or via our support desk.