Access controls [VC 21.3 GEN]

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.

Query Parameters:	additionalUserInfo (boolean) – Set to `true` to return full user information instead of only username. Requires role _user_read. Default is `false`. (New in 5.3.1.) additionalGroupInfo (boolean) – Set to `true` to return full group information instead of only group name. Requires role _group_read. Default is `false`. (New in 5.3.1.)
Produces:	application/xml, application/json – AccessControlListDocument text/plain – CRLF-delimited list of ids
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:	application/xml, application/json – AccessControlDocument
Produces:	application/xml, application/json – AccessControlDocument text/plain – The id of the created entry.
Role:	_accesscontrol_write

Example

NONE

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.

Query Parameters:	additionalUserInfo (boolean) – Set to `true` to return full user information instead of only username. Requires role _user_read. Default is `false`. (New in 5.3.1.) additionalGroupInfo (boolean) – Set to `true` to return full group information instead of only group name. Requires role _group_read. Default is `false`. (New in 5.3.1.)
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:	application/xml, application/json – AccessControlDocument
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:	application/xml, application/json – AccessControlDocument
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:	application/xml, application/json – AccessControlListDocument
Produces:	application/xml, application/json – AccessControlListDocument text/plain – The ids of the created entries.
Role:	_accesscontrol_write

Example

NONE

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>

HTML/XML

<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:	application/xml, application/json – AccessControlListDocument
Role:	_accesscontrol_write

Example

NONE

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>

NONE

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:	application/xml, application/json – An ImportAccessControlListDocument
Role:	_import

Example

NONE

GET /import/access

HTML/XML

<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

NONE

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

NONE

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

NONE

DELETE import/access/group/mygroup

NONE

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 a list of all access control entries that affects each user for a given entity. This includes all access derived from the user’s group memberships, and from the entity’s inclusion in collections or libraries.

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 access element of the AccessControlMergedDocument includes the following fields:

username - The username of the user affected by the entry.
group - The group name if the entry is derived from access granted to a group.
collection/library - The collection name or library ID If the access is derived from the entity’s inclusion in a collection or library.

rank - The access entries for each user are ranked based on the criteria described in Access Control Priority. The matching entry with the lowest value for each user applies.

Changed in version 5.3: rank changed name from priority to avoid confusion with field of the same name in AccessControlDocument.

matches - This shows if the entry matches the operation specified by the type query parameter. If query parameters are not specified, the type defaults to GENERIC.
effectivePermission - The effective permission if it is different from the permission initially assigned to the entry. This might occur if the grantor’s permission is lower than the permission they assigned.
originalDisabledGrantor - Access can be inherited through a chain of multiple grantors. If the entry is disabled due to a disabled grantor, this shows the original grantor that needs to be re-enabled for the entry to be re-enabled.

The entries are listed grouped by user, in order of rank for each user.

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:	application/xml, application/json – An AccessControlMergedDocument containing all access control that affects the entity.
Role:	_accesscontrol_read

Example: retrieving all entries

NONE

GET /item/VX-1/merged-access

HTML/XML

<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <access rank="1" id="VX-100" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
  </access>
  <access rank="2" id="VX-101" username="admin">
    <permission>WRITE</permission>
    <type>GENERIC</type>
    <collection>VX-10</collection>
  </access>
  <access rank="4" id="VX-102" username="admin">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-12</collection>
  </access>
  <access rank="1" id="VX-103" username="testUser">
    <permission>READ</permission>
    <type>METADATA</type>
    <group>mygroup</group>
  </access>
  <access rank="2" id="VX-104" username="testUser">
    <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-1. Notice that the access provided by VX-101 is of type SHAPE, and so does not match the query for METADATA access. However, the rank of VX-101 is ranked lower than the access of VX-100 and thus the user has full access to the metadata.

NONE

GET /item/VX-1/merged-access?username=admin&permission=ALL&type=METADATA

HTML/XML

<AccessControlMergedDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <query>
    <username>admin</username>
    <permission>ALL</permission>
    <type>METADATA</type>
    <item>VX-1</item>
  </query>
  <access rank="1" matches="true" id="VX-100">
    <permission>ALL</permission>
    <type>GENERIC</type>
  </access>
  <access rank="2" matches="false" id="VX-101">
    <permission>WRITE</permission>
    <type>SHAPE</type>
    <collection>VX-10</collection>
  </access>
  <access rank="3" matches="true" id="VX-102">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-23</collection>
  </access>
  <access rank="4" matches="true" id="VX-103">
    <permission>ALL</permission>
    <type>GENERIC</type>
    <collection>VX-12</collection>
  </access>
  <access rank="5" matches="true" id="VX-104">
    <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. emptyGroups (boolean) – `true` - Include groups without users in the response. `false` (default) - Do not include groups without users in the response.
Produces:	application/xml, application/json – An AccessControlMergedGroupDocument.
Role:	_accesscontrol_read

Example

NONE

GET /item/VX-1000/merged-access/group

HTML/XML

<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