Login

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

Creating a License Service Proxy

You can use a License Service Proxy to acheive different business use cases. As an example, if you want to process the requests from the player before it reaches the Axinom license Service or before sending the license response back to the player, you can use a proxy in between and filter out the requests. In general, the proxy mode workflow should be as follows:

  1. Playback of DRM protected content triggered in a player and player generates the license request (as usual).

  2. Instead of player sending the license request directly to the license service, the player is configured to send the license request to your proxy service URL.

  3. Your proxy then forwards the exact license request data sent by the player to the license service (in the request body), and also generates and attaches the license token to the request. NOTE: In proxy mode, usually the license token should also be configured with the “return_license_request_info: true“ option in the entitlement message. This option then tells the license service to return additional data to your proxy that you can the use in the proxy for device management.

  4. License service then generates the license and returns it to your proxy. If “return_license_request_info” is enabled in the license token, then additional device info will also be returned in a header.

  5. Proxy now got the license from the license service. Proxy can now perform some device management based on the response data. If proxy decides that the requesting device is still allowed to play this content, then the proxy now must also return the license data (in the HTTP response body) back to the player (exactly as it was received from the license service).

  6. Player now gets the license back from the proxy. The round trip is now complete. The player starts using the license and playback starts.

How to generate the license token when using the Proxy mode

Actually there is no hard rule how the license token generation should be set up or how the content key ID’s are stored.

In many cases our customers have come up with that fits their own desired workflows.

The proxy service could be one candidate where it is done. Perhaps the proxy could get the key ID from a content metadata database, based on some custom info the player app sends to the proxy or maybe the player app just sends the key ID that is needed for playback. But in any cases, it is important to keep in mind to organize the token generation so that only the valid users can get tokens only for intended content.

How to get the key IDs

There are two main possibilities:

  1. Key ID gets stored somewhere (possibly together with any other content metadata) while it’s packaged. Some AWS users have used “AWS Lambda” to set up a proxy between AWS MediaPackage and our Key Service, so they can e.g. intercept the Key IDs and then store and later do something with them.

  2. Since Key IDs are included in the manifest anyway during packaging, it is also possible to later, at a desired point, to parse them from the manifest. It could be right before playback in player code or perhaps in a separate service, that reads the manifest, parses the key ID and then generates the token.

Device identification in License Proxy Mode

As we have specified in License service Documentation, the device-specific Restrictions can be handled in the "Proxy Mode". Once you specify "return_license_request.info=true" in your Entitlement Message, License Service will extract the device Id and pass it to the Entitlement Message in the HTTP response Header X-AxDRM-Message.

How would the proxy help in the device management

  1. Know the user who sent the license request (in order to map Device IDs to particular users).

  2. Store Device IDs (as reported by our license responses in the "License Request Info Message" structure).

  3. Contain device management logic based on the above data.

  4. Be able to affect token generation (optional; if it is beneficial to deny licenses based on the "allowed_device_ids" in the token)

The usage of "allowed_device_ids" is optional as licenses can also be denied/allowed directly in the proxy. As an example, if a license response comes back from the license service and the Device ID is parsed and it is determined that this specific ID should not be allowed, the proxy can then just decide to not return the valid license to the player. Alternatively, if there’s a relatively stable list of allowed devices established in some preliminary phase or it is for any other reason more convenient to let the license be denied on the server-side and just pass through the response to the player (instead of clearing response body, altering status code, setting error message, etc), then the "allowed" list in the Entitlement Message could be used. Additionally, if your contract with us says the pricing of our service is per license generated, it may also make sense to have the license denied on the server (i.e. use the "allow" list), so it won’t count as a generated license.

The identity of the device will be found out only after the license service has responded to the proxy with a device ID. Then the proxy can make a decision whether to pass the license to the client or not, based on business logic. Here is a simple scenario:

  1. User makes first license request via the proxy.

  2. Proxy sees that the Device ID is both new and there are also no other existing Device IDs currently registered for the user. So it’s probably fine to allow playback — as it’s the first device, no concurrency limits can be exceeded.

  3. Proxy stores this Device ID and passes the license to the user for playback.

  4. The user makes another request from a different device. Proxy parses the device ID and notices that now there are two IDs from the same user. Now proxy can make some decisions: e.g. return an error saying that user is limited to 1 device only and e.g. to start using a different device user would need to wait some predefined time for previous device ID to be forgotten/disabled or take some action in a management system UI to "unregister" old devices. Once a device "slot" becomes free again or the number of available slots is increased, the user may start playback from more new devices.

Persistance of the device ID

Additional testing on your side with devices/platforms/use-cases would likely also be needed as we may not know all the triggers and nuances that will or won’t affect a Device ID. In addition, for Widevine we support three different types of Device IDs that can be useful in different cases. Here is a small summary regarding Widevine IDs here:

  1. "device_certificate_serial_number". This the recommended identifier to use for most cases other than Desktop browsers.

    1. On Desktop browsers we found it to be exactly the same for various browsers on various machines. So not usable for differentiation.

    2. In Android browsers, it seems to be different across devices and browsers. But can change with the clearing of browser’s cache and reinstalling browser; simple browser update should not affect it (We are not 100% sure about the case when update also causes CDM change). So, I’d say it can be expected for users to change "sometimes", but probably better to notify users what could trigger this and how to deal with consequences. Overall, I guess since anyway users can be expected to use different devices from time to time, there can be some system in place to allow for this. Overall, should be suitable for Android browser management.

    3. In Android native apps, the serial will be different across devices and is quite stable — not affected by app reinstall or clearing of app cache. A device factory reset might affect the ID.

  2. "device_id" — this is deprecated by Widevine, but may serve some use in the case of some older devices.

  3. "client_token" — this is intended to be used with Desktop browsers. It is a random value set by the license service upon the first request from a specific browser. Afterward, the browser will store this value and transmit it automatically in all subsequent requests and will be reported by us in the License Request Info Message. Android native apps and Android Chrome do not support it. Also, browser players that wish to utilize this must set the EME "persistent state" to "required"(The status is defined in https://www.w3.org/TR/encrypted-media/#dom-mediakeysystemconfiguration-persistentstate). Otherwise this ID can’t be set and won’t be stored. Also, this ID will be erased and a new one will be set if the user clears the browser cache.