ACLs and Permissions Management#

A user or group’s access rights to a file or folder within Nucleus are determined by permissions. These permissions are defined using an Access Control List (ACL).

Setting proper ACLs make a directory accessible only to users working in it. ACLs can also enable users to protect their own files from being changed by others while still be usable/visible (read-only) to them.

Features#

There are 4 levels of access permissions:

No access
Read
Write
Admin

These can apply to both folders and files. The tables below explain how ACLs affect user access.

Access Levels#

Feature
View item in directory listing
Read/Reference file contents
List file checkpoints
Read/Reference file checkpoints
Navigate into directory
Download item
View permission
Add items to the directory
Modify file contents
Copy ¹
Move ^{1, 2}
Rename ^{1, 2}
Delete ²
Modify permissions

¹ These operations require proper permissions on both source and destination (i.e., if the action would result in overwriting a file). Move and Rename require admin access on the source (and destination) as the action directly modifies it.

Feature	Minimum source ACL	Minimum destination ACL
Copy
Move
Rename

² For an action to complete, it requires that ALL child items of a directory also provide admin access. If a user cannot delete a directory because he/she does not have recursive admin permissions, another user with the necessary ACLs or a user with an ADMIN account should be consulted.

Default ACLs#

The following are the default ACLs on a Nucleus Server:

Directory	users	gm
Server root
Server root/Library
Server root/Projects
Server root/Users

The following are the default ACLs on the creation of a user home directory:

Directory	users	user	gm
Server root/Users/[username]

Note

A user will need to change the users permission if he/she wants to share content within their home directory.

Nucleus assigns default ACLs to new directories and files. On the creation of a new directory or file, the creator of the item and the gm group are given ADMIN permissions. Group permissions for ‘users’ is not assigned at this level, so users will inherit permissions from a parent directory.

GM Group (General Management)#

The GM Group (General Management) is the group containing all users that have Administrator permissions.

This group is created automatically and allows the users within the ability to:

Add and Remove users

Create, Delete, and Modify user groups

Modify ACLs on any Nucleus path

Create root level files or directories

Delete, Rename, or Move files or directories

Locked Folders (Read-Only)#

Within Nucleus, directories displaying a red lock icon are read-only and cannot be modified.

File Operations and ACLs#

Copy - ACLs are not copied from the source to the destination.
Move - ACLs are copied to the destination even if the operation overwrites existing items.
Rename - ACLs are retained.

Inheritance#

Permissions are inherited/recursive. If a directory item does not have an ACL specified for a user, Nucleus will look upwards in the parent directory structure until an ACL is defined for the given user or a group the given user is in, then apply that ACL.

In the below example, Jane has created a project directory structure. The Project directory - and all items below it - have the admin permission assigned to gm and Jane. The Project directory also has read access for users. Any user not in the gm group and is not Jane will have read only access to the car.usd file as permission inheritance applies the read ACL from the Project directory.

The screenshot below shows the permissions structure on the Props subfolder of Project.

The screenshot below shows the permissions structure on the Cars subfolder of Props, which is a subfolder of Project.

In the following example, an ACL has been added to the Cars directory. A user in the users group has write access on that directory and the items below. The permissions inheritance stops once it finds an ACL for the user trying to access an item. Therefore, the read access on the Project directory is ignored for the Cars directory and its children.

Note

Nucleus permission inheritance does not function the same way as some similar systems do. While file/folder permissions are inherited from all parents, permissions are unioned for all memberships, and are resolved with the most permissive assigned and inherited attributes to determine the level of access granted.

User Groups#

Multiple users can be combined into groups by administrators (see Grant Admin Access).

For larger teams, it may be easier to manage permissions by using groups rather than individual users. As team memberships change over time, groups can be edited to reflect this change, thereby modifying access to directory items with set permissions.

See User Groups for more on how user groups can be managed.

Multi-ACL Evaluation#

One directory item can have many ACLs for a given user as ACLs can be associated with a user account and many groups at the same time.

In the below example, the ACL for Jane’s Team grants write access while the ACL for users only grants read access.

Nucleus permissions are resolved using the most permissive access given on an item. This means that a user that is part of both Jane’s Team and users will have write access. A user within users will only have read access.

Jane herself could be part of both the Jane’s Team and users group. She will have admin access as that is the most permissive access.

Denying Access#

In order to deny access, the ACL must be configured to not read, not write, and not admin access. This can be achieved by adding an ACL for the users group where no items are checked.

In the below example, the ACL for Jane’s Team grants write access while the ACL for users restricts to no access.

A recommended workflow is to start with providing no access to the users group. Then add more permissive ACLs for smaller groups and/or individual users.

In contrast, the below example will not provide desirable behavior. Users in Bob’s Team will still have read access because those users are also in the users group.

Note

If it’s required to block a user or group from a file or folder that inherits permissions from a parent folder, click the file or folder in question and assign a new set of permissions to it directly that explicitly blocks that user and/or group.

Assigning Permissions#

All Nucleus administrators and any user that has the Admin ACL for a given directory item, can modify permissions.

Select a directory or a file and click the Permissions tab in the detail panel.
To add a permission, start typing the name of a user or a user group in the Assign user/group field. Select an item from the list and click the plus/add icon.
Edit the access level by selecting between read, write, or admin. If no checkboxes are selected, then a no access ACL is applied.
Remove a user/group by clicking the remove icon next to the item in the Assigned users/groups list.
Click Apply to commit and enforce your changes.

The above example will permit the “admin” and “gm” group Admin access. “Jane’s Team” users will have Write access. All other users will have no access.

“Admin Takeover”#

In this example, Jane gave Bob admin permission of a sub directory in her project. Bob then changes Jane’s permission to no access. Jane cannot move, rename, or delete the Project or Props directories as she does not have recursive admin ACL. Even if Bob allowed Jane read or write access, the move, rename, and delete actions would still not be permitted.

Jane would require Bob or a user with administrative permissions to grant access.