Document immutable roles (#2001)

Replaces #1984

---------

Co-authored-by: Phil Wright <[email protected]>

Author: renetapopova

modules/ROOT/content-nav.adoc

@@ -184,9 +184,9 @@
 *** xref:authentication-authorization/dbms-administration.adoc[]
 *** xref:authentication-authorization/load-privileges.adoc[]
 *** xref:authentication-authorization/limitations.adoc[]
-*** xref:authentication-authorization/privileges-immutable.adoc[]
 *** xref:authentication-authorization/manage-execute-permissions.adoc[]
 ** xref:authentication-authorization/built-in-roles.adoc[]
+** xref:authentication-authorization/immutable-roles-privileges.adoc[]
 ** Integration with auth systems
 *** xref:authentication-authorization/auth-providers.adoc[]
 *** xref:authentication-authorization/ldap-integration.adoc[]
@@ -246,7 +246,6 @@
 ** xref:tutorial/tutorial-composite-database.adoc[]
 ** xref:tutorial/access-control.adoc[]
 ** xref:tutorial/tutorial-sso-configuration.adoc[]
-** xref:tutorial/tutorial-immutable-privileges.adoc[]
 ** xref:tutorial/tutorial-clustering-docker.adoc[]
 
 // ** xref:clustering-advanced/index.adoc[]

modules/ROOT/images/privileges_grant_and_deny_syntax.svg

@@ -27,7 +27,7 @@ The components of the database privilege commands are:
 * _mutability_:
 ** `IMMUTABLE` - When used in conjunction with `GRANT` or `DENY`, specifies that a privilege cannot subsequently be removed unless auth is disabled.
 Contrastingly, when `IMMUTABLE` is specified in conjunction with a `REVOKE` command, it will act as a filter and only remove matching _immutable_ privileges.
-See also xref:authentication-authorization/privileges-immutable.adoc[].
+See also xref:authentication-authorization/immutable-roles-privileges.adoc[].
 
 * _database-privilege_
 ** `ACCESS` - allows access to a specific database or remote database alias.

modules/ROOT/pages/authentication-authorization/database-administration.adoc

@@ -0,0 +1,138 @@
+[role=enterprise-edition not-on-aura]
+[[immutable-roles-and-privileges]]
+= Immutable roles and privileges
+:description: This section explains how to use Cypher to manage immutable roles and privileges.
+
+
+Immutable privileges are useful for restricting the actions of users who can themselves administer xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[privileges]. 
+Starting with Neo4j 5.26, Neo4j also introduces immutable roles.
+Immutable roles are useful for providing _system roles_, which appear as permanent parts of the DBMS.
+
+
+[CAUTION]
+====
+Immutable privileges and roles should only be used in situations where changes are rare.
+They are intentionally difficult to modify, so changes should be undertaken with caution (e.g., when the DBMS has been isolated by some other means and unauthorized access can be reliably prevented).
+Typically, this type of modification should only be made once during the commissioning phase of a DBMS.
+====
+
+[[administer-immutable-roles-and-privileges]]
+== Administer immutable roles and privileges
+
+After the DBMS is safely isolated from external connections, follow these steps to administer immutable roles and privileges:
+
+. Change the config setting xref:configuration/configuration-settings.adoc#config_dbms.security.auth_enabled[`dbms.security.auth_enabled`] to `false`.
+. Restart the DBMS.
+. Create or remove immutable privileges and roles in the same way as regular privileges and roles but with the addition of the `IMMUTABLE` keyword.
+See <<immutable-roles-privileges-examples, Examples>>.
+. Change the config setting xref:configuration/configuration-settings.adoc#config_dbms.security.auth_enabled[`dbms.security.auth_enabled`] back to `true`.
+. Restart the DBMS.
+
+Privileges and roles created in this way now appear as an immutable part of the DBMS.
+If you want to change or remove them, you must repeat the process of setting xref:configuration/configuration-settings.adoc#config_dbms.security.auth_enabled[`dbms.security.auth_enabled`] to `false`.
+
+[[immutable-roles-privileges-examples]]
+== Examples
+
+The following examples demonstrate how to use Cypher to manage immutable roles and privileges.
+
+=== Restricting the actions of users who can manage privileges
+
+To prevent all users (including those with `PRIVILEGE MANAGEMENT` privileges) from performing *database management*, attach an immutable privilege to the `PUBLIC` role. 
+The `PUBLIC` role implicitly and irrevocably applies to all users. 
+
+. Ensure that you have completed steps 1 and 2 from <<administer-immutable-roles-and-privileges>>.
+. Run the following command to deny the `IMMUTABLE DATABASE MANAGEMENT` privilege to the `PUBLIC` role:
++
+[source, cypher, role=test-skip]
+----
+DENY IMMUTABLE DATABASE MANAGEMENT ON DBMS TO PUBLIC
+----
+
+. Verify that the `IMMUTABLE` keyword has been added to the privilege:
++
+[source, cypher, role=noplay]
+----
+SHOW PRIVILEGES WHERE IMMUTABLE
+----
++
+.Result
+[options="header,footer", width="100%", cols="1m,2m,1m,1m,1m,1m,1m"]
+|===
+|access
+|action
+|resource
+|graph
+|segment
+|role
+|immutable
+
+|"DENIED"
+|"database_management"
+|"database"
+|"*"
+|"database"
+|"PUBLIC"
+|true
+
+7+a|Rows: 2
+|===
++
+The result shows that all users are restricted from adding or removing privileges, including the `admin` user.
+. Ensure you have completed steps 4 and 5 from <<administer-immutable-roles-and-privileges>>.
+
+=== Creating permanent roles that cannot be changed
+
+You can use immutable roles to create permanent built-in system roles that cannot be modified even by users who have xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[`ROLE MANAGEMENT` privileges].
+
+For example, you want to create an `analyst` role that cannot be dropped, renamed, or have any of its privileges changed (even by users with the `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges).
+
+
+. Ensure that you have completed steps 1 and 2 from <<administer-immutable-roles-and-privileges>>.
+. Create an immutable role to hold the immutable privileges:
++
+[source, cypher, role=noplay]
+----
+CREATE IMMUTABLE ROLE analyst
+----
+
+. Immutably grant the `MATCH` privilege:
++
+[source, cypher, role=noplay]
+----
+GRANT IMMUTABLE MATCH {*} ON GRAPH * ELEMENTS * TO analyst
+----
+
+. Ensure you have completed steps 4 and 5 from <<administer-immutable-roles-and-privileges>>.
++
+Now, even users with `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges will not be able do any of the following:
++
+.Drop the `analyst` role
+[source, cypher, role=noplay]
+----
+DROP ROLE analyst
+----
++
+.Revoke the `MATCH` privilege from the `analyst` role
+[source, cypher, role=noplay]
+----
+REVOKE MATCH {*} ON GRAPH * ELEMENTS * FROM analyst
+----
++
+.Rename the `analyst` role
+[source, cypher, role=noplay]
+----
+RENAME ROLE analyst TO dataReader
+----
+
+[NOTE]
+====
+While the make-up (name, existence, associated privileges) of immutable roles is immutable, their assignment to users is not.
+This means that an immutable role can itself be granted to or revoked from a user by any user with `ROLE MANAGEMENT` privileges.
+====
+[NOTE]
+====
+Only immutable privileges (e.g. `GRANT IMMUTABLE MATCH {*} ON GRAPH * ELEMENTS * TO analyst` in the example above) can be assigned to immutable roles.
+This is to make sure that an immutable role and all of its privileges is explicitly and completely immutable.
+====
+

modules/ROOT/pages/authentication-authorization/immutable-roles-privileges.adoc

@@ -45,7 +45,11 @@ The components of the graph privilege commands are:
 ** `REVOKE` – removes granted or denied privileges from roles.
 
 * _mutability_:
-** `IMMUTABLE` can optionally be specified when performing a `GRANT` or `DENY` to indicate that the privilege cannot be subsequently removed unless auth is disabled. Auth must also be disabled in order to `GRANT` or `DENY` an immutable privilege. Contrastingly, when `IMMUTABLE` is specified in conjunction with a `REVOKE` command, it will act as a filter and only remove matching _immutable_ privileges. See also xref:authentication-authorization/privileges-immutable.adoc[].
+** `IMMUTABLE` can optionally be specified when performing a `GRANT` or `DENY` to indicate that the privilege cannot be subsequently removed unless auth is disabled.
+Auth must also be disabled in order to `GRANT` or `DENY` an immutable privilege.
+Contrastingly, when `IMMUTABLE` is specified in conjunction with a `REVOKE` command, it will act as a filter and only remove matching _immutable_ privileges.
+Starting from Neo4j 5.26, immutable privileges can also be used together with immutable roles.
+See xref:authentication-authorization/immutable-roles-privileges.adoc[] for more information.
 
 * _graph-privilege_:
 ** Can be either a xref:authentication-authorization/privileges-reads.adoc[read privilege] or xref:authentication-authorization/privileges-writes.adoc[write privilege].

modules/ROOT/pages/authentication-authorization/manage-privileges.adoc

@@ -62,7 +62,7 @@ GRANT SHOW ROLE
 ----
 
 
-(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges]).
+See xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[DBMS ROLE MANAGEMENT privileges].
 |===
 
 
@@ -140,7 +140,7 @@ a|
 GRANT SHOW PRIVILEGE
 ----
 
-(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges])
+See xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[DBMS PRIVILEGE MANAGEMENT privileges].
 
 |===
 
@@ -150,7 +150,7 @@ GRANT SHOW PRIVILEGE
 
 
 | Command
-m| CREATE ROLE
+m| CREATE [IMMUTABLE] ROLE
 
 | Syntax
 a|
@@ -339,7 +339,9 @@ For more information, see xref:authentication-authorization/dbms-administration.
 == Listing roles
 
 
-You can view all available roles using the Cypher command `SHOW ROLES`, which returns a single column.
+You can view all available roles using the Cypher command `SHOW ROLES`, which returns a single column by default.
+Starting from 5.26, you can optionally use `SHOW ROLES YIELD *` to see if the role is immutable.
+See <<access-control-immutable-roles, Immutable roles>> for more information.
 
 .`SHOW ROLES` output
 [options="header", width="100%", cols="2a,4,2m"]
@@ -351,6 +353,10 @@ You can view all available roles using the Cypher command `SHOW ROLES`, which re
 | role
 | Role name
 | STRING
+
+| immutable
+| `true` if the role is immutable, otherwise `false`.
+| BOOLEAN
 |===
 
 .List all roles
@@ -481,18 +487,18 @@ It is also possible to use `SKIP` and `LIMIT` to paginate the results.
 [[access-control-create-roles]]
 == Creating roles
 
-Roles can be created using `CREATE ROLE`:
+Roles can be created using `CREATE [IMMUTABLE] ROLE`:
 
 [source, syntax]
 ----
-CREATE ROLE name [IF NOT EXISTS] [AS COPY OF otherName]
+CREATE [IMMUTABLE] ROLE name [IF NOT EXISTS] [AS COPY OF otherName]
 ----
 
-Roles can be created or replaced by using `CREATE OR REPLACE ROLE`:
+Roles can be created or replaced by using `CREATE OR REPLACE [IMMUTABLE] ROLE`:
 
 [source, syntax]
 ----
-CREATE OR REPLACE ROLE name [AS COPY OF otherName]
+CREATE OR REPLACE [IMMUTABLE] ROLE name [AS COPY OF otherName]
 ----
 
 [NOTE]
@@ -504,7 +510,7 @@ The following naming rules apply:
 * Role names are case sensitive.
 ====
 
-A role can be copied, keeping its privileges, using `CREATE ROLE name AS COPY OF otherName`.
+A role can be copied, keeping its privileges, using `CREATE [IMMUTABLE] ROLE name AS COPY OF otherName`.
 
 .Copy a role
 ======
@@ -573,9 +579,19 @@ This is equivalent to running `DROP ROLE myrole IF EXISTS` followed by `CREATE R
 
 [NOTE]
 ====
-* The `CREATE OR REPLACE ROLE` command does not allow you to use the `IF NOT EXISTS`.
+The `CREATE OR REPLACE ROLE` command does not allow you to use the `IF NOT EXISTS`.
 ====
 
+[role=new-in-5.26]
+[[access-control-immutable-roles]]
+== Immutable roles
+
+Immutable roles are those that cannot be modified in the usual way.
+This means they cannot be created, renamed, dropped, or have privileges granted to or revoked from them under normal operating conditions.
+See xref:authentication-authorization/immutable-roles-privileges.adoc[Immutable roles and privileges] for details of when and how the `IMMUTABLE` keyword may be used.
+
+They are useful in cases where you need a permanent built-in system role that cannot be modified even by users who have xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[`ROLE MANAGEMENT` privileges] but yet can be granted to and revoked from users in the same way as an ordinary role.
+
 
 [[access-control-rename-roles]]
 == Renaming roles

modules/ROOT/pages/authentication-authorization/manage-roles.adoc

@@ -80,9 +80,10 @@ You can find more information in the xref:tools/cypher-shell.adoc[Cypher Shell s
 
 * Immutable privileges.
 +
-Immutable privileges are useful for restricting the actions of users who themselves are able to administer privileges. +
+Immutable privileges are useful for restricting the actions of users who themselves are able to administer privileges.
+Starting with Neo4j 5.26, immutable roles are also available. +
 Cloud operators can use sidecar design pattern to control RBAC-based permissions. +
-You can find xref:tutorial/tutorial-immutable-privileges.adoc[a tutorial] on how to administer immutable privileges.
+For more information, see xref:authentication-authorization/immutable-roles-privileges.adoc[Immutable roles and privileges].
 
 * Changes to Neo4j indexes
 ** The B-tree index type has been removed.

modules/ROOT/pages/authentication-authorization/privileges-immutable.adoc

@@ -11,5 +11,4 @@ The following step-by-step tutorials cover common operational tasks or otherwise
 * xref:tutorial/tutorial-composite-database.adoc[Set up and use a Composite database] -- This tutorial walks through the basics of setting up and using Composite databases.
 * xref:tutorial/access-control.adoc[Fine-grained access control (example)] -- This tutorial presents an example that illustrates various aspects of security and fine-grained access control.
 * xref:tutorial/tutorial-sso-configuration.adoc[Configuring Neo4j Single Sign-On (SSO)] -- This tutorial presents examples and solutions to common problems when configuring SSO.
-* xref:tutorial/tutorial-immutable-privileges.adoc[Administering immutable privileges] -- This tutorial describes methods for administering immutable privileges.
 * xref:tutorial/tutorial-clustering-docker.adoc[Deploy a Neo4j cluster in a Docker container] -- This tutorial walks through setting up a Neo4j cluster on your local computer for testing purposes.