Role-Based Access Control ========================= TrueNAS uses a role-based access control (RBAC) system to restrict which API methods a session may call. Roles are grouped into *privileges*, and privileges are linked to local or directory-service groups. When a user authenticates, the TrueNAS resolves that user's group memberships to a set of active roles, which are then checked against every API call the user makes. Privilege management is performed via the ``privilege.*`` API namespace (``privilege.create``, ``privilege.update``, ``privilege.delete``, ``privilege.query``). Role Concepts ------------- Individual roles (``builtin=true``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Individual roles are fine-grained roles attached directly to individual API methods. Examples: ``DISK_READ``, ``SHARING_SMB_WRITE``, ``ACCOUNT_READ``. Using custom privilege sets is deprecated and will be removed in TrueNAS 28. ``privilege.create`` and ``privilege.update`` reject an individual role, so a privilege may grant only the predefined group roles. TrueNAS raises a ``DeprecatedCustomPrivilege`` alert for every privilege that still grants one. Delete such a privilege to clear the alert. Predefined group roles (``builtin=false``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Predefined group roles are the four top-level roles surfaced in the UI and API for privilege assignment: * ``FULL_ADMIN`` * ``READONLY_ADMIN`` * ``SHARING_ADMIN`` * ``REPLICATION_ADMIN`` ``READONLY_ADMIN`` is the minimum role required for UI access. A privilege that grants only individual roles — without including at least ``READONLY_ADMIN`` — will not be sufficient to log in to the web interface. Use ``privilege.roles`` (filter ``builtin=false``) to retrieve the current list of predefined group roles at runtime. Role inclusion ~~~~~~~~~~~~~~ Roles can declare that they *include* other roles. Inclusion is expanded transitively, so a user assigned ``SHARING_ADMIN`` automatically gains all of the individual roles that ``READONLY_ADMIN`` expands into, plus the additional write roles specific to sharing. As a general convention, write roles include their corresponding read role. For example, ``ACCOUNT_WRITE`` includes ``ACCOUNT_READ``, so granting write access to a subsystem always implies read access to that same subsystem. Roles are additive and cannot be scoped down. There is no way to grant a role while simultaneously excluding a subset of what it includes — for example, it is not possible to assign ``FULL_ADMIN`` while blocking ``ACCOUNT_WRITE``. If finer-grained control is required, build a custom privilege from individual roles rather than starting from a broad predefined group role. Predefined Group Roles ---------------------- .. list-table:: :header-rows: 1 :widths: 20 40 40 * - Role - Description - Notable included roles * - ``FULL_ADMIN`` - Unrestricted access to all API methods - All roles * - ``READONLY_ADMIN`` - Read-only access across all subsystems - All ``*_READ`` individual roles * - ``SHARING_ADMIN`` - Manage datasets and all file-sharing protocols - ``READONLY_ADMIN`` + ``DATASET_WRITE`` + ``SHARING_WRITE`` + ``FILESYSTEM_ATTRS_WRITE`` + ``SERVICE_READ`` * - ``REPLICATION_ADMIN`` - Manage replication, snapshots, and keychain credentials - ``KEYCHAIN_CREDENTIAL_WRITE`` + ``REPLICATION_TASK_CONFIG_WRITE`` + ``REPLICATION_TASK_WRITE`` + ``SNAPSHOT_TASK_WRITE`` + ``SNAPSHOT_WRITE`` FULL_ADMIN ~~~~~~~~~~ ``FULL_ADMIN`` grants unrestricted access to every API method. It cannot be scoped down — a session holding this role may call any method regardless of what other roles are present or absent. The local ``root`` and ``truenas_admin`` accounts implicitly hold this privilege. Under GPOS STIG mode, any method not covered by a role becomes unreachable for *all* users. READONLY_ADMIN ~~~~~~~~~~~~~~ ``READONLY_ADMIN`` expands into every ``*_READ`` individual role defined in the system. A session with this role can call any ``*.query`` or ``*.get_instance`` endpoint and any other read-only method, but cannot create, update, or delete any resource or change any configuration. This role corresponds to the built-in ``READONLY_ADMINISTRATOR`` privilege. GPOS STIG has no effect on this role — all ``*_READ`` individual roles are GPOS-available. SHARING_ADMIN ~~~~~~~~~~~~~ ``SHARING_ADMIN`` is a superset of ``READONLY_ADMIN`` with additional write access scoped to storage and sharing: * Create, update, and delete ZFS datasets * Manage all file-sharing protocols: SMB, NFS, iSCSI, NVMe-oF, FTP, WebShare * Modify filesystem ACLs and other filesystem attributes * Read service status (but not change service settings) A session with ``SHARING_ADMIN`` *cannot* manage user accounts, system-level settings, network interfaces, storage pools, replication tasks, virtual machines, or applications. This role corresponds to the built-in ``SHARING_ADMINISTRATOR`` privilege. GPOS STIG has no effect on this role — all included roles are GPOS-available. REPLICATION_ADMIN ~~~~~~~~~~~~~~~~~ ``REPLICATION_ADMIN`` provides write access to the replication subsystem: * Replication tasks (push and pull) * Periodic snapshot tasks * ZFS snapshots * Keychain credentials (SSH keypairs and cloud credentials used by replication) A session with ``REPLICATION_ADMIN`` *cannot* manage datasets or pools directly, configure sharing protocols, manage user accounts, or change system settings. There is no built-in local group for ``REPLICATION_ADMIN``; it must be assigned through a custom privilege entry. GPOS STIG has no effect on this role — all included roles are GPOS-available. Individual Roles Reference -------------------------- The table below lists all individual roles available for use in custom privileges. Roles marked *unavailable under STIG* cannot be granted to any session when ``system.security`` has ``enable_gpos_stig=true``. .. list-table:: :header-rows: 1 :widths: 25 45 30 * - Subsystem - Roles - Notes * - Local Accounts - ``ACCOUNT_READ``, ``ACCOUNT_WRITE`` - * - API Keys - ``API_KEY_READ``, ``API_KEY_WRITE`` - ``API_KEY_WRITE`` unavailable under STIG * - Auth Sessions - ``AUTH_SESSIONS_READ``, ``AUTH_SESSIONS_WRITE`` - * - Boot Environments - ``BOOT_ENV_READ``, ``BOOT_ENV_WRITE`` - * - Certificates - ``CERTIFICATE_READ``, ``CERTIFICATE_WRITE`` - * - Cloud Backup - ``CLOUD_BACKUP_READ``, ``CLOUD_BACKUP_WRITE`` - * - Cloud Sync - ``CLOUD_SYNC_READ``, ``CLOUD_SYNC_WRITE`` - * - Containers / LXC - ``CONTAINER_READ``, ``CONTAINER_WRITE``, ``CONTAINER_DEVICE_READ``, ``CONTAINER_DEVICE_WRITE``, ``CONTAINER_IMAGE_READ``, ``CONTAINER_IMAGE_WRITE``, ``LXC_CONFIG_READ``, ``LXC_CONFIG_WRITE`` - All ``*_WRITE`` roles unavailable under STIG * - Dataset - ``DATASET_READ``, ``DATASET_WRITE``, ``DATASET_DELETE`` - * - Directory Services - ``DIRECTORY_SERVICE_READ``, ``DIRECTORY_SERVICE_WRITE`` - * - Disk - ``DISK_READ``, ``DISK_WRITE`` - * - Apps / Docker - ``APPS_READ``, ``APPS_WRITE``, ``CATALOG_READ``, ``CATALOG_WRITE``, ``DOCKER_READ``, ``DOCKER_WRITE`` - All ``*_WRITE`` roles unavailable under STIG * - Enclosure / JBOF - ``ENCLOSURE_READ``, ``ENCLOSURE_WRITE``, ``JBOF_READ``, ``JBOF_WRITE`` - * - Failover - ``FAILOVER_READ``, ``FAILOVER_WRITE`` - * - Filesystem - ``FILESYSTEM_ATTRS_READ``, ``FILESYSTEM_ATTRS_WRITE``, ``FILESYSTEM_DATA_READ``, ``FILESYSTEM_DATA_WRITE``, ``FILESYSTEM_FULL_CONTROL`` - * - IPMI - ``IPMI_READ``, ``IPMI_WRITE`` - * - Keychain Credentials - ``KEYCHAIN_CREDENTIAL_READ``, ``KEYCHAIN_CREDENTIAL_WRITE`` - * - KMIP - ``KMIP_READ``, ``KMIP_WRITE`` - * - Mail - ``MAIL_WRITE`` - * - Network - ``NETWORK_GENERAL_READ``, ``NETWORK_GENERAL_WRITE``, ``NETWORK_INTERFACE_READ``, ``NETWORK_INTERFACE_WRITE`` - * - Pool - ``POOL_READ``, ``POOL_WRITE``, ``POOL_SCRUB_READ``, ``POOL_SCRUB_WRITE`` - * - Privilege - ``PRIVILEGE_READ``, ``PRIVILEGE_WRITE`` - * - Replication - ``REPLICATION_TASK_CONFIG_READ``, ``REPLICATION_TASK_CONFIG_WRITE``, ``REPLICATION_TASK_READ``, ``REPLICATION_TASK_WRITE``, ``REPLICATION_TASK_WRITE_PULL`` - * - Reporting - ``REPORTING_READ``, ``REPORTING_WRITE`` - * - Services - ``SERVICE_READ``, ``SERVICE_WRITE`` - * - Sharing — FTP - ``SHARING_FTP_READ``, ``SHARING_FTP_WRITE`` - * - Sharing — iSCSI - ``SHARING_ISCSI_READ``, ``SHARING_ISCSI_WRITE``, ``SHARING_ISCSI_AUTH_READ``, ``SHARING_ISCSI_AUTH_WRITE``, ``SHARING_ISCSI_EXTENT_READ``, ``SHARING_ISCSI_EXTENT_WRITE``, ``SHARING_ISCSI_GLOBAL_READ``, ``SHARING_ISCSI_GLOBAL_WRITE``, ``SHARING_ISCSI_HOST_READ``, ``SHARING_ISCSI_HOST_WRITE``, ``SHARING_ISCSI_INITIATOR_READ``, ``SHARING_ISCSI_INITIATOR_WRITE``, ``SHARING_ISCSI_PORTAL_READ``, ``SHARING_ISCSI_PORTAL_WRITE``, ``SHARING_ISCSI_TARGET_READ``, ``SHARING_ISCSI_TARGET_WRITE``, ``SHARING_ISCSI_TARGETEXTENT_READ``, ``SHARING_ISCSI_TARGETEXTENT_WRITE`` - * - Sharing — NFS - ``SHARING_NFS_READ``, ``SHARING_NFS_WRITE`` - * - Sharing — NVMe-oF - ``SHARING_NVME_TARGET_READ``, ``SHARING_NVME_TARGET_WRITE`` - * - Sharing — S3 - ``SHARING_S3_READ``, ``SHARING_S3_WRITE`` - * - Sharing — SMB - ``SHARING_SMB_READ``, ``SHARING_SMB_WRITE`` - * - Sharing — WebShare - ``SHARING_WEBSHARE_READ``, ``SHARING_WEBSHARE_WRITE`` - * - Sharing (aggregate) - ``SHARING_READ``, ``SHARING_WRITE`` - Each expands into all ``SHARING_*_READ`` / ``SHARING_*_WRITE`` roles * - Snapshots - ``SNAPSHOT_READ``, ``SNAPSHOT_WRITE``, ``SNAPSHOT_DELETE``, ``SNAPSHOT_TASK_READ``, ``SNAPSHOT_TASK_WRITE`` - * - SSH - ``SSH_READ``, ``SSH_WRITE`` - * - Support - ``SUPPORT_READ``, ``SUPPORT_WRITE`` - * - System Audit - ``SYSTEM_AUDIT_READ``, ``SYSTEM_AUDIT_WRITE`` - * - System Settings - ``SYSTEM_ADVANCED_READ``, ``SYSTEM_ADVANCED_WRITE``, ``SYSTEM_CRON_READ``, ``SYSTEM_CRON_WRITE``, ``SYSTEM_GENERAL_READ``, ``SYSTEM_GENERAL_WRITE``, ``SYSTEM_PRODUCT_READ``, ``SYSTEM_PRODUCT_WRITE``, ``SYSTEM_SECURITY_READ``, ``SYSTEM_SECURITY_WRITE``, ``SYSTEM_TUNABLE_READ``, ``SYSTEM_TUNABLE_WRITE``, ``SYSTEM_UPDATE_READ``, ``SYSTEM_UPDATE_WRITE`` - * - TrueCommand - ``TRUECOMMAND_READ``, ``TRUECOMMAND_WRITE`` - ``TRUECOMMAND_WRITE`` unavailable under STIG * - TrueNAS Connect - ``TRUENAS_CONNECT_READ``, ``TRUENAS_CONNECT_WRITE`` - ``TRUENAS_CONNECT_WRITE`` unavailable under STIG * - Virtual Machines - ``VM_READ``, ``VM_WRITE``, ``VM_DEVICE_READ``, ``VM_DEVICE_WRITE`` - All ``*_WRITE`` roles unavailable under STIG * - ZFS Resources (filesystems, zvols) - ``ZFS_RESOURCE_READ``, ``ZFS_RESOURCE_WRITE``, ``ZFS_RESOURCE_DELETE`` - GPOS STIG Mode -------------- When ``system.security`` has ``enable_gpos_stig=true``, the GPOS STIG profile is active. Under this profile certain write roles become **unavailable**, meaning sessions that hold only those roles lose write access to the corresponding subsystems. The matching read roles remain available in all cases. The ``stig`` field in ``privilege.roles`` output indicates which STIG profiles permit a role. A value of ``null`` means the role is not permitted under any STIG profile; a non-null value identifies the profile(s) that allow it. .. list-table:: :header-rows: 1 :widths: 40 60 * - Unavailable role(s) - Affected area * - ``API_KEY_WRITE`` - API key management (``API_KEY_READ`` still permitted) * - ``VM_WRITE``, ``VM_DEVICE_WRITE`` - Virtual machines * - ``CONTAINER_WRITE``, ``CONTAINER_DEVICE_WRITE``, ``CONTAINER_IMAGE_WRITE``, ``LXC_CONFIG_WRITE`` - Containers and LXC * - ``DOCKER_WRITE`` - Docker back-end * - ``APPS_WRITE``, ``CATALOG_WRITE`` - Applications catalog * - ``TRUECOMMAND_WRITE`` - TrueCommand integration * - ``TRUENAS_CONNECT_WRITE`` - TrueNAS Connect cloud service For ``FULL_ADMIN`` specifically, see the note in the `FULL_ADMIN`_ section above. Managing Privileges ------------------- Use the following API methods to manage privileges: * ``privilege.create`` — create a new privilege and link it to one or more local or directory-service groups. Only the predefined group roles may be granted. * ``privilege.update`` — modify an existing privilege (change predefined group roles or group membership) * ``privilege.delete`` — remove a custom privilege * ``privilege.query`` — list all privileges, including the three built-in ones * ``privilege.roles`` — list all roles; pass ``[["builtin", "=", false]]`` as the filter argument to return only the predefined group roles * ``auth.me`` — returns the currently authenticated session, including the full list of roles that have been granted to it .. note:: **Enterprise license requirement.** Linking a privilege to a directory-service group (Active Directory or LDAP group) requires an Enterprise license. On Community Edition, privileges can only be assigned to local Unix groups. .. note:: **Secret field redaction.** API responses automatically redact fields marked ``secret`` in the schema (for example, credentials and passwords) for any session that does not hold the ``FULL_ADMIN`` role. Such fields are replaced with a redacted placeholder rather than being omitted, so the response structure remains consistent.