Access control for items, libraries, collections

Items, libraries and collections have access control lists that determine what operations a user can perform. The entries in the list either corresponds to a specific user or to an entire group.

Overview

Vidispine uses the access controls on the item, library or collection to determine if a user has access to perform a specific operation or not.

All entities will have a OWNER access control that identifies the user that created the entity, and that grants full access to it. Below is an example access control list document showing the access that has been applied to a specific collection:

<AccessControlListDocument xmlns:ns0="http://xml.vidispine.com/schema/vidispine">
    <access id="VX-16610">
        <loc>http://vs.example.com:8080/API/collection/VX-16/access/VX-21</loc>
        <appliesTo>all</appliesTo>
        <permission>OWNER</permission>
        <user>admin</user>
    </access>
    <access id="VX-18037">
        <loc>http://vs.example.com:8080/API/collection/VX-16/access/VX-21</loc>
        <grantor>admin</grantor>
        <appliesTo>self</appliesTo>
        <appliesTo recursive="true">collection</appliesTo>
        <appliesTo recursive="true">item</appliesTo>
        <permission>READ</permission>
        <user>example-user</user>
    </access>
</AccessControlListDocument>

The first access entry is the OWNER access, which shows that the admin user has created the collection, and is thus the owner with full access.

The second access entry shows that admin has granted READ access to example-user. The appliesTo setting has been used to determine which entities the access control extends to. In this case, access has been granted to the collection itself, child collections and items, but not libraries. If the appliesTo element is not set, access is granted to self and all decedent entities.

New in version 4.17.7.

All appliesTo settings have a property called recursive which is used to control the depth of the accesses granted. A recursive setting will dig through the entities entire relationship tree until it finds all entities for which the setting is applicable. If a setting is not recursive it will only look at the direct children of the entity on which it is set. If recursive is not explicitly set, the default is that the setting IS recursive. Consider the following example:

  • Collection A contains Item A and Collection B.
  • Collection B contains Item B.

<appliesTo recursive="true">item</appliesTo> will affect both Item A and Item B. <appliesTo recursive="false">item</appliesTo> will only affect Item A.

Setting recursive on self is a no-op. Setting recursive on libraries is also no different from setting recursive to false since libraries cannot contain further libraries.

Manage access controls using the access control resource on the entity in question. For example, to grant access to Users, but only allow them access to certain shapes:

POST /collection/VX-16/access
Content-Type: application/xml

<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <permission>READ</permission>
  <group>users</group>
</AccessControlDocument>
POST /collection/VX-16/access
Content-Type: application/xml

<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <permission>NONE</permission>
  <group>users</group>
  <operation>
    <shape>
      <tag>original</tag>
    </shape>
  </operation>
</AccessControlDocument>

To view the access controls that apply for an item, including any access controls inherited from parent collections or libraries, see Viewing applied access controls.

Access levels

The higher levels grants the permissions of the lower levels.

NONE
Grants no permissions whatsoever.
READ
Grants permission to read.
WRITE
Grants permission to write.
ALL
The highest level that grants permissions to perform operations such as item deletion.
OWNER
A specific case of ALL that is given by the system. This level cannot be added or removed.

Priority

The access control lists are sorted in order to determine which entry that applies to a given operation. The rule of thumb here is that if there’s a matching access control entry set on the item then that applies otherwise the item’s ancestor collections and libraries are traversed. Then the collection or library that grants the lowest access will apply. If no matching access control entry can be found, access will be denied.

Furthermore an access control entry that is more specific take precedence over an entry that is less specific. If two entries are determined equally specific then the entry that grants the highest access applies. An example of this is that an entry that restricts access for an items entire metadata is considered less specific than one that only restricts access for a certain field in the metadata.

The above can be illustrated by the priority list below:

  1. Controls with a high explicit priority take precedence over controls with lower explicit priority.
  2. Controls directly on the item take precedence over controls on ancestor collections and libraries.
  3. Controls that describe specific users take precedence over controls that describe groups.
  4. Controls that are more specific take precedence over controls that are less specific.
  5. If directly applied to an item:
    • Controls that grant more access take precedence over controls that give less access.
  6. If applied to an ancestor collection or library:
    • Controls that grant less access take precedence over controls that give more access.

An explicit priority can be assigned by setting the priority element in the AccessControlDocument to the desired level. The default is 0. Note that only superusers can create access controls with an explicit priority as users would otherwise be able to gain access to entities that they shouldn’t have.

Revoking access

The user that created an access control entry is also tracked. This is the grantor. It is also so that an entry is only valid if the grantor still has access to the entity. This means that access can be revoked by removing the original entry that granted access, or by disabling the grantor user without preserving access (see Disable a user).

For example, let’s assume that user A is the owner and grants READ access to user B, that in turn grants READ access to user C, as shown in the figure. Users A, B and C now all have read access. If the access control granting READ access to user B then the user C will no longer have access.

Operation

There are different types of operations that can be restricted using access control lists. Parameters are optional and makes the access control entry more specific. If no operation is specified then the entry will be considered generic and apply to the entire item.

URIs

Operation /item/ {item-id} /uri
Parameters type The type of the URI to restrict.

Example

<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <permission>READ</permission>
   <user>testuser</user>
   <operation>
      <uri>
        <type>lowres</type>
      </uri>
   </operation>
</AccessControlDocument>

Shapes

Operation /item/ {item-id} /shape
Parameters tag Restrict access to shapes with this tag.

Example

<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <permission>NONE</permission>
   <user>testuser</user>
   <operation>
      <shape>
        <tag>lowres</tag>
      </shape>
   </operation>
</AccessControlDocument>

Metadata

Operation /item/ {item-id} /metadata
Parameters field The name of the field to restrict.

Changed in version 5.0: Comma separated field names are supported in <field>.

Caution

Removal of fields are currently not restricted

Currently fields can be removed without checking the specific access control entry.

Example

<Accesscontroldocument Xmlns="http://xml.vidispine.com/schema/vidispine">
   <permission>READ</permission>
   <user>testuser</user>
   <operation>
      <metadata>
        <field>title</field>
      </metadata>
   </operation>
</AccessControlDocument>