Entitlement System - Content Management

Entitlement System

Entitlement is Kaltura's mechanism for restricting content visibility based on category membership. It combines category privacy settings, user membership, and KS privileges.

How Entitlement Works

Content entitlements govern which users can see which entries. Entitlements are configured at the category level by setting a privacy context (privacyContext field) -- a free-text label (English characters, no commas or spaces) that identifies the application context.

Applications such as Content Hubs use entitlements to implement "authenticated content channels."

1. Category privacy (privacy field) sets the baseline visibility rule.
2. Category membership (categoryUser) determines which users have access to MEMBERS_ONLY categories.
3. KS privileges control whether entitlement is enforced and which privacy contexts are applied.
4. Content owner always has access to their own content regardless of category settings.

KS Privileges for Entitlement

Privilege	Description
enableentitlement	Activates entitlement enforcement for this session
privacycontext:LABEL	Sets the privacy context to match against category privacyContext values
disableentitlement	Explicitly disables entitlement (default for ADMIN KS)
disableentitlementforentry:ENTRY_ID	Bypasses entitlement for a specific entry

Generate a USER KS with entitlement:

curl -X POST "$KALTURA_SERVICE_URL/service/session/action/start" \
  -d "format=1" \
  -d "partnerId=$KALTURA_PARTNER_ID" \
  -d "secret=$KALTURA_ADMIN_SECRET" \
  -d "type=0" \
  -d "userId=jane.doe@example.com" \
  -d "privileges=enableentitlement,privacycontext:myapp"

Entitlement Enforcement Decision Flow

The server evaluates content access in this order (first match wins):

Step	Check	Result if True
1	Entitlement disabled for this entry by widget/feed services	ALLOWED
2	Account's defaultEntitlementEnforcement is FALSE	ALLOWED
3	KS has disableentitlement OR disableentitlementforentry matching this entry	ALLOWED
4	KS userId is the entry owner	ALLOWED
5	KS userId has edit or publish permission on the entry	ALLOWED
6	Entry is NOT associated with any categories	ALLOWED
7	ALL of the entry's categories have privacyContext = null	ALLOWED
8	KS privacycontext matches one of the entry's categories' privacyContext AND category.privacy is ALL (1)	ALLOWED
9	KS privacycontext matches AND category.privacy is AUTHENTICATED_USERS (2) AND KS has valid userId	ALLOWED
10	KS privacycontext matches AND category.privacy is MEMBERS_ONLY (3) AND userId is a category member	ALLOWED
11	None of the above conditions met	DENIED

Content Visibility with Multiple Categories

When an entry is assigned to multiple categories, the least restrictive privacy setting determines access. If an entry is in both a MEMBERS_ONLY category and an ALL category within the same privacy context, the entry is accessible to everyone.

Privacy Context Configuration

Privacy context is a free-text label that ties categories to applications:

• Assign the same privacyContext to an entire category branch to scope entitlement per application
• Use privacyContexts (plural) for multiple comma-separated labels when a category serves multiple applications
• The KS privacycontext privilege must match the category's privacyContext for entitlement to be evaluated
• Categories without a privacyContext are not subject to entitlement enforcement

Account-Level Entitlement Configuration

The defaultEntitlementEnforcement property on KalturaPartner controls global enforcement:

• true (default): Entitlement is enforced. API calls must provide a KS with the correct privacycontext and a userId who is a member of the category.
• false: Entitlement is not enforced by default. Any valid KS can access content. The application is responsible for implementing its own entitlement logic.

Setting Up Entitlement -- Complete Walkthrough

1. Create a category with privacy=3 (MEMBERS_ONLY) and a privacyContext:

curl -X POST "$KALTURA_SERVICE_URL/service/category/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "category[objectType]=KalturaCategory" \
  -d "category[name]=Premium Content" \
  -d "category[privacy]=3" \
  -d "category[privacyContext]=myapp"

2. Add users as members of the category:

curl -X POST "$KALTURA_SERVICE_URL/service/categoryUser/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "categoryUser[objectType]=KalturaCategoryUser" \
  -d "categoryUser[categoryId]=$CATEGORY_ID" \
  -d "categoryUser[userId]=jane.doe@example.com" \
  -d "categoryUser[permissionLevel]=3"

3. Assign entries to the category:

curl -X POST "$KALTURA_SERVICE_URL/service/categoryEntry/action/add" \
  -d "ks=$KALTURA_KS" \
  -d "format=1" \
  -d "categoryEntry[objectType]=KalturaCategoryEntry" \
  -d "categoryEntry[categoryId]=$CATEGORY_ID" \
  -d "categoryEntry[entryId]=$KALTURA_ENTRY_ID"

4. Generate a user KS with entitlement for the matching privacy context:

curl -X POST "$KALTURA_SERVICE_URL/service/session/action/start" \
  -d "format=1" \
  -d "partnerId=$KALTURA_PARTNER_ID" \
  -d "secret=$KALTURA_ADMIN_SECRET" \
  -d "type=0" \
  -d "userId=jane.doe@example.com" \
  -d "privileges=enableentitlement,privacycontext:myapp"

Only jane.doe@example.com (a category member) can see entries in this category when using this KS. Other users with entitlement enabled for the same privacycontext who are not category members cannot see the entries.

Backward Compatibility Note

The KalturaBaseEntry exposes categories and categoriesIds properties. These properties work only when categories are NOT configured with entitlement settings. Use the categoryEntry service to manage category assignments in all cases.