ACLs and Permissions Management¶
A user or group’s access rights to a file or folder in Nucleus are determined via their permissions. These permissions are defined using an Access Control List (ACL).
ACLs can make a project directory accessible only to the team working on it. They can also enable a user to protect their files from being changed by other users, but still be visible/readable to those same users.
There are 4 different levels of access:
These can apply to both folders and files. The tables below explain how ACLs affect user access.
View item in directory listing
Read/Reference file contents
List file Checkpoints
Read/Reference file Checkpoints
Navigate into directory
Add items to the directory
Modify file contents
Copy to 1
Move 1, 2
Rename 1, 2
1 These commands require ACLs 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 as the action directly modifies it. The action will fail when a destination does exist and/or the user does not have the required permission on the destination.
Minimum source ACL
Minimum destination ACL
2 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.
On initial server setup:
On creation of user home directory:
Note that a user will need to change the users permission if he/she wants to share content in home directory.
Nucleus assigns default ACLs to new directories and files. Note that the below mentioned gm group contains administrator user accounts.
The creator of the item and the gm group are given ADMIN ACL. The users group is not added at all, so the group will inherit permissions from parent directory structure.
Versions prior to Nucleus 2021.2.0
The creator of the item and the gm group are given ADMIN ACL. The users group is given READ and WRITE ACLs.
The GM Group “General Management”, is the group containing all users that have Administrator level permissions.
As this group is created automatically, these users will have the ability to:
Add and Remove users from Nucleus
Create, Delete, and Modify User Groups on Nucleus
Modify ACLs on any Nucleus path
Create root level directories or files on Nucleus
Delete, Rename, or Move any path on Nucleus
Operations & ACLs¶
ACLs are not copied from the source to the destination.
ACLs are copied to the destination - even if the operation overwrites an existing item.
ACLs are retained.
Permissions are inherited/recursive. If a directory item does not have an ACL specified for a user, the system 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 - and then apply that ACL on the directory item.
In the below example, Jane has created a project directory structure. The Project - 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 who is not in the gm group and is not Jane will have read only access to the
car.usd file because 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.
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.
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 to 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 that is only part of users will have read access.
Jane herself could be part of both the Jane’s Team and users group. She will still have admin access as that is the most permissive ACL.
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.
All administrators on the server 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.
Make sure to click Apply to commit 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 ACL.
In this example, Jane gave Bob the admin permission of a sub directory in her project. Bob then changed Jane’s permission to no access. Jane cannot move, rename, or delete the Project or Props directories because she does not have recursive admin ACL. Even if Bob allowed Jane read or write access, the move, rename, and delete actions would not be allowed.
Jane would need assistance from Bob or someone with an ADMIN account to provide access.