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.
