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:
-
- 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.
-
- 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.
-
- User or Group
-
Entries granted directly to users take precedence over entries granted via groups.
-
- Operation Type
-
Shape
,Metadata
, andUri
entries take precedence overGeneric
entries. ForMetadata
, entries with a specific field set takes precedence over general metadata entries.
-
- 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
Operation |
| |
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 |
| |
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 |
| |
Parameters | field | The name of the field to restrict. |
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>