Access controls

Manage access to items, collections and libraries.

Managing access controls

In the following reference, {access-entity} is one of the following:

  • /item
  • /collection
  • /library

Retrieve the access control list for an entity

GET {access-entity}/(entity-id)/access

Retrieves the entire access control list for the specified entity.

Produces:
Role:

_accesscontrol_read

Create an access control entry

POST {access-entity}/(entity-id)/access

Adds a new access control entry for the specified entity.

Query Parameters:
 
  • allowDuplicate (boolean) – Set to false in order to avoid adding a duplicate access control. Default is true.
Accepts:
Produces:
  • application/xml, application/jsonAccessControlDocument
  • text/plain – The id of the created entry.
Role:

_accesscontrol_write

Example

POST /item/VX-123/access/
Content-Type: application/xml

<AccessControlDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <permission>READ</permission>
   <group>testGroup</group>
   <operation>
      <uri/>
   </operation>
</AccessControlDocument>

Retrieve an access control entry

GET {access-entity}/(entity-id)/access/(access-id)

Retrieves the desired access control entry.

Status Codes:
  • 404 Not found – No entry with that id exists in that entity.
Produces:
  • application/xml, application/json – An AccessControlDocument containing the requested access control entry.
  • text/plain – The id of the entry.
Role:

_accesscontrol_read

Delete an access control entry

DELETE {access-entity}/(entity-id)/access/(access-id)

Removes the desired access control entry.

Status Codes:
  • 200 OK – The entry was successfully removed.
  • 404 Not found – No entry with that id exists in that entity.
Role:

_accesscontrol_write

Add access control entries to all items

POST /item/access

Adds access control entries to all known items.

Accepts:
Role:

_administrator

Delete all access control entries from all items

DELETE /item/access

Deletes all access control entries from all known items.

Role:_administrator

Update the owner of an entity

PUT {access-entity}/(entity-id)/access/owner/(username)

Update the owner of the specified entity to the specified user.

Produces:
Role:

_administrator

Managing access controls in bulk

Create multiple entry access control entries

POST {access-entity}/(entity-id)/access/bulk

Adds multiple new access control entries to the specified entity.

Accepts:
Produces:
Role:

_accesscontrol_write

Example

POST /item/VX-123/access/bulk
Content-Type: application/xml

<AccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access>
    <permission>READ</permission>
    <group>testGroup</group>
    <operation>
      <uri/>
    </operation>
  </access>
  <access>
    <permission>READ</permission>
    <user>testUser</user>
  </access>
</AccessControlListDocument>
<AccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access id="VX-1043">
    <loc>http://localhost:8080/API/item/VX-123/access/VX-1043</loc>
    <grantor>admin</grantor>
    <appliesTo>all</appliesTo>
    <permission>READ</permission>
    <group>testGroup</group>
    <operation>
      <uri/>
    </operation>
  </access>
  <access id="VX-1044">
    <loc>http://localhost:8080/API/item/VX-123/access/VX-1044</loc>
    <grantor>admin</grantor>
    <appliesTo>all</appliesTo>
    <permission>READ</permission>
    <user>testUser</user>
  </access>
</AccessControlListDocument>

Delete multiple access control entries

DELETE {access-entity}/(entity-id)/access/bulk

Deletes multiple access control entries by id.

Accepts:
Role:

_accesscontrol_write

Example

DELETE /item/VX-123/access/bulk
Content-Type: application/xml

<AccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access id="VX-1043"/>
  <access id="VX-1044"/>
</AccessControlListDocument>
200 OK

Default access controls

Each user can specify what access control that will be applied to an imported item. The user importing the item will always be granted OWNER permissions.

List the default access controls for the current user

GET /import/access

Lists the access control list that will be applied on imported items.

Produces:
Role:

_import

Example

GET /import/access
<ImportAccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <group>
      <name>mygroup</name>
      <permission>READ</permission>
   </group>
</ImportAccessControlListDocument>

Add a group to the default access control list

PUT /import/access/group/(group-name)

Sets the permissions for a certain group.

Query Parameters:
 
  • permission (string) – Required. The level of permissions to grant the group.
Role:

_import

Example

PUT /import/access/group/mygroup?permission=READ
200 OK

Remove a group from the default access control list

DELETE /import/access/group/(group-name)

Removes the specified group from the default access control list.

Role:_import

Example

DELETE import/access/group/mygroup
200 OK

Viewing applied access controls

To review all access control entries that affects an item an AccessControlMergedDocument can be retrieved.

List the applied access control entries for an entity

GET {access-entity}/(entity-id)/merged-access/

Retrieves the access control entries that affects an item.

There are two modes of operation, either retrieving the access on the item for all users or querying for the access of a specific user. In the former case no parameters are specified and in the latter all parameters must be supplied.

The entries will be listed according to priority for every user. If the access is given through a group or a collection, the names and ids of those will be given.

If the effective access is different from the permission given by the access entry due to one or more grantors being disabled, the disabled grantors that the permission is derived from are listed listed in the originalDisabledGrantors field. The effective access may also be different for other reasons, for example if the grantor’s access has been revoked.

Query Parameters:
 
  • username (string) – The name of the user to check.
  • permission (string) – The lowest required permission level.
  • type (string) – The type of operation to check for.
  • extradata (string) – Any possible extradata.
Produces:
Role:

_accesscontrol_read

Example: retrieving all entries

GET /item/VX-250/merged-access
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access priority="1" id="VX-3111" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
  </access>
  <access priority="2" id="VX-24112" username="admin">
    <permission>WRITE</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access priority="3" id="VX-4119" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-23</collection>
  </access>
  <access priority="4" id="VX-2221" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-12</collection>
  </access>
  <access priority="5" id="VX-2205" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access priority="1" id="VX-24090" username="test">
    <permission>READ</permission>
    <type>METADATA</type>
    <group>mygroup</group>
  </access>
</AccessControlMergedDocument>

Example: querying about specific access

Checking if the user admin has full access to the metadata of item VX-250. Notice that the access provided by VX-24112 does not match, but it is less prioritized than the access of VX-3111 and thus the user has full access to the metadata.

GET /item/VX-250/merged-access?username=admin&permission=ALL&type=METADATA
<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <query>
    <username>admin</username>
    <permission>ALL</permission>
    <type>METADATA</type>
    <item>VX-250</item>
  </query>
  <access priority="1" matches="true" id="VX-3111">
    <permission>ALL</permission>
    <type>GENERIC</type>
  </access>
  <access priority="2" matches="false" id="VX-24112">
    <permission>WRITE</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access priority="3" matches="true" id="VX-4119">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-23</collection>
  </access>
  <access priority="4" matches="true" id="VX-2221">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-12</collection>
  </access>
  <access priority="5" matches="true" id="VX-2205">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
</AccessControlMergedDocument>

List the applied access control entries that affects groups

GET {access-entity}/(entity-id)/merged-access/group

Lists groups that have access to an entity.

Even though a user belongs to a group that has access to an entity, the user may not have access due to other access control entries that take precedence.

Groups without users will not appear, unless the group belongs to an inheritance hierarchy that has users.

Query Parameters:
 
  • full (boolean) –
    • true - Return all access controls that apply for a group. Also include additional information about the access controls in the response.
    • false (default) - Return a single access entry with the permission that applies for each group and type.
Produces:
Role:

_accesscontrol_read

Example

GET /item/VX-1000/merged-access/group
<AccessControlMergedGroupDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access>
    <group>groupA</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>_transcoder</group>
    <permission>WRITE</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>_special_all</group>
    <permission>WRITE</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>groupD</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>groupC</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
  <access>
    <group>groupB</group>
    <permission>READ</permission>
    <type>GENERIC</type>
  </access>
</AccessControlMergedGroupDocument>

Access visualization

In order to easily see the access control that apply for an entity there is a functionality to render the access control inheritance as a graph. In order to render the graph, the Graphviz package is required.

Retrieve the access graph

GET {access-entity}/(entity-id)/access/graph

Shows the entity and any ancestor collections or libraries and the access controls on each. The access-entity can be item or collection (library is not implemented).

Query Parameters:
 
  • type (string) –
    • ancestor - Show the entity and ancestor entities in a hierarchy.
    • grant - Show users and how permissions have been granted.
  • users (boolean) – If the user and group hierarchy should be shown as a subgraph for the relevant users/groups.
  • groups (boolean) – If groups should be shown as nodes in the grant graph.
Produces:
  • image/png
Role:

_administrator

Retrieve the access graph as dot file

GET {access-entity}/(entity-id)/access/graph/dot

Shows the entity and any ancestor collections or libraries and the access controls on each. The access-entity can be item or collection (library is not implemented).

Query Parameters:
 
  • type (string) –
    • ancestor - Show the entity and ancestor entities in a hierarchy.
    • grant - Show users and how permissions have been granted.
  • users (boolean) – If the user and group hierarchy should be shown as a subgraph for the relevant users/groups.
  • groups (boolean) – If groups should be shown as nodes in the grant graph.
Produces:
  • text/plain, text/vnd.graphviz
Role:

_administrator