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.
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
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
element is not set, access is granted to self and all decedent entities.
New in version 4.17.7.
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.
The higher levels grants the permissions of the lower levels.
- Grants no permissions whatsoever.
- Grants permission to read.
- Grants permission to write.
- The highest level that grants permissions to perform operations such as item deletion.
- A specific case of ALL that is given by the system. This level cannot be added or removed.
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
priorityelement 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.
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
Urientries take precedence over
Metadata, entries with a specific field set takes precedence over general metadata entries.
Controls that grant more access take precedence over controls that give less access.
If no matching entry is found access will be denied.
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.
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.
|Parameters||type||The type of the URI to restrict.|
<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <permission>READ</permission> <user>testuser</user> <operation> <uri> <type>lowres</type> </uri> </operation> </AccessControlDocument>
|Parameters||tag||Restrict access to shapes with this tag.|
<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine"> <permission>NONE</permission> <user>testuser</user> <operation> <shape> <tag>lowres</tag> </shape> </operation> </AccessControlDocument>
|Parameters||field||The name of the field to restrict.|
Changed in version 5.0: Comma separated field names are supported in
Removal of fields are currently not restricted
Currently fields can be removed without checking the specific access control entry.
<Accesscontroldocument Xmlns="http://xml.vidispine.com/schema/vidispine"> <permission>READ</permission> <user>testuser</user> <operation> <metadata> <field>title</field> </metadata> </operation> </AccessControlDocument>