Entitlement Service

Manage content entitlements and rights of end-users.

Overview

The purpose of an Entitlement Service is to decide based on the defined business rules if a given end-user should be able to play a given video and to provide respective entitlements.

Entitlement: the fact of having a right to something

A frontend application can then display or hide a video from the end-user. If DRM is used, it can further exchange the provided entitlements into a DRM license using a DRM License Service. This DRM License will be used by a video player (and the underlying Content Decryption Module) to decrypt and play the video.

Mosaic Entitlement Service integrates into the larger Monetization and Billing context. It makes its decisions based on the data provided by the Monetization Service (Subscription Plans, Claim Sets, Bundles), by the Billing Service (user subscriptions), and by the Media Service (movies/episodes and their licensing restrictions).

Entitlement Service natively supports Axinom DRM (it generates an entitlement message directly understood by the Axinom DRM License Service), but it can easily be adjusted to communicate with other DRM providers, see DRM Support below.

Axinom Entitlement Service is a customizable service. It is provided in source code under an open-source license. You can use the service as-is, or you can freely customize it to tailor your environment.

Entitlement service is delivered as a part of the Mosaic Media Template.

Data Model

The Data Model is described in the context of the Monetization and Billing.

Entitlement Service owns the following data:

• Claims Definition Schema - stored in the source code
• GeoIP Database - for deriving end-user’s country based on the IP address.

It also stores:

• Snapshots of the Subscription Plans, Claim Sets and Bundles received from the Monetization Service

Claims Definition Schema

Claims Definitions Schema is defined in the source code: /src/domains/monetization/claim-definition-groups.ts.

Example of the Claim Definition Groups

/**
 * An array of all Claim Definition Groups that is synced to monetization service.
 */
export const claimDefinitionGroups: ClaimDefinitionGroup[] = [
  {
    title: 'Downloadability',
    selection_mode: 'SINGLE',
    claim_definitions: [
      {
        claim: ENABLE_VIDEOS_DOWNLOAD,
        title: 'Enable videos download',
      },
    ],
  },
...

The definitions made here are synchronized to the Monetization Service and are used there to build a GUI for adding Claim Sets to Subscription Plans.

GeoIP Database

A GeoIP Database is used for deriving end-user’s country based on the IP address. A free tier of a Maxmind country database is currently included.

The GeoIP Database is updated automatically on every Entitlement Service startup and then every 24 hours. This complies with the licensing conditions of Maxmind. The database can also be easily updated manually by updating geoip-country npm package that is used, since the vendor regularly deploys new versions with updated databases.

GUI

Entitlement Service does not have its own GUI.

Interfaces

GraphQL Frontend-facing

Entitlement Service exposes a GraphQL query endpoint entitlement() that takes an entityId as a parameter and returns (in positive case) an Entitlement Message and an array of claims that passed the evaluation.

entityId is the ID of an entity that the caller would like to play, e.g. movie-123 or episode-456.

To call this endpoint, the end-user must be authenticated using the User Service and must provide a valid JWT token.

Business Rules

To make its decision the Entitlement Service performs the following steps:

Entitlement Service implements the following Claims checks:

Claim Group	Claims	Meaning	If no claim in the group
Entity Type	ENTITY_TYPE_MOVIES, ENTITY_TYPE_EPISODES	ENTITY_TYPE_MOVIES: any Movie is allowed, ENTITY_TYPE_EPISODES: any Episode is allowed	Request denied
Countries	e.g. COUNTRY_DE	Only specified countries are allowed	Any country is allowed
Maximum Quality	QUALITY_(SD,HD,UHD1,UHD2)	Only specified quality groups should be playable. Enforcement of the rule currently is delegated to a frontend. Later can be taken over by the DRM License Service.	no effect
Downloadability	ENABLE_VIDEOS_DOWNLOAD	Only if set, enables a persistent DRM License	Request is granted, but without a possibility for a persistent license

Customizing Business Rules

If you would like to add/remove/modify the entitlement checks, you can easily do so by modifying the source code of the Entitlement Service.

Removing unused checks can make sense already from a performance point of view.

Roadmap

In the future we plan to extend the Entitlement Service with the following:

• TVOD support. Once the Billing Service supports TVOD, Entitlement Service will be able to check if an end-user purchased a specific movie and grant access to it
• AVOD/FVOD, based on Monetization Service' support
• Device Management - once Axinom DRM supports limiting the number of devices which should be able to play a video simultaneously, the Entitlement Service will implement the corresponding claims
• Multiple active subscriptions - currently Entitlement Service only supports a single active subscription for any end-user. But this can be extended to the case of multiple different subscriptions with additive logic.

DRM Support

The service is compatible with Axinom DRM - it generates an Entitlement Message, that is understood natively by Axinom DRM License Service.

The currently implemented logic does the following:

• In a positive case, create an Axinom DRM Entitlement Message wrapped into an Axinom DRM License Service Message
• Include every Key ID (Key IDs are assumed to be maintained in the Video Service and published through the Catalog Service)
• Assign the same Policy to all Key IDs
• For this policy set for PlayReady - for development purpose - min_device_security_level: 150 and a PlayReady enabler "Support playback when the output type is unknown"
• Set license.allow_persistence to true or false, depending on the presence of the claim ENABLE_VIDEOS_DOWNLOAD
• Sign the generated Entitlement Message with the configured Communication Key (you can find it in your Axinom DRM configuration).

Customizing DRM Support

To customize the logic for Entitlement Message generation, adjust the file entitlement-message-generation.ts.

If you use Axinom DRM, you may want to customize the structure of the Entitlement Message. See Entitlement Message (data structure) and Entitlement Message (Tool) for more details.

If you use a different DRM provider, replace the code according to the instructions of the respective provider.

Pricing

Entitlement Service is provided under an open-source license free of charge.