Access control for items, libraries, collections [VC 21.3 GEN]

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. If there are multiple matching entries (i.e. match both the item and the operation being performed), following criteria are used to determine which entry applies, in order of most to least important:

1. Explicit Priority

   Controls with a high explicit priority take precedence over controls with lower explicit priority. An explicit priority can be assigned by setting the priority element in the AccessControlDocument to the desired level. The default is 0, and entries with a higher number override entries with lower value. 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.

2. Inheritance

   Controls directly on the item take precedence over entries inherited from ancestor collections or libraries. It is not differentiated where the entry is inherited from, e.g. whether it is through several ‘generations’ of collections, or immediately from a library.

3. User or Group

   Entries granted directly to users take precedence over entries granted via groups.

4. Operation Type

   Shape, Metadata, and Uri entries take precedence over Generic entries. For Metadata, entries with a specific field set takes precedence over general metadata entries.

5. Permission

   Controls that grant more access take precedence over controls that give less access.

If no matching entry is found access will be denied.

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

Example

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

Shapes

Example

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

Metadata

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

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>