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: - application/xml, application/json – AccessControlListDocument
- text/plain – CRLF-delimited list of ids
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 istrue
.New in version 4.8.
Accepts: - application/xml, application/json – AccessControlDocument
Produces: - application/xml, application/json – AccessControlDocument
- text/plain – The id of the created entry.
Role: _accesscontrol_write
- allowDuplicate –
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: - application/xml, application/json – AccessControlDocument
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: - application/xml, application/json – AccessControlDocument
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: - application/xml, application/json – AccessControlListDocument
Produces: - application/xml, application/json – AccessControlListDocument
- text/plain – The ids of the created entries.
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: - application/xml, application/json – AccessControlListDocument
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: - application/xml, application/json – An ImportAccessControlListDocument
Role: _import
Example¶
GET /import/access
<ImportAccessControlListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<group>
<name>mygroup</name>
<permission>READ</permission>
</group>
</ImportAccessControlListDocument>
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¶
-
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.
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: - application/xml, application/json – An AccessControlMergedDocument containing all access control that affects the entity.
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: - application/xml, application/json – An AccessControlMergedGroupDocument.
Role: _accesscontrol_read
- full –
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
- type –
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
- type –