updating to include immutable roles

Author: phil198

modules/ROOT/content-nav.adoc

@@ -184,7 +184,7 @@
 *** 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/privileges-and-roles-immutable.adoc[]
 *** xref:authentication-authorization/manage-execute-permissions.adoc[]
 ** xref:authentication-authorization/built-in-roles.adoc[]
 ** Integration with auth systems
@@ -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/pages/authentication-authorization/database-administration.adoc

@@ -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/privileges-and-roles-immutable.adoc[].
 
 * _database-privilege_
 ** `ACCESS` - allows access to a specific database or remote database alias.

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

@@ -45,7 +45,7 @@ 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. See also xref:authentication-authorization/privileges-and-roles-immutable.adoc[].
 
 * _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-roles.adoc

@@ -150,7 +150,7 @@ GRANT SHOW PRIVILEGE
 
 
 | Command
-m| CREATE ROLE
+m| CREATE [IMMUTABLE] ROLE
 
 | Syntax
 a|
@@ -339,7 +339,7 @@ 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. You can optionally use `SHOW ROLES YIELD *` to return the `IMMUTABLE` column. (See xref:authentication-authorization/manage-roles.adoc#access-control-immutable-roles[immutable roles] for more information).
 
 .`SHOW ROLES` output
 [options="header", width="100%", cols="2a,4,2m"]
@@ -351,6 +351,10 @@ You can view all available roles using the Cypher command `SHOW ROLES`, which re
 | role
 | Role name
 | STRING
+
+| immutable
+| Whether the role is immutable
+| BOOLEAN
 |===
 
 .List all roles
@@ -481,18 +485,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 +508,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
 ======
@@ -576,6 +580,11 @@ This is equivalent to running `DROP ROLE myrole IF EXISTS` followed by `CREATE R
 * The `CREATE OR REPLACE ROLE` command does not allow you to use the `IF NOT EXISTS`.
 ====
 
+[[access-control-immutable-roles]]
+=== Immutable roles
+Immutable roles are roles which cannot be modified in the usual way after they have been created. This means they cannot be renamed, dropped, or have privileges granted to or revoked from them. See xref:authentication-authorization/privileges-and-roles-immutable.adoc[here] for details.
+
+They are useful in cases where you need a permanent built-in system role which 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/privileges-and-roles-immutable.adoc

@@ -0,0 +1,147 @@
+[role=label--new-5.24]
+[role=enterprise-edition not-on-aura]
+[[access-control-privileges-immutable]]
+= Immutable privileges and roles
+:description: This section explains how to use Cypher to manage immutable privileges and roles.
+
+[NOTE]
+====
+Immutable roles are newly introduced in Neo4j 5.24. Immutable privileges have been available since Neo4j 5.0.
+====
+
+[[access-control-privileges-immutable-admin]]
+== How to administer immutable privileges and roles
+
+Unlike for regular privileges and roles, immutable privileges and roles cannot be administered by users with xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[PRIVILEGE MANAGEMENT] and xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[ROLE MANAGEMENT] privileges. Instead, they can only be administered when auth is disabled -- that is, when the configuration setting <<config_dbms.security.auth_enabled,`dbms.security.auth_enabled`>> is set to `false`.
+
+[CAUTION]
+It is intended that administering immutable privileges and roles is an extraordinarily rare scenario and one which should be undertaken with extreme caution (i.e. when the dbms has been isolated by some other means and unauthorized access can be reliably prevented). It is considered to be the kind of action which may be performed once during the commissioning phase of a database.
+
+When the configuration setting <<config_dbms.security.auth_enabled,`dbms.security.auth_enabled`>> is set to `false`, immutable privileges and roles can be administered in a similar way to regular privileges and roles, using the `IMMUTABLE` keyword.
+
+Once the dbms is safely isolated from external connections, follow these steps to administer immutable privileges and roles:
+
+. 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 xref:authentication-authorization/privileges-and-roles-immutable.adoc#access-control-privileges-immutable-usecase[here] for 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 will now appear to all users as an immutable part of the DBMS.
+The only way to subsequently change or remove them it would be to repeat the process of setting xref:configuration/configuration-settings.adoc#config_dbms.security.auth_enabled[`dbms.security.auth_enabled`] to `false`.
+
+
+[[access-control-privileges-immutable-usecase]]
+== When to use immutable privileges and roles
+
+Immutable privileges and roles are useful for restricting the actions of users who can themselves xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[administer privileges] and xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-role-management[roles].
+
+=== Immutable privileges
+
+You may want to prevent all users from performing Database Management, even the `admin` user (who are themselves able to add or remove privileges).
+To do so, it would not be adequate to run:
+
+[source, cypher]
+----
+DENY DATABASE MANAGEMENT ON DBMS TO PUBLIC
+----
+
+This is because the `admin` user could subsequently runs this:
+
+[source, cypher]
+----
+REVOKE DENY DATABASE MANAGEMENT ON DBMS FROM PUBLIC
+----
+
+They would then effectively regain Database Management privileges.
+
+Instead, you could use an immutable privilege.
+
+.Create an immutable privilege
+======
+
+[source, cypher, role=test-skip]
+----
+DENY IMMUTABLE DATABASE MANAGEMENT ON DBMS TO PUBLIC
+----
+[source, cypher, role=noplay]
+----
+SHOW PRIVILEGES WHERE IMMUTABLE
+----
+.Result
+[options="header,footer", width="100%", cols="m,m,m,m,m,m,m"]
+|===
+|access
+|action
+|resource
+|graph
+|segment
+|role
+|immutable
+
+|"DENIED"
+|"database_management"
+|"database"
+|"*"
+|"database"
+|"PUBLIC"
+|true
+
+7+a|Rows: 1
+|===
+
+======
+
+=== Immutable roles
+
+Immutable _privileges_ are useful when wanting to attach a permanent privilege to the `PUBLIC` role, which will apply to all users (because the `PUBLIC` role applies to all users).
+
+If you want permanent privileges, but with more control over which users they apply to, then you need to use immutable roles in conjunction with immutable privileges.
+
+For example you have a user called `alice` who also has `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges, but you want to prevent them from dropping any databases (and you want to prevent them from being able to simple remove this restriction using their `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges).
+
+.Create an immutable role
+======
+
+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
+----
+Now (despite having `ROLE MANAGEMENT` and `PRIVILEGE MANAGEMENT` privileges) alice will not be able do any of the following:
+[source, cypher, role=noplay]
+----
+DROP DATABASE foo
+----
+[source, cypher, role=noplay]
+----
+REVOKE ROLE restrictedAdmin FROM alice
+----
+[source, cypher, role=noplay]
+----
+DROP ROLE restrictedAdmin
+----
+[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/privileges-immutable.adoc

@@ -82,7 +82,7 @@ You can find more information in the xref:tools/cypher-shell.adoc[Cypher Shell s
 +
 Immutable privileges are useful for restricting the actions of users who themselves are able to administer privileges. +
 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.
+You can find more information xref:authentication-authorization/privileges-and-roles-immutable.adoc[here] on how to administer immutable privileges.
 
 * Changes to Neo4j indexes
 ** The B-tree index type has been removed.

modules/ROOT/pages/index.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.