Merge branch 'dev' into 5.x-merge-dev

Author: renetapopova

antora.yml

@@ -7,7 +7,7 @@ nav:
 asciidoc:
   attributes:
     neo4j-version: '5'
-    neo4j-version-minor: '5.25'
-    neo4j-version-exact: '5.25.1'
-    neo4j-buildnumber: '5.25'
+    neo4j-version-minor: '5.26'
+    neo4j-version-exact: '5.26.0'
+    neo4j-buildnumber: '5.26'
     neo4j-debian-package-version: '1:5.22.0@'

modules/ROOT/content-nav.adoc

@@ -125,6 +125,7 @@
 *** xref:database-administration/composite-databases/querying-composite-databases.adoc[]
 *** xref:database-administration/composite-databases/sharding-with-copy.adoc[]
 ** xref:database-administration/syntax.adoc[]
+** xref:database-administration/routing-decisions.adoc[]
 
 * xref:database-internals/index.adoc[]
 ** xref:database-internals/transaction-management.adoc[]
@@ -183,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[]
@@ -236,20 +237,17 @@
 *** xref:tools/neo4j-admin/validate-config.adoc[]
 ** xref:tools/cypher-shell.adoc[]
 
+* xref:procedures.adoc[]
+
 * xref:tutorial/index.adoc[]
 //** xref:tutorial/local-causal-cluster.adoc[]
 //** xref:tutorial/causal-backup-restore-db.adoc[]
 ** xref:tutorial/neo4j-admin-import.adoc[]
 ** 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[]
 
-* Appendix
-** xref:reference/procedures.adoc[]
-** xref:routing-decisions.adoc[]
-
 // ** xref:clustering-advanced/index.adoc[]
 // *** xref:clustering-advanced/lifecycle.adoc[]
 // *** xref:clustering-advanced/multi-data-center/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

@@ -65,7 +65,7 @@ this LDAP group will fail authentication, even if their credentials are correct.
 |===
 
 All settings are defined at server startup time in the default configuration file _xref:configuration/neo4j-conf.adoc[neo4j.conf]_ or can be modified at
-runtime using xref:reference/procedures.adoc#procedure_dbms_setconfigvalue[`dbms.setConfigValue()`].
+runtime using xref:procedures.adoc#procedure_dbms_setconfigvalue[`dbms.setConfigValue()`].
 
 
 [[auth-ldap-configure-provider]]

modules/ROOT/pages/authentication-authorization/ldap-integration.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

@@ -97,4 +97,33 @@ The role `regularUsers` does not need to have `READ` privilege for the property
 [source, syntax, role="noheader"]
 ----
 DENY READ {*} ON GRAPH * FOR (n) WHERE NOT n.classification IN ['UNCLASSIFIED', 'PUBLIC'] TO regularUsers
-----
+----
+
+.Granting permission to `READ` all properties on nodes where the property `createdAt` is later than the current date to role `regularUsers`:
+[source, syntax, role="noheader"]
+----
+GRANT READ {*} ON GRAPH * FOR (n) WHERE n.createdAt > date() TO regularUsers
+----
+[NOTE]
+====
+The `date()` function is evaluated, and the value used to evaluate the privilege is the date when the property-based privilege is created.
+Keep this in mind when designing your property rules, and use the `SHOW PRIVILEGES AS COMMANDS` command to check the stored value.
+This is essential when revoking property-based privileges containing evaluated function values like `date()`.
+====
+[NOTE]
+====
+Not all temporal values are comparable, see link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/syntax/operators/#cypher-ordering[Cypher Manual -> Syntax -> Operators -> Ordering and comparison of values].
+====
+
+.Show the privilege created by the command in the previous example as a revoke command:
+[source, syntax, role="noheader"]
+----
+SHOW ROLE regularUsers PRIVILEGES AS REVOKE COMMANDS
+----
+.Result
+[options="header,footer", width="100%", cols="m"]
+|===
+|command
+|"REVOKE GRANT READ {*} ON GRAPH * FOR (n) WHERE n.createdAt > date('2024-10-25') FROM `regularUsers`"
+a|Rows: 1
+|===