Access controls

Managing access controls

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

  • /item
  • /collection
  • /library

Retrieve 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

Add a new entry access control entry

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

Adds a new access control entry for the specified entity.

Query Parameters:
 
  • allowDuplicate

    Set to false in order to avoid adding a duplicate access control, default is true.

    New in version 4.8.

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 a specific 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 a specific 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

Remove all access control entries from all items

DELETE /item/access/

Deletes all access control entries from all known items.

Role:_administrator

Change the owner of an entity

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

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

Produces:
Role:

_administrator

New in version 4.10.

Managing access controls in bulk

Add multiple new 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>
    <recursive>true</recursive>
    <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>
    <recursive>true</recursive>
    <permission>READ</permission>
    <user>testUser</user>
  </access>
</AccessControlListDocument>

Delete multiple access control entries

DELETE {access-entity}/(item-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 – 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.

Retrieve a list of applied access control entries

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.

GET {access-entity}/(entity-id)/merged-access/
Query Parameters:
 
  • username – The name of the user to check.
  • permission – The lowest required permission level.
  • type – The type of operation to check for.
  • extradata – Any possible extradata.
Produces:
Role:

_accesscontrol_read

Example: retrieving all entries

GET /item/VX-250
<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>

Retrieve a list of 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
    • 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.

    New in version 4.2.3.

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.

Get 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
    • ancestor - Show the entity and ancestor entities in a hierarchy.
    • grant - Show users and how permissions have been granted.
  • users – If the user and group hierarchy should be shown as a subgraph for the relevant users/groups.
  • groups – If groups should be shown as nodes in the grant graph.
Produces:
  • image/png
Role:

_administrator

Get 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
    • ancestor - Show the entity and ancestor entities in a hierarchy.
    • grant - Show users and how permissions have been granted.
  • users – If the user and group hierarchy should be shown as a subgraph for the relevant users/groups.
  • groups – If groups should be shown as nodes in the grant graph.
Produces:
  • text/plain, text/vnd.graphviz
Role:

_administrator