Login

Mosaic products documentation: Concepts, API Reference, Technical articles, How-to, Downloads and tools

AMS License Configuration Mapping

Preword

Microsoft decided to retire its Azure Media Services (AMS) by 30 June 2024.

AMS included services for:

  • On-demand encoding

  • Live streaming

  • On-demand streaming

  • Content protection.

Axinom DRM and Axinom Encoding can be a good alternative for AMS customers, covering on-demand encoding and content protection.

The aim of this guide is to assist Azure Media Services DRM customers to migrate to Axinom DRM - part of Axinom Mosaic platform. It provides general migration guidelines as well as specific mappings for AMS configuration to Axinom DRM.

See also the Microsoft retirement guide: https://learn.microsoft.com/en-us/azure/media-services/latest/media-services-overview.

General Guidelines

Concepts

If you are using AMS, you are used to a concept of a Media Streaming Endpoint. Media Streaming Endpoint connects the video material (referenced from the endpoint) with the access rules, configurable within the endpoint. To play a DRM-protected video, a player has to provide an Authentication Token, which is used by AMS to decide if the player should receive a DRM license or not. If yes, the configured policies are applied.

Both AMS and Axinom support Widevine, PlayReady, and FairPlay, each DRM provider coming with a different set of configuration options.

In Axinom DRM, there is no direct binding between the videos and the licensing policies. You can store and stream your DRM-protected videos from anywhere. To play a protected video, the player needs a DRM license, which it can request from the Axinom DRM License Service. Within the license request you will pass a data structure called the Entitlement Message (EM), which contains the information about the requested key(s) and the policies to be applied. There is no separate location to configure the DRM policies.

With Axinom DRM, you would typically develop a custom service we call an Entitlement Service. This service would implement the authorization logic. In positive case, it would generate an Entitlement Message with the necessary DRM policies. It will further sign the Entitlement Message using a so called Communication Key - a shared secret between the Entitlement Service and the Axinom DRM License Service.

PlayerEntitlement_ServiceLicense_ServiceEntitlement Request [Key ID]Verify eligibilityPrepare Entitlement Message as JWTSign JWT using Communication KeyJWTLicense Request [Key ID, JWT]Validate JWTProcess License requestDRM License [Content Key, Usage rules]Figure 1. Interactions between the Player, the Entitlement Service and the Axinom DRM License Service
Figure 1. Interactions between the Player, the Entitlement Service and the Axinom DRM License Service

Content key management

Different DRM vendors offer different ways to specify which content keys should be returned in a license, how the key data obtained and how to attach DRM policies to them.

DRM systems fundamentally reference keys via their Key IDs (KIDs, a GUID), which is also the approach that Axinom uses in the Entitlement Message. In contrast with AMS, Axinom does not store content metadata, such as Content IDs and track labels, which can be internally mapped to the specific Key IDs. It is assumed the integrator has access to the existing content key and metadata information via AMS APIs and can extract it and perform the relevant mappings to Key IDs. The Entitlement Message shall contain the KeyID(s) of the requested keys.

Axinom DRM supports three models to generate the content keys:

  • Key Seed - the content keys are generated by the Axinom DRM License Service based on a seed value and the Key ID. This is the default mode and is suitable for most use cases.

  • Direct Keys - the content keys are provided directly in the Entitlement Message. This mode is suitable for use cases where the content keys are generated and managed by the customer.

  • Stored Keys - the content keys are uploaded and stored in the Key Service database. The License Service queries the needed keys at runtime from the Key Service. (Please contact Axinom Support to use this model, as the documentation is not yet fully published.)

If you don’t have many videos and you are fine re-encoding them, we would suggest doing so and using the Key Seed model.

If you migrate existing encrypted content library from AMS we recommend to use the Stored Keys model. You can extract the keys from AMS and ingest them into the Axinom Key Service.

For a general overview of content key management, please see: License Service documentation, with more technical details being available here.

Policy attachment

For policy attachments, please see the EM documentation:

Rules based on devices

It is possible to define rules based on user devices. However, this requires more efforts, because the device information is not directly available in the license request. The license request is sent to the License Service encrypted and it is only the License Service that can decrypt it.

Please refer to Device-specific restrictions section for information on a possible solution.

Returning requested keys vs bulk keys

Axinom by default operates in the mode where only the content keys explicitly requested by the player (via Key IDs in the PlayReady or Widevine PSSH boxes or in the Asset ID of FairPlay requests) is returned in a license, even if more keys are mentioned in the Entitlement Message. This is the original DASH-IF recommended and transparency-promoting way of operation. In this case, the keys listed in the Axinom DRM Entitlement Message are purely for "entitlement" purposes - i.e. for key selection purpose the EM is purely used to validate if a particular key requested by the player is allowed to be returned.

However, in some situations, it can be preferable that in addition to or instead of the player-requested keys, all the keys listed in the Entitlement Message are returned. Such cases and workarounds are described here:

Sample entitlement message

In the example below, the license will be issued for 1h and its persistence on the client side is allowed. Only a single keyId is permitted ("11111111-0000-0000-0000-000000000000") with a policy "Policy A". This policy is contained in the same message. It defines for Widevine the security level "SW_SECURE_DECODE" and usage of HDCP version "2.0".

A sample Entitlement Message using a specific usage policy
{
    "license": {
        "duration": 3600,
        "allow_persistence": true
    },
    "content_keys_source": {
        "inline": [
            {
                "id": "11111111-0000-0000-0000-000000000000",
                "usage_policy": "Policy A"
            }
        ]
    },
    "content_key_usage_policies": [
        {
            "name": "Policy A",
            "widevine": {
                "device_security_level": "SW_SECURE_DECODE",
                "hdcp": "2.0"
            }
        }
    ]
}

Further reading

The following links help you to start with Axinom DRM:

Configuration Mapping

This section describes the detailed mapping between AMS and Axinom configuration.

Widevine Mappings

The list of AMS Widevine settings is based on: Media Services v3 Widevine license template overview

Unless specified, the data type, defaults and allowed range of values used by Axinom match those used by AMS and the settings can be carried over as-is.

JSON message

AMS setting Axinom setting Notes

payload

N/A

Axinom licenses services expect license request data to be in the HTTP request body. In Widevine case, it is expected to be in binary format. Therefore the payload value needs to be base64-decoded into binary and the result set as the HTTP request body.

content_id

N/A

See Content key management section.

provider

N/A

Axinom license services identify user accounts via the Communication Key ID. See more under License Service Message

policy_name

N/A

Axinom does not support stored policies. Policies are provided via the Entitlement Message.

allowed_track_types

N/A

See Content key management section.

content_key_specs

Supported

See the Content key specs section below.

use_policy_overrides_exclusively

N/A

All policies are specified per-request via the Entitlement Message.

policy_overrides

Supported

See Policy overrides section below.

session_init

Partially supported

See "Session initialization" section below.

parse_only

Partially supported

See Device-specific restrictions.

Content key specs

AMS setting Axinom setting Notes

track_type

No direct mapping

See Content key management section on how to achieve the equivalent behaviour.

security_level

content_key_usage_policies.widevine.device_security_level

AMS uses integer values; Axinom uses string values. Map these as follows:

  • 1 → "SW_SECURE_CRYPTO" (default)

  • 2 → “SW_SECURE_DECODE“

  • 3 → “HW_SECURE_CRYPTO“

  • 4 → “HW_SECURE_DECODE“

  • 5 → “HW_SECURE_ALL“

If no value provided by AMS, omit value for Axinom as well (results in the default value).

required_output_protection.hdcp

content_key_usage_policies.widevine.hdcp

Note: AMS doc says the field is called “output_protection.hdc“, with missing “p” in the end. Perhaps a mistake in the doc?

The allowed string values are different, to be mapped as follows:

  • “HDCP_NONE” → omit (this is the default and can’t be explicitly specified)

  • “HDCP_V1“ → “1.0“

  • “HDCP_V2” → “2.0“

Note: Axinom supports further values (see the EM doc).

key

content_keys_source.inline[n].encrypted_key

Note: The content key must be additionally encrypted.

More about this and other key provisioning methods, please see under License Service

key_id

content_keys_source.inline[n].id

For Axinom, the value must be in the GUID string format. So a base64 → GUID string conversion is needed. For example:

  • AMS value: “0Bh4stjQSfS4oofOzZquwg==”

  • Axinom value: “d01878b2-d8d0-49f4-b8a2-87cecd9aaec2”

Policy overrides

AMS setting Axinom setting Notes

can_play

license.widevine.allow_playback

Note: Axinom defaults to “true”. Hence this can be omitted, if “true”.

can_persist

license.allow_persistence OR license.widevine.allow_persistence

can_renew

license.widevine.allow_renewal

Note: Axinom doesn’t allow any other renewal settings to be set if renewal is not allowed.

license_duration_seconds

license.duration OR license.widevine.duration AND make sure "license.widevine.real_time_duration_expiration" is NOT set (or is set to "true" - the default)

Note: Value range allowed by Axinom is: 1 - 4294967295. If the value is < 1, omit the value. If the value is greater than the max, set it to the max value.

Note: With Google deprecating the native SDK "license duration", exact AMS duration mapping is no longer possible. In case an AMS user has specified greater than zero values for both the "license" and "rental" duration, as a rule of thumb, we then recommend to ignore the rental duration and just map the license duration - in practice, the license duration is usually the more restrictive setting.

rental_duration_seconds

license.widevine.duration AND license.widevine.real_time_duration_expiraton = false

Note: Value range allowed by Axinom is: 1 - 4294967295. If the value is < 1, omit the value. If the value is greater than the max, set it to the max value.

Note: With Google deprecating the native SDK "license duration", exact AMS duration mapping is no longer possible. In case an AMS user has specified greater than zero values for both the "license" and "rental" duration, as a rule of thumb, we then recommend to ignore the rental duration and just map the license duration - in practice, the license duration is usually the more restrictive setting.

playback_duration_seconds

license.widevine.playback_duration

Note: Value range allowed by Axinom is: 1 - 4294967295. If the value is < 1, omit the value. If the value is greater than the max, set it to the max value.

renewal_server_url

license.widevine.renewal_url

Axinom doesn’t allow setting it if renewal is not allowed (must be omitted from JSON or explicitly null).

Note: this value will have no effect for Axinom server-side as the same license service instances can handle both new and renewal license requests. If set, ensure players send renewals to valid licensing endpoints. This logic is controlled by the players.

renewal_delay_seconds

license.widevine.renewal_delay

Must be omitted or “null” if renewal is not allowed.

Axinom default: 300 Allowed values: 0, 180 - 9223372036854775807 (same as AMS, except 1-179)

In case of the disallowed values, set the Axinom value to 180.

renewal_retry_interval_seconds

license.widevine.renewal_retry_interval

Must be omitted or “null” if renewal is not allowed.

Axinom default: 10 Allowed values: 0, 3 - 9223372036854775807 (same as AMS, except 1, 2)

In case of the disallowed values, set the Axinom value to 3.

renewal_recovery_duration_seconds

license.widevine.renewal_recovery

Must be omitted or “null” if renewal is not allowed.

Axinom default: 60 Allowed values: 0 - 9223372036854775807 (same as AMS)

renew_with_usage

license.widevine.renew_with_usage

Session initialization

All settings here are handled internally by Axinom DRM. If there is a usage case of setting any of them explicitly, please contact us.

AMS setting Axinom setting Notes

provider_session_token

not supported

Note: “session_id”-s, suitable for session-management are supported and are set internally. These will be exposed in the License Request Info Message in an upcoming release.

provider_client_token

not exposed - handled internally

Automatically set internally to a random GUID string, unless it is already set to a valid GUID string.

Note: When returning the “License Request Info” message is enabled, this value will be returned in that message (if the client platform supports client tokens) and can be used for device management. See License Request Info Message.

override_provider_client_token

not exposed - handled internally

Automatically overridden, unless already set to a valid GUID string.

FairPlay Mappings

Based on Axinom research, AMS seems to have a very limited set of license configurations options. Most notably, missing were:

  • Duration settings for controlling online streaming (non-persistent) playback.

    • In Axinom case, if persistence is disallowed (default), then the license duration and real time expiration settings control the online playback.

    • According to AMS doc all duration settings seemed to be related only to the offline case, and there was no hint of "leaseDuration", which in Axinom terms means "real_time_expiration".

  • HDCP settings

Note
 in the upcoming release Axinom will also provide DRM-enforced options to prevent playback via AirPlay or Digital AV Adapters.

FairPlay certificate settings

AMS settings:

  • ask

  • fairPlayPfx

  • fairPlayPfxPassword

In Axinom case, these settings, also called the FairPlay Data Sets or FairPlay Credentials, need to be provided just once in the License Service Tenant configuration in Axinom Portal. These are then synced to all FairPlay license services via our backend and do not need to be provided as part of license configuration.

See FairPlay and AxinomDRM.

License configuration settings

AMS setting Axinom setting Notes

rentalAndLeaseKeyType

license.allow_persistence OR license.fairplay_allow_persistence

As far as we can tell the AMS supported KeyTypes are:

  • DualExpiry

  • PersistentLimited

  • PersistentUnlimited

  • Undefined

The only important factor for Axinom here is that the first three key types designate that a persistent license is required. Any other value could be considered as persistence should not be allowed.

This means:

  • Set Axinom “allow_persistence” to true if AMS KeyType is one of DualExpiry, PersistentLimited or PersistentUnlimited

  • Otherwise do not set anything (allow_persistence defaults to false).

In Axinom case, a specific key type does not need to be specified as our backend automatically chooses the most appropriate key type to be used for the offline case.

offlineRentalConfiguration.playbackDurationSeconds

license.fairplay.playback_duration

Should only be available when AMS rentalAndLeaseKeyType is “DualExpiry”.

Since AMS type is “TimeSpan” and Axinom type is “uint”, conversion is needed.

Axinom supported range is: 1 - 4294967295 (uint). If the AMS value is out of this range, please constrain to this range.

Axinom does not allow 0. If the AMS value is effectively 0, omit Axinom value – this will default to 0.

offlineRentalConfiguration.storageDurationSeconds

license.duration OR license.fairplay.duration

Same “Notes” apply as for AMS “offlineRentalConfiguration.playbackDurationSeconds”.

rentalDuration

license.duration OR license.fairplay.duration

Should only be available when AMS rentalAndLeaseKeyType = “PersistentLimited”.

Otherwise, same “Notes” apply as for AMS “offlineRentalConfiguration.playbackDurationSeconds”

PlayReady Mappings

AMS setting Axinom setting Notes

beginDate

license.start_datetime

AMS value can be directly used.

expirationDate

license.expiration_datetime

AMS value can be directly used.

licenseType

license.allow_persistence

AMS uses string values; Axinom uses a boolean. Map these as follows:

  • “Persistent” → true

  • “NonPersistent” → false (default)

securityLevel

content_key_usage_policies.playready.min_device_security_level

AMS uses string values; Axinom uses string values. Map these as follows:

  • “SL150“ → 150

  • “SL2000“ → 2000

  • “SL3000“ → 3000

contentType

content_key_usage_policies.playready.source_id

AMS uses string values; Axinom uses string values. Map these as follows:

  • “Unpecified“ → 0

  • “UltraVioletDownload“ → 267

  • “UltraVioletStreaming“ → 268

firstPlayExpiration

license.playready.playback_duration

AMS uses timespan string values; Axinom uses integer values (in seconds). Map these as follows:

  • “00:01:10“ → 70

analogVideoOpl

content_key_usage_policies.playready.analog_video_opl

compressedDigitalAudioOpl

content_key_usage_policies.playready.compressed_digital_audio_opl

compressedDigitalVideoOpl

content_key_usage_policies.playready.compressed_digital_video_opl

uncompressedDigitalAudioOpl

content_key_usage_policies.playready.uncompressed_digital_audio_opl

uncompressedDigitalVideoOpl

content_key_usage_policies.playready.uncompressed_digital_video_opl

allowPassingVideoContentToUnknownOutput

content_key_usage_policies.playready.play_enablers

AMS uses string values; Axinom uses GUID string values. Map these as follows:

  • “Allowed“ → “786627D8-C2A6-44BE-8F88-08AE255B01A7“

  • “AllowedWithVideoConstriction“ → “B621D91F-EDCC-4035-8D4B-DC71760D43E9“

  • “NotAllowed“ → Do not set play_enablers flag.

agcAndColorStripeRestriction

content_key_usage_policies.playready.analog_video_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”C3FD11C6-F8B7-4D20-B008-1DB17D61F2DA”

Values (“config_data“):

  • 00 → “AA==”

  • 01 → “AQ==“

  • 02 → “Ag==“

  • 03 → “Aw==“

E.g:

00 → analog_video_output_protections = [ { “id“:”C3FD11C6-F8B7-4D20-B008-1DB17D61F2DA”, “config_data“: “AA==” } ]

explicitAnalogTelevisionOutputRestriction.configurationData

content_key_usage_policies.playready.analog_video_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”2098DE8D-7DDD-4BAB-96C6-32EBB6FABEA3”

Values (“config_data“):

  • 00 → “AA==”

  • 01 → “AQ==“

  • 02 → “Ag==“

  • 03 → “Aw==“

explicitAnalogTelevisionOutputRestriction.bestEffort

content_key_usage_policies.playready.analog_video_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”225CD36F-F132-49EF-BA8C-C91EA28E4369”

Values (“config_data“):

  • 00 → “AA==”

  • 01 → “AQ==“

  • 02 → “Ag==“

  • 03 → “Aw==“

imageConstraintForAnalogComponentVideoRestriction

content_key_usage_policies.playready.analog_video_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”811C5110-46C8-4C6E-8163-C0482A15D47E”

Values (“config_data“):

  • true→ “UgAA”

  • false → Do not set this key value pair.

imageConstraintForAnalogComputerMonitorRestriction

content_key_usage_policies.playready.analog_video_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”D783A191-E083-4BAF-B2DA-E69F910B3772”

Values (“config_data“):

  • true→ “UgAA”

  • false → Do not set this key value pair.

digitalVideoOnlyContentRestriction

content_key_usage_policies.playready.analog_video_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”760AE755-682A-41E0-B1B3-DCDF836A7306”

Values (“config_data“):

  • true→ “AA==”

  • false → Do not set this key value pair.

scmsRestriction

content_key_usage_policies.playready.digital_audio_output_protections

AMS handles output protection as individual flags; Axinom uses key value pairs, where, key (GUID) is the protection feature and value (base64) is the configuration for it. Map these as follows:

Key (“id”) → ”6D5CFA59-C250-4426-930E-FAC72C8FCFA6”

Values (“config_data“):

  • 00 → “AA==”

  • 01 → “AQ==“

  • 02 → “Ag==“

  • 03 → “Aw==“

relativeExpirationDate

license.duration

AMS uses timespan string values; Axinom uses integer values (in seconds). Map these as follows:

“00:01:10“ → 70

relativeBeginDate

Not supported

Same effect could be achieved in Axinom DRM by computing the absolute timestamp and set it in expiration_datetime

allowTestDevices

Not supported

Please contact Axinom for more information.

gracePeriod

Not supported and Deprecated

This flag is only available in PlayReady older client versions below 3.0 and now deprecated.

contentKeyLocation

Not Applicable

AMS allows two settings “ContentEncryptionKeyFromHeader” (default) and “ContentEncryptionKeyFromKeyIdentifier”.

Axinom also get the key ID from the PSSH box (PlayReady Header) by default.

However, if the key IDs are set in AMS content key policies, similar behaviour can be achieved in Axinom by use of stored content keys or encrypted content keys. For this key IDs/key must be known.

Contact Axinom for more information.
Note
 In addition to the above-mentioned parameter mappings, Axinom supports more protection flags in PlayReady, for example, HDCP restrictions, content source IDs, etc.
Version Date Description

1.0

August 01, 2023

Initial version.

2.0

December 15, 2023

Updated Widevine mapping information.

3.0

February 16, 2024

Added an introduction and made more readable

Axinom uses cookies for analytics and personalized content. By continuing to browse this site, you agree to this use. Learn more