Password and user recovery

This section describes how to recover from a lost password, specifically for an admin user, how to recover an admin user if all the admin users have been unassigned the admin role, and how to recreate the built-in admin role if it has been dropped.

It is recommended to block network connections during the recovery phase, so users should connect to Neo4j only via localhost. This can be achieved by editing the neo4j.conf file.

You can temporarily comment out the dbms.connectors.default_listen_address parameter:

#dbms.connectors.default_listen_address=<your_configuration>

or provide the specific localhost value:

dbms.connectors.default_listen_address=127.0.0.1

1. Recover a lost password

Use the following steps to set a new password (assuming your admin user is named neo4j):

  1. Stop Neo4j:

    $ bin/neo4j stop
  2. Disable the dbms.security.auth_enabled parameter by modifying the neo4j.conf file:

    dbms.security.auth_enabled=false
  3. Start Neo4j:

    $ bin/neo4j start
  4. Modify the admin user password using a client such as Cypher Shell, or the Neo4j Browser:

    • Connect to the system database via Cypher Shell, and modify the admin user password:

      $ bin/cypher-shell -d system
      
      neo4j@system> ALTER USER neo4j SET PASSWORD 'mynewpass';
      
      neo4j@system> :exit
    • Alternatively, you can run the following statement on the system database via another client, such as the Neo4j Browser:

      ALTER USER neo4j SET PASSWORD 'mynewpass';
  5. Stop Neo4j:

    $ bin/neo4j stop
  6. Enable the dbms.security.auth_enabled parameter by modifying the neo4j.conf file.

    You can achieve this either by commenting out dbms.security.auth_enabled (the default value is true), or by specifically setting dbms.security.auth_enabled to true:

    #dbms.security.auth_enabled=false

    or,

    dbms.security.auth_enabled=true
  7. Restart Neo4j:

    $ bin/neo4j start

2. Recover an unassigned admin role

If you have no user assigned to the admin role, you can grant an admin role to an existing user (assuming your existing user is named neo4j):

  1. Stop Neo4j:

    $ bin/neo4j stop
  2. Disable the dbms.security.auth_enabled parameter by modifying the neo4j.conf file:

    dbms.security.auth_enabled=false
  3. Start Neo4j:

    $ bin/neo4j start
  4. Grant the admin user role to an existing user using a client such as Cypher Shell, or the Neo4j Browser:

    • Connect to the system database via Cypher Shell, and grant the admin user role to an existing user:

      $ bin/cypher-shell -d system
      
      neo4j@system> GRANT admin TO neo4j;
      
      neo4j@system> :exit
    • Alternatively, you can run the following statement on the system database via another client, such as the Neo4j Browser:

      GRANT admin TO neo4j;
  5. Stop Neo4j:

    $ bin/neo4j stop
  6. Enable the dbms.security.auth_enabled parameter by modifying the neo4j.conf file.

    You can achieve this either by commenting out dbms.security.auth_enabled (the default value is true), or by specifically setting dbms.security.auth_enabled to true:

    #dbms.security.auth_enabled=false

    or,

    dbms.security.auth_enabled=true
  7. Restart Neo4j:

    $ bin/neo4j start

3. Recover the admin role

If you have removed the admin role from your system entirely, you can recreate the role with its original capabilities (but minus the ability to run admin procedures) by following these steps:

  1. Stop Neo4j:

    $ bin/neo4j stop
  2. Disable the dbms.security.auth_enabled parameter by modifying the neo4j.conf file:

    dbms.security.auth_enabled=false
  3. Start Neo4j:

    $ bin/neo4j start
  4. Create a custom admin role using a client such as Cypher Shell, or the Neo4j Browser:

    • Connect to the system database via Cypher Shell, and grant the admin user role to an existing user:

      $ bin/cypher-shell -d system
      
      neo4j@system> CREATE ROLE admin;
      neo4j@system> GRANT ALL DBMS PRIVILEGES ON DBMS TO admin;
      neo4j@system> GRANT TRANSACTION MANAGEMENT ON DATABASE * TO admin;
      neo4j@system> GRANT START ON DATABASE * TO admin;
      neo4j@system> GRANT STOP ON DATABASE * TO admin;
      neo4j@system> GRANT MATCH {*} ON GRAPH * TO admin;
      neo4j@system> GRANT WRITE ON GRAPH * TO admin;
      neo4j@system> GRANT ALL ON DATABASE * TO admin;
      
      neo4j@system> :exit

      Before running the :exit command, we suggest granting the newly created role to a user. Although this is optional, without this step you will have only collected all admin privileges in a role that no one is assigned to.

      To grant the role to a user (assuming your existing user is named neo4j), you can run GRANT admin TO neo4j;

    • Alternatively, you can run the following statement on the system database via another client, such as the Neo4j Browser:

      CREATE ROLE admin;
      GRANT ALL DBMS PRIVILEGES ON DBMS TO admin;
      GRANT TRANSACTION MANAGEMENT ON DATABASE * TO admin;
      GRANT START ON DATABASE * TO admin;
      GRANT STOP ON DATABASE * TO admin;
      GRANT MATCH {*} ON GRAPH * TO admin;
      GRANT WRITE ON GRAPH * TO admin;
      GRANT ALL ON DATABASE * TO admin;

      Before exiting your client, we suggest granting the newly created role to a user. Although this is optional, without this step you will have only collected all admin privileges in a role that no one is assigned to.

      To grant the role to a user (assuming your existing user is named neo4j), you can run GRANT admin TO neo4j;

  5. Stop Neo4j:

    $ bin/neo4j stop
  6. Enable the dbms.security.auth_enabled parameter by modifying the neo4j.conf file.

    You can achieve this either by commenting out dbms.security.auth_enabled (the default value is true), or by specifically setting dbms.security.auth_enabled to true:

    #dbms.security.auth_enabled=false

    or,

    dbms.security.auth_enabled=true
  7. Restart Neo4j:

    $ bin/neo4j start