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.

1. Disable authentication

  1. Stop Neo4j:

    $ bin/neo4j stop
  2. Open the neo4j.conf file and set dbms.security.auth_enabled parameter to false to disable the authentication:

    dbms.security.auth_enabled=false

    It is recommended to block network connections during the recovery phase, so users can connect to Neo4j only via localhost. This can be achieved by either:

    • Temporarily commenting out the dbms.default_listen_address parameter:

      #dbms.default_listen_address=<your_configuration>

    or

    • Providing the specific localhost value:

      dbms.default_listen_address=127.0.0.1
  3. Start Neo4j:

    $ bin/neo4j start
  1. Stop the cluster (all Core servers and Read Replicas).

    $ bin/neo4j stop
  2. On each Core server, open the neo4j.conf file and modify the following settings:

    1. Set dbms.security.auth_enabled parameter to false to disable the authentication:

      dbms.security.auth_enabled=false
    2. Disable the HTTP and HTTPS network connections and restrict the bolt connector to use only localhost. This ensures that no one from outside can access the cluster during the recovery period.

      #dbms.connector.http.enabled=true
      #dbms.connector.https.enabled=true
      dbms.connector.bolt.listen_address:127.0.0.1
  3. Start all Core servers:

    $ bin/neo4j start

2. Recover a lost password

You can use a client such as Cypher Shell or the Neo4j Browser to connect to the system database and set a new password for the admin user.

In a cluster deployment, you should complete the steps only on one of the Core servers.

  1. Complete the steps in Disable authentication as per your deployment.

  2. Connect to the system database using Cypher shell. Alternatively, log into Neo4j Browser.

    $ bin/cypher-shell -d system

    Cluster If you have specified a non-default port for your bolt connector, add -a neo4j://<your-core>:<non-default-bolt-port> to the cypher-shell command to be able to connect to your Core server.

  3. Set a new password for the admin user. In this example, the admin user is named neo4j.

    ALTER USER neo4j SET PASSWORD 'mynewpass'
  4. Exit the cypher-shell console:

    :exit;
  5. Proceed with the post-recovery steps as per your deployment.

3. Recover an unassigned admin role

You can use a client such as Cypher Shell or the Neo4j Browser to connect to the system database and grant the admin user role to an existing user.

In a cluster deployment, you should complete the steps only on one of the Core servers.

  1. Complete the steps in Disable authentication as per your deployment.

  2. Connect to the system database using Cypher shell. Alternatively, log into Neo4j Browser.

    $ bin/cypher-shell -d system

    Cluster If you have specified a non-default port for your bolt connector, add -a neo4j://<your-core>:<non-default-bolt-port> to the cypher-shell command to be able to connect to your Core server.

  3. Grant the admin user role to an existing user. In this example, the user is named neo4j.

    GRANT ROLE admin TO neo4j
  4. Exit the cypher-shell console:

    :exit;
  5. Proceed with the post-recovery steps as per your deployment.

4. Recover the admin role

If you have removed the admin role from your system entirely, you can use a client such as Cypher Shell or the Neo4j Browser to connect to the system database and recreate the role with its original capabilities (but without the ability to run admin procedures).

In a cluster deployment, you should complete the steps only on one of the Core servers.

  1. Complete the steps in Disable authentication as per your deployment.

  2. Connect to the system database using Cypher shell. Alternatively, log into Neo4j Browser.

    $ bin/cypher-shell -d system

    Cluster If you have specified a non-default port for your bolt connector, add -a neo4j://<your-core>:<non-default-bolt-port> to the cypher-shell command to be able to connect to your Core server.

  3. Recreate the admin role with its original capabilities.

    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;
  4. Grant the admin user role to an existing user.

    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 ROLE admin TO neo4j;

  5. Exit the cypher-shell console:

    :exit;
  6. Proceed with the post-recovery steps as per your deployment.

5. Post-recovery steps

  1. Stop Neo4j:

    $ bin/neo4j stop
  2. Enable the authentication and restore your Neo4j to its original configuration (See Disable authentication).

  3. Start Neo4j:

    $ bin/neo4j start
  1. Stop the Core servers.

    $ bin/neo4j stop
  2. Enable the authentication and restore each Core server to its original configuration (See Disable authentication).

  3. Start the cluster (all Core servers and Read Replicas):

    $ bin/neo4j start