Authentication and authorization

This section describes breaking changes and deprecations for the Neo4j authentication and authorization.

Removal of flat files for authentication and authorization

Neo4j 3.x manages authentication and authorization in flat files.

Neo4j 4.0 introduces a complex security model stored in the system graph, maintained in a special database called the system database. The contents of both the auth and roles files are automatically migrated to the system database. If you are bringing multiple databases together from multiple Neo4j 3.5 deployments or upgrading a cluster, you must manually merge the auth and role files before the migration.

The neo4j-admin commands set-initial-password and set-default-admin continue to work in version 4.0 and write to the same files as in 3.5. Any content in these files is considered on the first start of Neo4j after installing the new version.

The command set-initial-password is applied only if the default user neo4j with the default password is the only user present, while set-default-admin will only be used when no roles are present. For more information, see Operation Manual 4.0 → Set an initial password.

Role-based access control

Neo4j 3.1 introduced the concept of role-based access control. It was possible to create users and assign them to roles to control whether they could read, write, and administer the database. In Neo4j 4.0, this model is enhanced significantly with the addition of privileges, which are the underlying access-control rules by which the users' rights are defined.

It is still possible to have different security configurations per database after the migration, but this needs to be managed through the granting of privileges and roles specific to databases after the migration. The built-in roles from 3.5 still exist but will apply to all databases after the migration unless explicitly modified using the new security administration commands. The ability to manage database-specific roles and privileges is described in more detail in Cypher^® Manual 4.0 → Administration.

It is no longer possible to have different security privileges on different instances of a cluster. The entire cluster shares the privileges configured in the system database using Cypher administration commands. In practice, this means that users have the same privileges regardless of which server in a cluster they access.

Deprecated and removed security procedures

The built-in security procedures for user management dbms.security in Neo4j 3.x are deprecated in 4.x. If you still want to use them, they must be run against the system database and cannot be followed by YIELD.

There are two options for rewriting your code and routines for managing authentication and authorization.

(Recommended) Rewrite the procedures to the corresponding Cypher administration commands, using the xref: version-4/migration/surface-changes/auth.adoc#convert-security-procedures-table[conversion table]. All administrative commands must be executed against the system database. When connected to the DBMS using the Neo4j Drivers (Bolt Protocol), administrative commands are automatically routed to the system database (Neo4j 4.1+).
Run the procedures against the system database and replace any YIELD parts by post-processing on the application side.

The procedure dbms.security.changePassword(password, requirePasswordChange) has been entirely removed since the corresponding Cypher administration command also requires the old password, and thus is more secure.

Table 1. Procedure to Cypher administrative command conversion
Procedure	Administration command
`dbms.security.createUser`	`CREATE USER`
`dbms.security.deleteUser`	`DROP USER`
`dbms.security.changePassword`	`ALTER CURRENT USER SET PASSWORD`
`dbms.security.listUsers`	`SHOW USERS`
`dbms.security.changeUserPassword`	`ALTER USER`
`dbms.security.suspendUser`	`ALTER USER`
`dbms.security.activateUser`	`ALTER USER`
`dbms.security.addRoleToUser`	`GRANT ROLE TO USER`
`dbms.security.removeRoleFromUser`	`REVOKE ROLE FROM USER`
`dbms.security.listRoles`	`SHOW ROLES`
`dbms.security.listRolesForUser`	`SHOW USERS`
`dbms.security.listUsersForRole`	`SHOW ROLES WITH USERS`
`dbms.security.createRole`	`CREATE ROLE`
`dbms.security.deleteRole`	`DROP ROLE`

For more info about the administration commands, see Cypher Manual 4.0 → User and role management.