Secure video playback

Mux Playback IDs have two types: public and signed. Public playback URLs can be watched anywhere, any time. This means that public playback URLs can be embedded on other sites. For example, a user could "View Source," find the m3u8 URL, and publish it somewhere else (or post it to Reddit, or email it to a friend).

If this is not what you want, use a signed URL. Signed URLs are signed server-side by your application and are only playable for a short time.

1Create an Asset or Live Stream with a "signed" playback policy

A Mux Video Asset or Live Stream can have multiple playback IDs, each with a playback policy that is public or signed. The playback policy can be specified when creating a new Asset, creating a new Live Stream or it can be added after the fact via the playback policy API.

copy
// POST https://api.mux.com/video/assets
{
  "input": "https://storage.googleapis.com/muxdemofiles/mux-video-intro.mp4",
  "playback_policy": "signed"
}  

See Create a playback IDAPI to learn how to add a new playback ID to an existing Asset or Live Stream.

2Create a signing key

Signing keys can be managed (created, deleted, listed) either from the dashboard or via the Mux Video API. When creating a new signing key, the API will generate a 2048-bit RSA key-pair and return the private key and a generated key-id; the public key will be stored at Mux to validate signed tokens. Store the private-key in a secure manner.

Signing keys are created and deleted independently of Assets. You probably only need one signing key active at a time, but you can create multiple to enable key rotation, creating a new key and deleting the old only after any existing signed URLs have expired.

See Create a URL signing keyAPI for full documentation.

copy
// POST https://api.mux.com/video/v1/signing-keys
{
  "data": {
    "private_key": "(base64-encoded PEM file with private key)",
    "id": "(unique signing-key identifier)",
    "created_at": "(UNIX Epoch seconds)”
  }
}  

3Generate a JSON Web Token

All signed requests will have a JWT with at least the following standard claims:

The Thumbnail API accepts several options to control image selection and transformations.

For playback-id’s that use a public policy, the thumbnail options are supplied as query parameters on the request URL.

For playback-id’s that use a signed policy, the thumbnail options must be specified in the JWT claims when using signed URLs. This ensures that the thumbnail options are not altered, such as changing the timestamp or the dimensions of the thumbnail image. For example, if you uploaded a 4K video and wanted to restrict a thumbnail to a width of 600 pixels and a specific timestamp, then simply include the width and time keys in the JWT claims.

Expiration time

Expiration time should be at least the duration of the Asset or the expected duration of the Live Stream. When the signed URL expires, the URL will no longer be playable, even if playback has already started. Make sure you set the expiration to be sufficiently in the future so that users do not experience an interruption in playback.

Your application should consider cases where the user loads a video, leaves your application, then comes back later at some time in the future and tries to play the video again. You will likely want to detect this behavior and make sure you fetch a new signed URL to make sure playback is able to start.

4Signing the JWT

The steps can be summarized as:

1. Load the private key used for signing
2. Assemble the claims (sub, exp, kid, aud, etc) in a map
3. Encode and sign the JWT using the claims map and private key and the RS256 algo.

There are dozens of software libraries for creating & reading JWTs. Whether you’re writing in Go, Elixir, Ruby, or a dozen other languages, don’t fret, there’s probably a JWT library that you can rely on.

// We've created some helper functions for Node to make your signing-life easier
const { JWT } = require('@mux/mux-node');

const playbackId = 'your-asset-playback-id';

// Set some base options we can use for a few different signing types
let baseOptions = {
  keyId: 'your-key-id',
  keySecret: 'your-key-secret',
};

const token = JWT.sign(playbackId, { ...baseOptions, type: 'video' });

// Now the signed playback url should look like this:
// https://stream.mux.com/${playbackId}.m3u8?token=${token}

// If you wanted to pass in params for something like a gif, use the
// params key in the options object
const gifToken = JWT.sign(playbackId, {
  ...baseOptions,
  type: 'gif',
  params: { time: 10 },
})

// https://image.mux.com/${playbackId}/animated.gif?token=${gifToken}  

5Include the JWT in the media URL

Supply the JWT in the resource URL using the ‘token’ query parameter. The Mux Video service will enforce the inspect and validate the JWT to make sure the request is allowed.

Video URL example:

copy
https://stream.mux.com/{playback-id}.m3u8?token={JWT}  

Thumbnail options are supplied as query parameters when using a public policy. When using a signed policy, the thumbnail options must be specified as claims in the JWT following the same naming conventions as with query parameters.

Thumbnail URL example:

copy
https://image.mux.com/{playback-id}/thumbnail.{format}?token={JWT}  

Note on query parameters after signing

When you're signing a URL, you're signing the params for that URL as well. After the params are signed for a playback ID, the resulting signed URL should only contain the token param. This is important because leaving the parameters in the URL would both:

• expose more information about the underlying asset than you may want
• result in an incorrect signature since the extraneous params would alter the URL.

Example:

Let's say we're taking the following public example and making a signed URL:

• https://image.mux.com/{public_playback_id}/thumbnail.jpg?time=25

Generate a signed url with {time: 25} in the claims body. Using the helper example we wrote above, this would look like:

• sign(signedPlaybackId, { ...requiredTokenOptions, params: { time: 25 } })

Correct Signed URL:

• https://image.mux.com/{signed_playback_id}/thumbnail.jpg?token={token}

Bad Signed URL:

• https://image.mux.com/{signed_playback_id}/thumbnail.jpg?time=25&token={token}

Including query params in the token also applies to playback modifiers like default_subtitles_lang, redundant_streams and roku_trick_play. The jwt claims body must include the extra param:

copy
{
  "sub": "{PLAYBACK_ID}",
  "aud": "{AUDIENCE_TYPE}",
  "exp": "{EXPIRATION_TIME}",
  "redundant_streams": true
}  

Passing custom parameters to a signed token

With signed URLs, you can pass extra parameters via a custom key in the claims body like the example above.

This may be useful in order to identify bad actors that share signed URLs in an unauthorized way outside of your application. If you find out that a signed URL gets shared then you can decode the params and trace it back to the user who shared it. When including extra params like this, be sure to respect the following guidelines:

• Do NOT under any circumstances include personally identifiable information (PII) like a name or email address.
• Put your custom params nested inside the "custom" key.

copy
{
  "sub": "{PLAYBACK_ID}",
  "aud": "{AUDIENCE_TYPE}",
  "exp": "{EXPIRATION_TIME}",
  "custom": {
    "session_id": "xxxx-123"
  }
}