Document immutable roles

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,146 @@
+[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.
+
+[NOTE]
+====
+Immutable roles are available starting with Neo4j 5.26.
+====
+
+Immutable privileges and roles are useful for restricting the actions of users who can themselves administer  xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[roles] xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[privileges].
+
+
+[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 can now appear to all users 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 the `admin` user, from performing *database management*, follow these steps:
+
+. Ensure that you have completed steps 1 an 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>>.
+
+=== Restricting the actions of users who can manage roles and privileges
+
+If you want permanent privileges but with more control over which users they apply to, you need to use immutable roles with immutable privileges.
+For example, you have a user called `alice` who has `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges.
+To prevent `alice` from dropping any databases and from being able to remove this restriction using their `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges, follow these steps:
+
+. Ensure that you have completed steps 1 an 2 from <<administer-immutable-roles-and-privileges>>.
+. Create an immutable role to hold the immutable privileges:
++
+[source, cypher, role=noplay]
+----
+CREATE IMMUTABLE ROLE restrictedAdmin
+----
+
+. Immutably deny the `DROP DATABASE` privilege:
++
+[source, cypher, role=noplay]
+----
+DENY IMMUTABLE DROP DATABASE ON DBMS TO restrictedAdmin
+----
+
+. Grant the restrictedAdmin role to `alice` to prevent her dropping databases:
++
+[source, cypher, role=noplay]
+----
+GRANT restrictedAdmin TO alice
+----
++
+. Ensure you have completed steps 4 and 5 from <<administer-immutable-roles-and-privileges>>.
++
+Now, despite having `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges, `alice` will not be able do any of the following:
++
+.Drop databases:
+[source, cypher, role=noplay]
+----
+DROP DATABASE foo
+----
++
+.Remove the restrictedAdmin role from `alice`
+[source, cypher, role=noplay]
+----
+REVOKE ROLE restrictedAdmin FROM alice
+----
++
+.Remove the `DROP DATABASE` privilege from the restrictedAdmin role
+[source, cypher, role=noplay]
+----
+DROP ROLE restrictedAdmin
+----
++
+.Remove `DENY DROP DATABASE` from the restrictedAdmin role
+[source, cypher, role=noplay]
+----
+REVOKE DENY DROP DATABASE ON DBMS FROM restrictedAdmin
+----
+
+[NOTE]
+====
+Only immutable privileges (e.g. `DENY IMMUTABLE DROP DATABASE` in the example above) can be assigned to immutable roles.
+This is to make sure that the 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.
+See xref:authentication-authorization/immutable-roles-privileges.adoc[Immutable roles and privileges] for details.
+
+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].
+
 
 [[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 vailable. +
 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.