.. raw:: html .. only:: internal .. |ACL_NO_ACCESS| image:: /content/images/nucleus_web_acls_no_access.png :align: middle :alt: NO_ACCESS .. |ACL_READ| image:: /content/images/nucleus_web_acls_read.png :align: middle :alt: READ .. |ACL_WRITE| image:: /content/images/nucleus_web_acls_write.png :align: middle :alt: WRITE .. |ACL_ADMIN| image:: /content/images/nucleus_web_acls_owner.png :align: middle :alt: ADMIN .. |YES| image:: /content/images/nucleus_web_acls_checkmark.png :align: middle :alt: YES .. |NO| image:: /content/images/nucleus_web_acls_checkmark_off.png :align: middle :alt: NO .. |DEFAULT_ACLS_110| image:: /content/images/nucleus_web_acls_default_110.png :align: middle :alt: Default ACLs Nucleus version 110 .. |DEFAULT_ACLS_111| image:: /content/images/nucleus_web_acls_default.png :align: middle :alt: Default ACLs Nucleus version 111 .. _RST_ACLs_And_Permissions: 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. Features -------- There are 4 different levels of access: - *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 |ACL_NO_ACCESS| |ACL_READ| |ACL_WRITE| |ACL_ADMIN| ================================================= ======================== ======================== ======================== ======================== View item in directory listing |NO| |YES| |YES| |YES| Read/Reference file contents |NO| |YES| |YES| |YES| List file Checkpoints |NO| |YES| |YES| |YES| Read/Reference file Checkpoints |NO| |YES| |YES| |YES| Navigate into directory |NO| |YES| |YES| |YES| Download item |NO| |YES| |YES| |YES| View permission |NO| |YES| |YES| |YES| Add items to the directory |NO| |NO| |YES| |YES| Modify file contents |NO| |NO| |YES| |YES| Copy to :superscript:`1` |NO| |NO| |YES| |YES| Move :superscript:`1, 2` |NO| |NO| |NO| |YES| Rename :superscript:`1, 2` |NO| |NO| |NO| |YES| Delete :superscript:`2` |NO| |NO| |NO| |YES| Change permissions |NO| |NO| |NO| |YES| ================================================= ======================== ======================== ======================== ======================== :superscript:`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. ================================================= ======================== ======================== Feature Minimum source ACL Minimum destination ACL ================================================= ======================== ======================== Copy |ACL_READ| |ACL_WRITE| Move |ACL_ADMIN| |ACL_WRITE| Rename |ACL_ADMIN| |ACL_WRITE| ================================================= ======================== ======================== :superscript:`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. Default ACLs ^^^^^^^^^^^^ On initial server setup: ================================================= ======================== ======================== Directory users gm ================================================= ======================== ======================== Server root |ACL_READ| |ACL_ADMIN| Server root/Library |ACL_WRITE| |ACL_ADMIN| Server root/Projects |ACL_WRITE| |ACL_ADMIN| Server root/Users |ACL_READ| |ACL_ADMIN| ================================================= ======================== ======================== On creation of user home directory: ================================================= ======================== ======================== ======================== Directory users user gm ================================================= ======================== ======================== ======================== Server root/Users/[username] |ACL_NO_ACCESS| |ACL_ADMIN| |ACL_ADMIN| ================================================= ======================== ======================== ======================== 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. :guilabel:`Nucleus 2021.2.0` 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. |DEFAULT_ACLS_111| :guilabel:`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. |DEFAULT_ACLS_110| .. note:: 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 ^^^^^^^^^^^^^^^^^ Copy ******* ACLs are not copied from the source to the destination. Move ******* ACLs are copied to the destination - even if the operation overwrites an existing item. Rename ******* ACLs are retained. Inheritance ^^^^^^^^^^^ 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. .. image:: /content/images/nucleus_web_acls_inheritance_proj.png :alt: ACL inheritance example proj The screenshot below shows the permissions structure on the *Props* subfolder of *Project*. .. image:: /content/images/nucleus_web_acls_inheritance_props.png :alt: ACL inheritance example props The screenshot below shows the permissions structure on the *Cars* subfolder of *Props*, which is a subfolder of *Project*. .. image:: /content/images/nucleus_web_acls_inheritance_cars.png :alt: ACL inheritance example cars 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. .. image:: /content/images/nucleus_web_acls_inheritance_3.png :alt: ACL inheritance example User Groups ^^^^^^^^^^^ Multiple users can be combined into groups by administrators (see :ref:`RST_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 :ref:`RST_User_Management_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 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. .. image:: /content/images/nucleus_web_acls_inheritance_2.png :alt: ACL inheritance example 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. .. image:: /content/images/nucleus_web_acls_no_access_example.png :alt: ACL no access example 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. .. image:: /content/images/nucleus_web_acls_no_access_example_bad.png :alt: ACL no access example .. 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 or group. Assigning Permissions --------------------- All administrators on the server and any user that has the *Admin* ACL for a given directory item, can modify permissions. 1. Select a directory or a file and click the *Permissions* tab in the detail panel. 2. 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. 3. Edit the access level by selecting between *read*, *write*, or *admin*. If no checkboxes are selected then a "No Access" ACL is applied. 4. Remove a user/group by clicking the *remove* icon next to the item in the "Assigned users/groups" list. 5. Make sure to click **Apply** to commit your changes. .. image:: /content/images/nucleus_web_assign_permission.png :align: center :alt: Nucleus Web Modify Group 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. "Admin Takeover" ^^^^^^^^^^^^^^^^^^^^ 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. .. image:: /content/images/nucleus_web_acls_owner_takeover.png :align: center :alt: Nucleus Web Modify Group Jane would need assistance from Bob or someone with an ADMIN account to provide access. .. only:: internal FUTURE FEATURE ACLs ------------------- .. note:: This section is for INTERNAL use only. Flagged with `internal` directive. :guilabel:`AFTER GENERAL AVAILABILITY` Access Levels ^^^^^^^^^^^^^^^^^^^^^^^ ================================================= ======================== ======================== ======================== ======================== Feature |ACL_NO_ACCESS| |ACL_READ| |ACL_WRITE| |ACL_ADMIN| ================================================= ======================== ======================== ======================== ======================== See item in directory listing |NO| |YES| |YES| |YES| Read/Reference file contents |NO| |YES| |YES| |YES| List file Checkpoints |NO| |YES| |YES| |YES| Read/Reference file Checkpoints |NO| |YES| |YES| |YES| Navigate into directory |NO| |YES| |YES| |YES| Download item |NO| |YES| |YES| |YES| View permission |NO| |YES| |YES| |YES| Add items to the directory |NO| |NO| |YES| |YES| Modify file contents |NO| |NO| |YES| |YES| Copy to :superscript:`1` |NO| |NO| |YES| |YES| :guilabel:`change` Move :superscript:`1` |NO| |NO| |YES| |YES| :guilabel:`change` Rename :superscript:`1` |NO| |NO| |YES| |YES| :guilabel:`change` Delete (Soft) |NO| |NO| |YES| |YES| :guilabel:`new` Obliterate :superscript:`2` |NO| |NO| |NO| |YES| Change permissions |NO| |NO| |NO| |YES| ================================================= ======================== ======================== ======================== ======================== :superscript:`1` These commands require ACLs on both `source` and `destination`. `Move` and `Rename` require `admin` ACL on source because the commands delete the source. The command will fail when a destination does exist and the user does not have the required ACL on the destination. ================================================= ======================== ======================== Feature Minimum source ACL Minimum destination ACL ================================================= ======================== ======================== Copy |ACL_READ| |ACL_WRITE| Move |ACL_READ| |ACL_WRITE| Rename |ACL_READ| |ACL_WRITE| ================================================= ======================== ======================== :superscript:`2` For command 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` ACL, another user with the necessary ACLs or a user with an ADMIN account, should be consulted.