We've looked at many different ways to create live streaming experiences with Amazon Interactive Video Service (Amazon IVS) here on this blog, but all of those examples so far have focused on public channels that can be viewed by anyone without any playback authorization to verify that the viewer is allowed to view the live stream. Many live streaming user generated content (UGC) platforms do not require any authorization to view a stream, but there are use cases where we want to limit our stream viewers to a subset of our audience. For example, maybe our content creators want to charge a subscription for the content that they produce. Or, perhaps there are licensing limitations to the stream content that prohibit distribution to certain demographics or geographic locations. To address use cases where the platform must enforce playback authorization, Amazon IVS supports private channels. These channels will restrict playback to viewers who have obtained a token that is signed with a private key and verified with a public key. In this post, we'll look at how to enable playback authorization, create a playback key pair, generate a token, and play a private stream. Creating a Private Channel The first step in this workflow is to create a private channel. Creating a private channel is very similar to creating a public channel - the only difference is a single setting when creating the channel to enable playback authorization. We can enable playback authorization via the , via the AWS CLI, or via any of the AWS SDKs. Amazon IVS Console Let's start by looking at how to create a private channel via the Amazon IVS Console. At the list of channels in the console, click . Create channel On the page, enter a channel name (#1), select (#2), and turn on (#3). Create channel Custom configuration Enable token-authorization requirement for video playback If you prefer to use the CLI to create a channel, you can add the option. --authorized $ aws ivs create-channel --name demo-private-channel --latency-mode LOW --type STANDARD --authorized In reality, you're probably going to use the AWS SDK to create your user's channels. In this case, you can refer to the AWS SDK documentation for your favorite language to determine the appropriate argument to set for playback. For example, here are the for for the AWS SDK for JavaScript v3 which state that we can set a boolean property when creating a channel. authorized docs CreateChannelCommandInput authorized Now that we have enabled playback authorization, if we were to broadcast to the channel and try to view the live playback without generating and passing a playback token, we will receive a playback error. Here's an example of playback using the Amazon IVS player SDK where we have added an listener to capture playback errors. ERROR const streamUrl = '[private channel Playback Url]'; const ivsPlayer = IVSPlayer.create(); ivsPlayer.attachHTMLVideoElement(document.getElementById('video-player')); ivsPlayer.load(streamUrl); ivsPlayer.play(); ivsPlayer.addEventListener(IVSPlayer.PlayerEventType.ERROR, (err) => { console.log(err); }); Running this in a browser when pointed at a private channel will result in the following error logged to the console. { "type": "ErrorAuthorization", "code": 7, "source": "MasterPlaylist", "message": "invalid_playback_auth_token" } This confirms that our channel is indeed private, and requires a to be generated and passed along with the to authorize playback. token Playback Url Creating a Playback Key Before we can generate a playback token, we will need to create a private/public key pair and upload it to the Amazon IVS console. This key pair will be used to generate a token that is signed with the private key, and verified with the public key, to authorize playback. JWT To manage Playback keys with the Amazon IVS Console, select in the left navigation sidebar. Playback keys We can either create a key with the console, or manually with OpenSSL offline on our local machine. To create a key pair directly in the console. For this, click on . Create playback key Give the key a name, and click . Create The public key of this pair is saved to your AWS account and will be used to verify any playback requests that contain a token signed with the private key. When using the Amazon IVS Console to generate a key pair, the private key is immediately downloaded to your machine and is . not saved in the console or available for further download Creating a Key Pair Offline If you'd prefer to create your own key pair, you can do that offline and then import the public key into the Amazon IVS console. Here's an example of creating a key pair with OpenSSL. $ openssl ecparam -name secp384r1 -genkey -noout -out demo-private-channel-private-key-1.pem $ openssl ec -in demo-private-channel-private-key-1.pem -pubout -out demo-private-channel-public-key-1.pem To import the public key, click on on the list page. Import Playback key Give the imported key a name, and browse for the key file (or paste the key file contents). public public This can also be done via the AWS CLI: $ aws ivs \ import-playback-key-pair \ --name demo-private-channel-playback-key-1 \ --public-key-material "`cat /path/to/your/public-key.pem`" Or via the AWS SDK ( for JavaScript example). docs Private Channel Playback Now that we have created a private channel and a playback key pair, we are ready to generate signed playback authorization tokens. In your application, your business logic will dictate which users should be granted an authorization token. As mentioned above, maybe your application logic will first check that the user is a valid subscriber to the channel by querying a database. Or, in the case of geo restrictions, maybe you'll have to look up the IP address of the viewer to make sure it is associate with a region that is able to view the stream. The exact implementation will vary, but once you determine whether the viewer is indeed authorized to view the stream, you can proceed with the token generation method described below. Token generation will differ based on the language you're using on the backend. Refer to the for details on the requirements. Heads Up: user guide To generate a token with Node.js, we can use the library ( ). This library will simplify the process and allow us to sign our payload with the signing algorithm as required by Amazon IVS. Our payload must contain the , an to limit playback to a specific domain (or for all domains), and a token expiration timestamp. To sign the payload, we'll format it as below and use the private key that we created and imported above. jsonwebtoken docs SHA-384 Channel ARN access-control-origin * The token is used to start playback on a private channel, so the expiration period only applies to the time between token generation and playback start. It does not relate to the amount of time the user can play a given stream. Once playback is authorized, it can continue until the user disconnects or reloads the web page. Note: Here's one way to generate a token on the backend (via a microservice or serverless application) using Node.js. import jwt from "jsonwebtoken"; const getToken = () => { const privateChannelArn = process.env.DEMO_PRIVATE_CHANNEL_ARN; // private channel ARN const privateChannelPrivateKey = process.env.DEMO_PRIVATE_CHANNEL_PRIVATE_KEY; // playback private key const payload = { "aws:channel-arn": privateChannelArn, "aws:access-control-allow-origin": "*", "exp": Date.now() + (60 * 1000), // expires in 1 minute }; const token = jwt.sign(payload, privateChannelPrivateKey, { algorithm: 'ES384' }); return token; } In our frontend, we can retrieve the token from the backend and append it to the private channel's . In the example below, I've trunacted the Playback Url ( ) for brevity. Playback Url streamUrl const streamUrl = `https://[truncated].m3u8?token=${token}` const ivsPlayer = IVSPlayer.create(); ivsPlayer.attachHTMLVideoElement(document.getElementById('video-player')); ivsPlayer.load(streamUrl); ivsPlayer.play(); Summary In this post we learned how to create private channels, create and import playback keypairs, and generate a JWT token for playback authorization. To learn more about private channels, refer to the . user guide
