Azure Media Services work with Axinom DRM License Service. Learn the steps of integrating these services and setting everything up.

Integrating Azure Media Services

Overview

This guide describes how to integrate Azure Media Services (AMS) v3 with Axinom DRM License Service. The following topics are covered:

  • Setting up a Postman API client to use Azure Media Services v3 REST API collection.

  • Uploading video content through the Azure Portal.

  • Configuring dynamic encryption with multi-DRM (PlayReady and Widevine) with user-defined Content Keys & Content Key IDs.

  • Generating the JSON Web Token (JWT) authorization token required by the Axinom DRM License Service.

  • Configuring Axinom DRM License Service license acquisition URL for Azure Media Player (AMP).

  • Setting a custom authorization token header for Azure Media Player (AMP).

Prerequisites

The following are the prerequisites for integrating AMS:

  1. Azure Media Services account.

    You can use a trial Azure subscription to create an Azure Media Services account.

  2. Service Fact Sheet and documentation provided by Axinom.

    Contact Axinom to get access to the documentation portal.

Setting up the Postman API Client

This guide uses the Postman API client to access Azure Media Service v3 REST API. The Postman API client is used as Microsoft provides a ready-to-use API configuration package for it. However, any REST API client can be used to access the Azure Media Service v3 REST API. The reference for Azure Media Services v3 REST API can be found here.

Note
Microsoft also provides a .NET SDK and a Java SDK for Azure Media Services integration for those who do not want to use the REST API.
  1. Retrieve the AMS REST API credentials from Azure.

    1. Use Azure Cloud Shell in the Azure Portal or install Azure CLI locally to execute the command.

      More details about "Azure CLI" can be found here.

    2. Execute the following command in the Azure shell.

       az ams account sp create --account-name <ams account name> --resource-group <resource group name>

      In the above command, <ams account name> is the Azure Media Services account name and <resource group name> is the Azure resource group name where the Azure Media Services account was created under.

      If the command completed successfully, the resulting structure is similar to the following:

      {
        "AadClientId": "00000000-0000-0000-0000-000000000000",
        "AadEndpoint": "https://login.microsoftonline.com",
        "AadSecret": "00000000-0000-0000-0000-000000000000",
        "AadTenantId": "00000000-0000-0000-0000-000000000000",
        "AccountName": "amsaccount",
        "ArmAadAudience": "https://management.core.windows.net/",
        "ArmEndpoint": "https://management.azure.com/",
        "Region": "West US 2",
        "ResourceGroup": "amsResourceGroup",
        "SubscriptionId": "00000000-0000-0000-0000-000000000000"
      }
  2. Install the Postman API client.

  3. Download and extract the AMS REST API collection provided by Microsoft.

  4. Import the AMS REST API collection into Postman API client.

    1. Select FileImport (Ctrl+O).

    2. Select Import Folder tab.

      postman import
    3. Select Choose Folders.

    4. Select the Postman folder from the extracted archive.

      postman folder
  5. Set the Postman API client environment variables.

    1. Click the Manage Environments button.

      postman manage env
    2. Select Azure Media Service v3 Environment in the Postman API client.

      postman manage ams env
    3. In the "CURRENT VALUE" field, set the variables based on the above retrieved AMS API credentials.

      postman edit env

      The following table shows the fields that need to be set and the corresponding fields in the AMS REST API credentials:

      Postman API client variable field AMS REST API credentials field

      tenantId

      AadTenantId

      clientId

      AadClientId

      clientSecret

      AadSecret

      subscriptionId

      SubscriptionId

      accountName

      AccountName

      resourceGroupName

      ResourceGroup

      location

      Region

    4. Click Update.

  6. Select Azure Media Service v3 Environment as the environment from the environments dropdown menu.

    postman select env
  7. Get an authentication token for the REST API.

    1. Navigate to Media Services v3 (2018-07-01 GA)Step 1: Get AAD Auth TokenGet Azure AD Token for Service Principal Authentication request. (Depending on the API collection release you download, the version date "2018-07-01 GA" could be different).

      postman auth
    2. Select Send.

      If successful, you should get an HTTP response status code "200 OK".

Uploading Video Content

Video content can be uploaded using the Azure Portal, the AMS REST API or one of the AMS SDKs. While the use of AMS REST API or AMS SDKs can give more control to customize parameters, such as the asset name, description, etc., this guide uses the Azure Portal to upload and encode video content.

Uploading the Input Asset

The input asset is the video content in its original format. Based on the input asset, you can encode multiple output assets in different formats.

  1. Log in to the Azure Portal.

  2. Navigate to All Resources.

  3. Select the media service account from the list (The AMS account which was created at the beginning of this guide should be listed).

    ams msaccount
  4. Select Assets from the left menu.

    ams assets
  5. Select Upload.

    ams asset upload
  6. Select the folder icon to upload a video file from the local machine.

    upload video

Encoding the Input Asset

The input asset should be re-encoded using the "Content Adaptive Multiple Bitrate MP4" or the "Adaptive Streaming" preset. These are the only encoding presets that support dynamic encryption. After encoding, a new asset is created for which dynamic encryption can be applied. This newly encoded asset is referred to as the "Output Asset".

  1. Navigate back to the Assets list.

  2. Select the above uploaded input asset from the Assets list.

    ams input asset
  3. Click Encode.

    ams encode
  4. Choose "Content Adaptive Multiple Bitrate MP4" or "Adaptive Streaming" as the Encoding preset.

    encode video
  5. Click Create.

    Encoding could take some time to finish. Once it’s finished it shows up in the assets list.

Encrypting Video Content

In Azure Media Services v3, video content is encrypted based on configuration of a Streaming Locator which associates a Content Key with an output asset.

Creating a Streaming Locator is the same as Publish in the Azure Portal which creates a Streaming Locator internally. However, the default parameters are not suitable for integrating with Axinom DRM License Service. Therefore, a custom Streaming Locator needs to be created using the REST API or the AMS SDK, as the Azure Portal doesn’t have the option to change the parameters of a Streaming Locator.

Setting a Content Key

Content Key and Content Key ID must be explicitly set in the Streaming Locator and you must use the key seed specified in the Service Fact Sheet provided by Axinom to generate the Content Keys that match licenses returned by Axinom DRM License Service.

Axinom customers should retrieve content keys from "Axinom DRM Key Service" which can deliver Content Keys via "Widevine Common Encryption API", "CPIX", and "SPEKE" key exchange protocols. For more information on the "Widevine Common Encryption API" key exchange protocol, refer to WidevineContentKeyRequestExamples_ sample code.

Creating a Streaming Policy

A Streaming Policy is required to create a Streaming Locator for protected content. Streaming Policy shall also contain the license acquisition URL for the protected content. By creating a new Streaming Policy with a minimal configuration, you can avoid any additional encryption configurations that are not required for the Axinom DRM License Service. To use the Azure Media Player, it is important to set the license acquisition URL in the Streaming Policy.

  1. Set "Ax_MultiDrmStreamingPolicy" as the Streaming Policy name in the Postman API client environment variables.

    set policyname
  2. Navigate to Media Services v3 (2018-07-01 GA)Streaming Polices and LocatorsCreate a Streaming Policy (Secure Streaming) in the Postman API client.

  3. Replace the Postman API client request body as per the following example:

    {
      "properties": {
        "commonEncryptionCenc": {
          "enabledProtocols": {
            "download": false,
            "dash": true,
            "hls": false,
            "smoothStreaming": true
          },
          "contentKeys": {
            "defaultKey": {
              "label": "cencDefaultKey"
            }
          },
          "drm": {
            "playReady": {
              "customLicenseAcquisitionUrlTemplate": "https://drm-playready-licensing.axtest.net/AcquireLicense"
            },
            "widevine": {
              "customLicenseAcquisitionUrlTemplate": "https://drm-widevine-licensing.axtest.net/AcquireLicense"
            }
          }
        }
      }
    }
  4. Click Send. If successful, you should get an HTTP response status code "201 Created".

Creating a Streaming Locator

  1. Navigate back to the Assets list in the Azure Portal.

  2. Select the output asset from the Assets list.

  3. Get the output asset name from the Azure Portal.

    In the Azure Portal, the asset name is represented in the ID field as a UUID value.

    asset name
  4. Navigate to Media Services v3 (2018-07-01 GA)Streaming Polices and LocatorsCreate a Streaming Locator (secure - userDefined) in the Postman API client.

    create streamlocator
  5. Replace the Postman API client request body with the following example and fill in the fields marked with "<>":

    {
      "properties": {
        "assetName": "<output asset name>",
        "streamingPolicyName": "Ax_MultiDrmStreamingPolicy",
        "contentKeys": [
          {
            "LabelReferenceInStreamingPolicy":"cencDefaultKey",
            "Id": "<content key ID>",
            "Value": "<base64 encoded key>"
          }
        ]
      }
    }
  6. Click Send to create the Streaming Locator.

Getting the Asset Streaming Path

  1. Navigate to Media Services v3 (2018-07-01 GA)Streaming and LiveList StreamingEndpoints in the Postman API client.

    If successful, you should get an HTTP response status code "200 OK" with a JSON response.

  2. Get the Streaming endpoint host name under the "hostName", property in the JSON response.

    postman endpoint
  3. Navigate to Media Services v3 (2018-07-01 GA)Streaming Polices and LocatorsList Paths in the Postman API client.

    postman listpath
  4. Click Send to list the paths of a Streaming Locator.

    If successful, you should get an HTTP response status code "200 OK" with a response similar to the following:

    {
      "streamingPaths": [
        {
          "streamingProtocol": "Dash",
          "encryptionScheme": "CommonEncryptionCenc",
          "paths": [
            "/00000000-0000-0000-0000-000000000000/file_example_MP4.ism/manifest(format=mpd-time-csf,encryption=cenc)"
          ]
        }
      ],
      "downloadPaths": []
    }

A listed path is not complete without the Streaming endpoint host name. The complete content URL can be found by concatenating the above retrieved streaming endpoint host name and the streaming locator path. An example content path would look similar to this example: https://somename.streaming.media.azure.net/00000000-0000-0000-0000-000000000000/file_example_MP4.ism/manifest(format=mpd-time-csf,encryption=cenc)

Generating a JWT Authorization Token

Axinom DRM License Service requires a JWT authorization token to issue a license. This custom JWT authorization token uses an Axinom defined payload structure which is also referred to as "Entitlement Message" in the provided Axinom documentation. The JWT token must be generated from a custom developed authorization service that has access to the corresponding Content Key IDs.

The Content Key ID is required to generate an authorization token. Since the authorization token needs to be ready before loading a video, the Content Key ID needs to be retrieved to generate the authorization token.

There are multiple ways to obtain the Content Key ID. For example, the Content Key ID could be stored together with content metadata in a database or you can retrieve the Content Key ID from the DASH Media Presentation Description manifest file (.mpd).

Axinom customers can use the "Axinom DRM Key Service" to retrieve the Content Key ID from the database and generate the JWT authorization token with the required restrictions.

Furthermore, the Axinom DRM License Service requires the JWT authorization token to be under the custom HTTP header named X-AxDRM-Message when sending the license request. Different media players may have different ways to set custom HTTP headers. For Azure Media Player, please refer to the section Setting the Custom Authorization Header

The following C# sample code generates a JWT authorization token which is based on Entitlement Message v2. Please refer to the documentation provided by Axinom for a detailed description of the token’s structure.

Note
CommunicationKey and CommunicationKeyId are needed for signing the JWT token. They are available in the Service Fact Sheet provided by Axinom.
using System;
using System.IO;
using System.IdentityModel.Tokens.Jwt;
using Microsoft.IdentityModel.Tokens;

namespace Axinom.Drm.LicenseTokenGenerationExamples
{
    public class LicenseTokenGeneration
    {
        // Replace with Your 32-byte communication key.
        private const string CommunicationKeyAsBase64 = "<base64 encoded communication key>";

        // Replace with Your communication Key ID.
        private const string CommunicationKeyIdAsGuidString = "<communication key id>";

        private static void GenerateLicenseTokenFromCode()
        {
            var payload = new JwtPayload
            {
                { "version", 1 },
                { "com_key_id", CommunicationKeyIdAsGuidString },
                { "message", new
                    {
                        type = "entitlement_message",
                        version = 2,
                        content_keys_source = new
                        {
                            inline = new []
                            {
                                new
                                {
                                     id = "<content key ID>"
                                }
                            }
                        },
                    }
                }
            };

            var signedJwtToken = CreateJwtToken(payload);
        }
        private static string CreateJwtToken(JwtPayload payload)
        {
            var symmetricKey = Convert.FromBase64String(CommunicationKeyAsBase64);
            var credentials = new SigningCredentials(new SymmetricSecurityKey(symmetricKey), "HS256");
            var header = new JwtHeader(credentials);

            var token = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var tokenAsString = handler.WriteToken(token);

            return tokenAsString;
        }
    }
}

Customizing Azure Media Player

Azure Media Player (AMP) supports playback of DRM-protected content. When using Axinom DRM License Service, the following changes need to be made due to the design of AMP.

  1. Set a custom authentication token header name.

  2. Define a Streaming Policy with the custom license acquire URL.

Setting the Custom Authorization Header

As Axinom DRM License Service requires the JWT authorization token to be under the HTTP header named “X-AxDRM-Message”, the AMP requires a workaround to set the custom header.

The following Javascript needs to be in the web page hosting AMP before initializing the player:

AzureHtml5JS.KeySystem.WidevineCustomAuthorizationHeader = "X-AxDRM-Message"

The above Javascript is a short-term workaround while awaiting a permanent solution from Microsoft.

Setting the Custom License Acquisition URL

Azure Media Player uses the license acquisition URL defined in the content manifest file, where it cannot be set programmatically like other media players, such as "dash.js". Therefore, when using the AMP, the custom license acquisition URL must be set through a Streaming Policy.

The section Creating a Streaming Policy describes the steps to create a Streaming Policy with Axinom DRM License Service license acquisition URL. If that Streaming Policy ("Ax_MultiDrmStreamingPolicy") is used to create Streaming Locators for the content, no additional changes are needed. Otherwise, please follow the Creating a Streaming Policy and Creating a Streaming Locator sections.

Azure Media Player Sample Code

<html>

<head>
    <link href="//amp.azure.net/libs/amp/latest/skins/amp-default/azuremediaplayer.min.css" rel="stylesheet">
    <script src="//amp.azure.net/libs/amp/latest/azuremediaplayer.min.js"></script>
</head>

<body>
    <video id="azuremediaplayer" class="azuremediaplayer amp-default-skin amp-big-play-centered"> </video>

    <script>
        var amyOptions = {
            autoplay: true,
            controls: true
        };

        AzureHtml5JS.KeySystem.WidevineCustomAuthorizationHeader = "X-AxDRM-Message";

        var licenseToken = "<JWT authentication token>";

        var amyPlayer = amp("azuremediaplayer", amyOptions);

        amyPlayer.src(
            [
                {
                    src: "https://<Streaming endpoint host name>/<content streaming path>",
                    type: "application/dash+xml",
                    protectionInfo:
                        [
                            { type: "PlayReady", authenticationToken: licenseToken },
                            { type: "Widevine", authenticationToken: licenseToken },
                        ]
                },
            ]
        );
    </script>
</body>

</html>

The latest AMP documentation can be found here.

Revision History

Version Date Description

1.0

November 15, 2019

  • Initial version