Immutable roles and privileges

Immutable privileges are useful for restricting the actions of users who can themselves administer 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.

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

After the DBMS is safely isolated from external connections, follow these steps to administer immutable roles and privileges:

Change the config setting 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 Examples.
Change the config setting 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 dbms.security.auth_enabled to false.

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:
```
DENY IMMUTABLE DATABASE MANAGEMENT ON DBMS TO PUBLIC
```
Verify that the IMMUTABLE keyword has been added to the privilege:
```
SHOW PRIVILEGES WHERE IMMUTABLE
```
Table 1. Result

access action resource graph segment role immutable

"DENIED"

"database_management"

"database"

"*"

"database"

"PUBLIC"

true

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.

Table 1. Result
access	action	resource	graph	segment	role	immutable
`"DENIED"`	`"database_management"`	`"database"`	`"*"`	`"database"`	`"PUBLIC"`	`true`
Rows: 2

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 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:
```
CREATE IMMUTABLE ROLE analyst
```

Immutably grant the MATCH privilege:

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
```
DROP ROLE analyst
```
Revoke the MATCH privilege from the analyst role
```
REVOKE MATCH {*} ON GRAPH * ELEMENTS * FROM analyst
```
Rename the analyst role
```
RENAME ROLE analyst TO dataReader
```

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.

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.