Protect your content with Media Services dynamic encryption

media services logo v3

Looking for Media Services v2 documentation?
Having trouble? See the Troubleshooting guide for solutions to issues with using Media Services.
Code samples can be found on the Samples page.

Use Azure Media Services to help secure your media from the time it leaves your computer all the way through storage, processing, and delivery. With Media Services, you can deliver your live and on-demand content encrypted dynamically with Advanced Encryption Standard (AES-128) or any of the three major digital rights management (DRM) systems: Microsoft PlayReady, Google Widevine, and Apple FairPlay. FairPlay Streaming is an Apple technology that is only available for video transferred over HTTP Live Streaming (HLS) on iOS devices, in Apple TV, and in Safari on macOS. Media Services also provides a service for delivering AES keys and DRM (PlayReady, Widevine, and FairPlay) licenses to authorized clients. If content is encrypted with an AES clear key and is sent over HTTPS, it is not in clear until it reaches the client.


Widevine is not available in the GovCloud region.

In Media Services v3, a content key is associated with Streaming Locator (see this example). If using the Media Services key delivery service, you can let Azure Media Services generate the content key for you. The content key should be generated yourself if you're using you own key delivery service, or if you need to handle a high availability scenario where you need to have the same content key in two data centers.

When a stream is requested by a player, Media Services uses the specified key to dynamically encrypt your content by using AES clear key or DRM encryption. To decrypt the stream, the player requests the key from Media Services key delivery service or the key delivery service you specified. To decide if the user is authorized to get the key, the service evaluates the content key policy that you specified for the key.

content protection system

You can use the REST API, or a Media Services client library to configure authorization and authentication policies for your licenses and keys.

This article explains concepts and terminology that help you understand content protection with Media Services.

Main components of a content protection system

To successfully complete your content protection system, you need to fully understand the scope of the effort. The following sections give an overview of three parts that you need to implement.


We highly recommended that you focus and fully test each part in the following sections before you move on to the next part. To test your content protection system, use the tools specified in the sections.

Media Services code

The DRM sample shows you how to implement a multi-DRM system with Media Services v3 by using .NET. It also shows how to use the Media Services license/key delivery service.

You can encrypt each asset with multiple encryption types (AES-128, PlayReady, Widevine, FairPlay). To see what makes sense to combine, see Streaming protocols and encryption types.

The example shows how to:

  1. Create and configure a content key policy.

    You create a content key policy to configure how the content key (which provides secure access to your assets) is delivered to end clients:

    • Define license delivery authorization. Specify the logic of the authorization check based on claims in JSON Web Token (JWT).

    • Configure PlayReady, Widevine, and/or FairPlay licenses. The templates let you configure rights and permissions for each of the DRMs.

      ContentKeyPolicyPlayReadyConfiguration playReadyConfig = ConfigurePlayReadyLicenseTemplate();
      ContentKeyPolicyWidevineConfiguration widevineConfig = ConfigureWidevineLicenseTempate();
      ContentKeyPolicyFairPlayConfiguration fairPlayConfig = ConfigureFairPlayPolicyOptions();
  2. Create a streaming locator that's configured to stream the encrypted asset.

    The streaming locator has to be associated with a streaming policy. In the example, we set StreamingLocator.StreamingPolicyName to the "Predefined_MultiDrmCencStreaming" policy.

    The PlayReady and Widevine encryptions are applied, and the key is delivered to the playback client based on the configured DRM licenses. If you also want to encrypt your stream with CBCS (FairPlay), use the "Predefined_MultiDrmStreaming" policy.

    The streaming locator is also associated with the content key policy that you defined.

  3. Create a test token.

    The GetTokenAsync method shows how to create a test token.

  4. Build the streaming URL.

    The GetDASHStreamingUrlAsync method shows how to build the streaming URL. In this case, the URL streams the DASH content.

Player with an AES or DRM client

A video player app based on a player SDK (either native or browser-based) needs to meet the following requirements:

  • The player SDK supports the needed DRM clients.
  • The player SDK supports the required streaming protocols: Smooth, DASH, and/or HTTP Live Streaming (HLS).
  • The player SDK can handle passing a JWT token in a license acquisition request.

You can create a player by using the Azure Media Player API. Use the Azure Media Player ProtectionInfo API to specify which DRM technology to use on different DRM platforms.

For testing AES or CENC (Widevine and/or PlayReady) encrypted content, you can use Azure Media Player. Make sure that you select Advanced options and check your encryption options.

If you want to test FairPlay encrypted content, use this test player. The player supports Widevine, PlayReady, and FairPlay DRMs, along with AES-128 clear key encryption.

Choose the right browser to test different DRMs:

  • Chrome, Opera, or Firefox for Widevine.
  • Microsoft Edge or Internet Explorer 11 for PlayReady.
  • Safari on macOS for FairPlay.

Security token service

A security token service (STS) issues JWT as the access token for back-end resource access. You can use the Azure Media Services license/key delivery service as the back-end resource. An STS has to define the following things:

  • Issuer and audience (or scope).
  • Claims, which are dependent on business requirements in content protection.
  • Symmetric or asymmetric verification for signature verification.
  • Key rollover support (if necessary).

You can use this STS tool to test the STS. It supports all three types of verification keys: symmetric, asymmetric, or Azure Active Directory (Azure AD) with key rollover.

Streaming protocols and encryption types

You can use Media Services to deliver your content encrypted dynamically with AES clear key or DRM encryption by using PlayReady, Widevine, or FairPlay. Currently, you can encrypt the HLS, MPEG DASH, and Smooth Streaming formats. Each protocol supports the following encryption methods.


The HLS protocol supports the following container formats and encryption schemes:

Container format Encryption scheme URL example
All AES,encryption=cbc)
MPG2-TS CBCS (FairPlay),encryption=cbcs-aapl)
CMAF(fmp4) CBCS (FairPlay),encryption=cbcs-aapl)
MPG2-TS CENC (PlayReady),encryption=cenc)
CMAF(fmp4) CENC (PlayReady),encryption=cenc)

HLS/CMAF + FairPlay (including HEVC/H.265) is supported on the following devices:

  • iOS 11 or later.
  • iPhone 8 or later.
  • macOS High Sierra with Intel 7th Generation CPU.


The MPEG-DASH protocol supports the following container formats and encryption schemes:

Container format Encryption scheme URL Examples
All AES,encryption=cbc)
CSF(fmp4) CENC (Widevine + PlayReady),encryption=cenc)
CMAF(fmp4) CENC (Widevine + PlayReady),encryption=cenc)

Smooth Streaming

The Smooth Streaming protocol supports the following container formats and encryption schemes.

Protocol Container format Encryption scheme
fMP4 CENC (PlayReady)
fMP4 PIFF 1.1 (PlayReady)


PIFF 1.1 support is provided as a backwards compatible solution for Smart TV (Samsung, LG) that implemented the early "Silverlight" version of Common Encryption. It is recommended to only use the PIFF format where needed for support of legacey Samsung or LG Smart TVs shipped between 2009-2015 that supported the PIFF 1.1 version of PlayReady encryption.


Common browsers support the following DRM clients:

Browser Encryption
Chrome Widevine
Microsoft Edge, Internet Explorer 11 PlayReady
Firefox Widevine
Opera Widevine
Safari FairPlay

Controlling content access

You can control who has access to your content by configuring the content key policy. Media Services supports multiple ways of authorizing users who make key requests. The client (player) must meet the policy before the key can be delivered to the client. The content key policy can have open or token restriction.

An open-restricted content key policy may be used when you want to issue license to anyone without authorization. For example, if your revenue is ad-based and not subscription-based.

With a token-restricted content key policy, the content key is sent only to a client that presents a valid JWT token or a simple web token (SWT) in the license/key request. This token must be issued by an STS.

You can use Azure AD as an STS or deploy a custom STS. The STS must be configured to create a token signed with the specified key and issue claims that you specified in the token restriction configuration. The Media Services license/key delivery service returns the requested license or key to the client if both of these conditions exist:

  • The token is valid.
  • The claims in the token match those configured for the license or key.

When you configure the token-restricted policy, you must specify the primary verification key, issuer, and audience parameters. The primary verification key contains the key that the token was signed with. The issuer is the STS that issues the token. The audience, sometimes called scope, describes the intent of the token or the resource that the token authorizes access to. The Media Services license/key delivery service validates that these values in the token match the values in the template.

Token replay prevention

The Token Replay Prevention feature allows Media Services customers to set a limit on how many times the same token can be used to request a key or a license. The customer can add a claim of type urn:microsoft:azure:mediaservices:maxuses in the token, where the value is the number of times the token can be used to acquire a license or key. All subsequent requests with the same token to Key Delivery will return an unauthorized response. See how to add the claim in the DRM sample.


  • Customers must have control over token generation. The claim needs to be placed in the token itself.
  • When using this feature, requests with tokens whose expiry time is more than one hour away from the time the request is received are rejected with an unauthorized response.
  • Tokens are uniquely identified by their signature. Any change to the payload (for example, update to the expiry time or the claim) changes the signature of the token and it will count as a new token that Key Delivery hasn't come across before.
  • Playback fails if the token has exceeded the maxuses value set by the customer.
  • This feature can be used for all existing protected content (only the token issued needs to be changed).
  • This feature works with both JWT and SWT.

Using a custom STS

A customer might choose to use a custom STS to provide tokens. Reasons include:

  • The identity provider (IDP) used by the customer doesn't support STS. In this case, a custom STS might be an option.

  • The customer might need more flexible or tighter control to integrate STS with the customer's subscriber billing system.

    For example, an OTT service operator might offer multiple subscriber packages, such as premium, basic, and sports. The operator might want to match the claims in a token with a subscriber's package so that only the contents in a specific package are made available. In this case, a custom STS provides the needed flexibility and control.

  • To include custom claims in the token to select between different ContentKeyPolicyOptions with different DRM license parameters (a subscription license versus a rental license).

  • To include a claim representing the content key identifier of the key that the token grants access to.

When you use a custom STS, two changes must be made:

  • When you configure license delivery service for an asset, you need to specify the security key used for verification by the custom STS instead of the current key from Azure AD.
  • When a JTW token is generated, a security key is specified instead of the private key of the current X509 certificate in Azure AD.

There are two types of security keys:

  • Symmetric key: The same key is used to generate and to verify a JWT.
  • Asymmetric key: A public-private key pair in an X509 certificate is used with a private key to encrypt/generate a JWT and with the public key to verify the token.

If you use .NET Framework/C# as your development platform, the X509 certificate used for an asymmetric security key must have a key length of at least 2048. This key length is a requirement of the class System.IdentityModel.Tokens.X509AsymmetricSecurityKey in .NET Framework. Otherwise, the following exception is thrown: IDX10630: The 'System.IdentityModel.Tokens.X509AsymmetricSecurityKey' for signing can't be smaller than '2048' bits.

Custom key and license acquisition URL

Use the following templates if you want to specify a different license/key delivery service (not Media Services). The two replaceable fields in the templates are there so that you can share your streaming policy across many assets instead of creating a streaming policy per asset.

  • EnvelopeEncryption.CustomKeyAcquisitionUrlTemplate: Template for the URL of the custom service that delivers keys to end-user players. It isn't required when you're using Azure Media Services for issuing keys.

    The template supports replaceable tokens that the service will update at runtime with the value specific to the request. The currently supported token values are:

    • {AlternativeMediaId}, which is replaced with the value of StreamingLocatorId.AlternativeMediaId.
    • {ContentKeyId}, which is replaced with the value of the identifier of the requested key.
  • StreamingPolicyPlayReadyConfiguration.CustomLicenseAcquisitionUrlTemplate: Template for the URL of the custom service that delivers licenses to end-user players. It isn't required when you're using Azure Media Services for issuing licenses.

    The template supports replaceable tokens that the service will update at runtime with the value specific to the request. The currently supported token values are:

    • {AlternativeMediaId}, which is replaced with the value of StreamingLocatorId.AlternativeMediaId.
    • {ContentKeyId}, which is replaced with the value of the identifier of the requested key.
  • StreamingPolicyWidevineConfiguration.CustomLicenseAcquisitionUrlTemplate: Same as the previous template, only for Widevine.

  • StreamingPolicyFairPlayConfiguration.CustomLicenseAcquisitionUrlTemplate: Same as the previous template, only for FairPlay.

For example:

streamingPolicy.EnvelopEncryption.customKeyAcquisitionUrlTemplate = "{AlternativeMediaId}/{ContentKeyId}";

ContentKeyId has a value of the requested key. You can use AlternativeMediaId if you want to map the request to an entity on your side. For example, AlternativeMediaId can be used to help you look up permissions.

For REST examples that use custom license/key acquisition URLs, see Streaming Policies - Create.


Widevine is a service provided by Google Inc. and subject to the terms of service and Privacy Policy of Google, Inc.

Security considerations for closed captions, subtitles, and timed-metadata delivery

The dynamic encryption and DRM features of Azure Media Services has limits to consider when attempting to secure content delivery that includes live transcriptions, captions, subtitles, or timed-metadata. The DRM subsystems, including PlayReady, FairPlay, and Widevine do not support the encryption and licensing of text tracks. The lack of DRM encryption for text tracks limits your ability to secure the contents of live transcriptions, manual inserted captions, uploaded subtitles, or timed-metadata signals that may be inserted as separate tracks.

To secure your captions, subtitles, or timed-metadata tracks, it is recommended to follow one of the guidelines:

  1. Use AES-128 Clear Key encryption. When enabling AES-128 clear key encryption, the text tracks can be configured to be encrypted using a full "envelope" encryption technique that follows the same encryption pattern as the audio and video segments. These segments can then be decrypted by a client application after requesting the decryption key from the Media Services Key Delivery service using an authenticated JWT token. This method is supported by the Azure Media Player, but may not be supported on all devices and can require some client-side development work to make sure it succeeds on all platforms.
  2. Use CDN token authentication to protect the text (subtitle, captions, metadata) tracks being delivered with short form tokenized URLs that are restricted to geo, IP, or other configurable settings in the CDN portal. Enable the CDN security features using Verizon Premium CDN or other 3rd-party CDN configured to connect to your Media Services streaming endpoints.


If you do not follow one of the guidelines above, your subtitles, captions, or timed-metadata text will be accessible as un-encrypted content that could be intercepted or shared outside of your intended client delivery path. This can result in leaked information. If you are concerned about the contents of the captions or subtitles being leaked in a secure delivery scenario, reach out to the Media Services support team for more information on the above guidelines for securing your content delivery.


If you get the MPE_ENC_ENCRYPTION_NOT_SET_IN_DELIVERY_POLICY error, make sure that you specify the appropriate streaming policy.

If you get errors that end with _NOT_SPECIFIED_IN_URL, make sure that you specify the encryption format in the URL. An example is …/manifest(format=m3u8-cmaf,encryption=cbcs-aapl). See Streaming protocols and encryption types.

Ask questions, give feedback, get updates

Check out the Azure Media Services community article to see different ways you can ask questions, give feedback, and get updates about Media Services.