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

• addAction
• getAction
• updateAction
• deleteAction
• listAction

KalturaAccessControlProfile

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

KalturaRule

The KalturaRule type contains the following attributes:

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

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 

 The objects available that implement the condition objects are:

• KalturaAuthenticatedCondition **Note: **This object should be configured only on an entry level access control objects.
• KalturaCompareMetadataCondition
• KalturaFieldCompareCondition
• KalturaCountryCondition
• KalturaFieldMatchCondition
• KalturaIpAddressCondition
• KalturaMatchMetadataCondition
• KalturaUserAgentCondition
• KalturaSiteCondition

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: 

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)

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

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

<?php
$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}

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

Actions: none

<?php
$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)

<?php
$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’

<?php
$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

<?php
$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)

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

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

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

Actions: Block

<?php
$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)

<?php
$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

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