Manage content entitlement and rights of subscribers

Entitlement Service

Manage content entitlements and rights of consumers.

Overview

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

Entitlement: the fact of having a right to something
— OxfordLanguages

A frontend application can then display or hide a video from the consumer. 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 Content Monetization Solution. 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 Integration] 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 OTT Template.

Data Model

The Data Model is described in the context of the Content Monetization Solution.

Entitlement Service owns the following data:

  • Claims Definition Schema - stored in the source code

  • GeoIP Database - for deriving consumer’s country based on the IP address.

It also stores:

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 consumer’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 consumer 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:

Check if aJWTis supplied and validDetect consumer'scountrybased on the IP address(GeoIP database)Getmovie/episode's details based on the `entityId`(Catalog Service)Check movie/episode'slicensingfor consumer's countryGet consumer's activeSubscription (Billing Service)CheckClaim Setsfor theSubscription (see below)

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 a consumer 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 consumer. 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 Encoding 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.