The Kaltura Media Access Control Model

Printer-friendly version

An Access Control Profile defines authorized and restricted domains where your content can or cannot be displayed, countries from which it can or cannot be viewed, white and black lists of IP addresses and authorized and unauthorized domains and devices in which your media can be embedded.

For information on Kaltura session-based restrictions, refer to Kaltura's API Authentication and Security

Access Control API

The access control API service accessControlProfile  provides the following actions:

accessControlProfile

KalturaAccessControlProfile

The API object KalturaAccessControlProfile is composed of an ordered set of rules of type KalturaRule.

KalturaRule

The KalturaRule type contains the following attributes:

Name Type Writable

Description

actions

KalturaAccessControlActionArray

V

Actions to be performed by the player in case the rule is fulfilled.

conditions

KalturaConditionArray

V

Conditions to validate the rule.

contexts

KalturaAccessControlContextTypeHolderArray

V

Indicates what contexts should be tested by this rule. 

message

string

V

Message to be thrown to the player in case the rule is fulfilled.

stopProcessing

boolean

V

Indicates that when this rule has been met there is no need to continue checking the rest of the rules. 

Rules are evaluated according to their order and evaluated only if they are configured to run in the current context, according to their contexts attribute. A KalturaRule is considered  fulfilled only if all its conditions are evaluated as true. The available context types are in the KalturaAccessControlContextType.

KalturaAccessControlContextType

Name

Type

Value

DOWNLOAD

string

2

PLAY

string

1

THUMBNAIL

string

3

All rules are evaluated, unless one of the rule's stop processing flag is true and the rule condition was fulfilled. Each rule that matches the conditions, adds the actions to the outcome actions and its message to the outcome messages. All of the actions are performed for rules that are evaluated and their conditions are true. Each rule is composed of a set of conditions KalturaCondition  and an action KalturaAccessControlAction.  The action types are described in KalturaAccessControlActionType. The logical relation between the set of conditions in a single rule uses the AND operator, meaning that all conditions must be evaluated to true in order to consider the rule as fulfilled.

KalturaCondition

The condition types are:

KalturaConditionType 

Name Type Value

Description

AUTHENTICATED 

string

 1

Validate that the user is authenticated, specific privileges may be defined.

COUNTRY

string

 2

Validate that the request came from a specific country, calculated according to request IP.

FIELD_COMPARE 

string

 7

Validate that the field number compared correctly to all listed numeric values.

FIELD_MATCH

string

 6

Validate that the field text matches any of listed textual values. 
IP_ADDRESS  string   3 Validate that the request came from a specific IP range.
METADATA_FIELD_COMPARE  string metadata.FieldCompare  Validate that all metadata elements number compared correctly to all listed numeric values. 
METADATA_FIELD_MATCH string  metadata.FieldMatch  Validate that any of the metadata elements text matches any of listed textual values. 
SITE string  4 Validate that the request came from a specific domain, wildcards are supported. 
USER_AGENT string   5 Validate that the request came from a specific user agent, regular expressions are supported. 

 The objects available that implement the condition objects are:

For example:

Rule #1 – conditions: KS is not valid -> action: block

Rule #2 – conditions: country is not US -> action: block

If no rule applies, no action will be taken and the content will be allowed.

Understanding the Compare and Match Condition Objects 

FIELD_COMPARE and FIELD_MATCH differentiate generic fields from generic values. A field is any implementation of KalturaStringField for textual matching or KalturaIntegerField for numeric comparison.

KalturaStringField implementations:

  • KalturaCountryContextField – Represents the current request's country context as calculated based on the IP address.
  • KalturaIpAddressContextField – Represents the current request's IP address context.
  • KalturaUserAgentContextField – Represents the current request's user agent context.
  • KalturaUserEmailContextField – Represents the current session's user e-mail address context.
  • KalturaEvalStringField (Falcon only: Requires Admin Console permission) – Evaluates a PHP statement, depends on the execution context.

KalturaIntegerField implementations:

  • KalturaTimeContextField – Represents the current time context on Kaltura servers.

FIELD_COMPARE and FIELD_MATCH use KalturaIntegerValue for numeric comparison values and KalturaStringValue for textual matches.

KalturaIntegerValue may contain a numeric value or may be implemented as KalturaIntegerField.

KalturaStringValue may contain a string value or may be implemented as KalturaStringField.

METADATA_FIELD_COMPARE and METADATA_FIELD_MATCH also use KalturaIntegerValue and KalturaStringValue for sets of values. For the metadata condition objects, the field used is from the metadata fields of a specific xPath in the metadata XML (instead of the field object).

The profile ID attribute indicates the metadata profile ID to use.

The xPath attribute may contain the full xPath to the field in the following formats:

  • xPath with a slash
    For example:  /metadata/myElementName
  • Using a local name function 
    For example: /*[local-name()='metadata']/*[local-name()='myElementName']
  • Using only the field name
    For example: myElementName will be searched as //myElementName

KalturaAccessControlActionType

The following set of actions are defined:

  1. KalturaAccessControlBlockAction - Block access
  2. KalturaAccessControlPreviewAction - Preview – play only the first X seconds of a video

KalturaAccessControlScope

The KalturaAccessControlScopeAPI contains a predefined list of context variables: 

Name

Type

Writable

Description

contexts

KalturaAccessControlContextTypeHolderArray

V

Indicates what contexts should be tested. No context means any context.

ip

string

V

IP to be used to test geographic location conditions.

ks

string

V

Kaltura session to be used to test session and user conditions.

referrer

string

V

URL to be used to test domain conditions.

time

int

V

Unix timestamp (in seconds) to be used to test entry scheduling, keep null to use now.

userAgent

string

V

Browser or client application to be used to test agent conditions.


Examples

The following examples are in PHP and effectively will be the same across all client libraries. 

Note that the xpath property may contain the full xpath to the field in three formats:

  • Slashed xPath, e.g. /metadata/myElementName
  • Using local-name function, e.g. /*[local-name()='metadata']/*[local-name()='myElementName']
  • Using only the field name, e.g. myElementName, it will be searched as //myElementName

Device-specific scheduling window

Condition #1: User agent MATCH 'ipad' (regular expression)

$value1 = new KalturaStringValue();
$value1->value = '.*ipad.*';
$condition1 = new KalturaUserAgentCondition();
$condition1->values = array($value1);

Condition #2: Current time => entry’s {metadata_123/ipadSunrise}

$condition2 = new KalturaCompareMetadataCondition();
$condition2->comparison = KalturaSearchConditionComparison::LESS_THAN_OR_EQUAL;
$condition2->xPath = 'ipadSunrise';
$condition2->profileId = 123;
$condition2->value = new KalturaTimeContextField();

Condition #3: Current time <= entry’s {metadata_123/ipadSunset}

$condition3 = new KalturaCompareMetadataCondition();
$condition3->comparison = KalturaSearchConditionComparison::GREATER_THAN_OR_EQUAL;
$condition3->xPath = 'ipadSunset';
$condition3->profileId = 123;
$condition3->value = new KalturaTimeContextField();

Actions: none

$rule->conditions = array($condition1, $condition2, $condition3);
$rule->stopProcessing = true;

The next rule should be defined with no conditions and one block action in order to block all requests that didn’t stop processing on the first rule.

Block long-form content on mobile devices

Condition #1: User agent MATCH ‘Mobile devices of brands X, Y, Z’ (regular expression)

$value1 = new KalturaStringValue();
$value1->value = '.*X.*';
$value2 = new KalturaStringValue();
$value2->value = '.*Y.*';
$value3 = new KalturaStringValue();
$value3->value = '.*Z.*';
$condition1 = new KalturaUserAgentCondition();
$condition1->values = array($value1, $value2, $value3);

Condition #2: Entry’s {metadata_123/FormatType} Equals ‘Long Form’

$value1 = new KalturaStringValue();
$value1->value = 'Long Form';
$condition2 = new KalturaMatchMetadataCondition();
$condition2->xPath = 'FormatType';
$condition2->profileId = 123;
$condition2->values = array($value1);
$rule->conditions = array($condition1, $condition2);

Actions: Block

$rule->actions = array(new KalturaAccessControlBlockAction());

Block language-specific content for consumers in a specific geography

Condition #1: Region Equals Quebec* (First phase will be limited to countries)

$value1 = new KalturaStringValue();
$value1->value = 'Quebec';
$condition1 = new KalturaCountryCondition();
$condition1->values = array($value1);

Condition #2: entry’s {metadata_123/AudioLanguage} NOT Equals ‘French’

$value1 = new KalturaStringValue();
$value1->value = ‘French';
$condition2 = new KalturaMatchMetadataCondition();
$condition2->xPath = 'AudioLanguage';
$condition2->profileId = 123;
$condition2->values = array($value1);
$condition2->not = true;

Actions: Block

$rule->actions = array(new KalturaAccessControlBlockAction());

Block content for unidentified devices

Condition #1: User agent NOT MATCH ‘Mobile devices of brands X, Y, Z’ (regular expression)

$value1 = new KalturaStringValue();
$value1->value = '.*X.*';
$value2 = new KalturaStringValue();
$value2->value = '.*Y.*';
$value3 = new KalturaStringValue();
$value3->value = '.*Z.*';
$condition1 = new KalturaUserAgentCondition();
$condition1->values = array($value1, $value2, $value3);
$condition1->not = true;

Actions: Block

$rule->actions = array(new KalturaAccessControlBlockAction());
(24233 reads)