Chapter 3. Authentication and authorization

This chapter describes authentication and authorization using the Neo4j HTTP API.

This chapter includes the following sections:

3.1. Introduction

Authentication and authorization are enabled by default in Neo4j (refer to Operations Manual → Enabling authentication and authorization). This means that requests to the HTTP API must be authorized using the username and password of a valid user.

When Neo4j is newly installed, the default user neo4j has the default password neo4j. The default password must be changed before access to resources will be permitted. See Section 3.8, “Changing the user password” for how to set a new password.

3.2. Authenticate to access the server

Authenticate by sending a username and a password to Neo4j using HTTP Basic Auth. Requests should include an Authorization header with a value of Basic <payload>, where payload is a base64-encoded string of username:password.

Example request

  • GET http://localhost:7474/user/neo4j
  • Accept: application/json; charset=UTF-8
  • Authorization: Basic bmVvNGo6c2VjcmV0

Example response

  • 200: OK
  • Content-Type: application/json;charset=utf-8
{
  "password_change_required" : false,
  "password_change" : "http://localhost:7474/user/neo4j/password",
  "username" : "neo4j"
}

3.3. Missing authorization

If an Authorization header is not supplied, the server will reply with an error.

Example request

  • GET http://localhost:7474/db/data/
  • Accept: application/json; charset=UTF-8

Example response

  • 401: Unauthorized
  • Content-Type: application/json;charset=utf-8
  • WWW-Authenticate: Basic realm="Neo4j"
{
  "errors" : [ {
    "code" : "Neo.ClientError.Security.Unauthorized",
    "message" : "No authentication header supplied."
  } ]
}

If authentication and authorization have been disabled, HTTP API requests can be sent without an Authorization header.

3.4. Incorrect authentication

If an incorrect username or password is provided, the server replies with an error.

Example request

  • POST http://localhost:7474/db/data/
  • Accept: application/json; charset=UTF-8
  • Authorization: Basic bmVvNGo6aW5jb3JyZWN0

Example response

  • 401: Unauthorized
  • Content-Type: application/json;charset=utf-8
  • WWW-Authenticate: Basic realm="Neo4j"
{
  "errors" : [ {
    "code" : "Neo.ClientError.Security.Unauthorized",
    "message" : "Invalid username or password."
  } ]
}

3.5. Required password changes

In some cases, for example the very first time Neo4j is accessed, the user will be required to choose a new password. The database will signal that a new password is required and deny access.

See Section 3.8, “Changing the user password” for how to set a new password.

Example request

  • GET http://localhost:7474/db/data/
  • Accept: application/json; charset=UTF-8
  • Authorization: Basic bmVvNGo6bmVvNGo=

Example response

  • 403: Forbidden
  • Content-Type: application/json;charset=utf-8
{
  "password_change" : "http://localhost:7474/user/neo4j/password",
  "errors" : [ {
    "code" : "Neo.ClientError.Security.Forbidden",
    "message" : "User is required to change their password."
  } ]
}

3.6. User status on first access

On first access, and using the default password, the user status will indicate that the users password requires changing.

Example request

  • GET http://localhost:7474/user/neo4j
  • Accept: application/json; charset=UTF-8
  • Authorization: Basic bmVvNGo6bmVvNGo=

Example response

  • 200: OK
  • Content-Type: application/json;charset=utf-8
{
  "password_change_required" : true,
  "password_change" : "http://localhost:7474/user/neo4j/password",
  "username" : "neo4j"
}

3.7. User status

Given that you know the current password, you can ask the server for the user status.

Example request

  • GET http://localhost:7474/user/neo4j
  • Accept: application/json; charset=UTF-8
  • Authorization: Basic bmVvNGo6c2VjcmV0

Example response

  • 200: OK
  • Content-Type: application/json;charset=utf-8
{
  "password_change_required" : false,
  "password_change" : "http://localhost:7474/user/neo4j/password",
  "username" : "neo4j"
}

3.8. Changing the user password

Given that you know the current password for a user, you can ask the server to change that user’s password. You can choose any password as long as it is different from the current password.

Example request

  • POST http://localhost:7474/user/neo4j/password
  • Accept: application/json; charset=UTF-8
  • Authorization: Basic bmVvNGo6bmVvNGo=
  • Content-Type: application/json
{
  "password" : "secret"
}

Example response

  • 200: OK