20.3. REST API Authentication and Authorization

In order to prevent unauthorized access to Neo4j, the REST API supports authorization and authentication. When enabled, requests to the REST API must be authorized using the username and password of a valid user. Authorization is enabled by default, see the section called “Server authentication and authorization” for how to disable it.

When Neo4j is first installed you can authenticate with the default user neo4j and the default password neo4j. However, the default password must be changed (see the section called “User status and password changing”) before access to resources will be permitted. This can easily be done via the Neo4j Browser, or via direct HTTP calls.

The username and password combination is local to each Neo4j instance. If you wish to have multiple instances in a cluster, you should ensure that all instances share the same credential. For automated deployments, you may also copy security configuration from another Neo4j instance (see the section called “Copying security configuration from one instance to another”).

Authenticating

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."
  } ]
}

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"
}

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."
  } ]
}

Required password changes

In some cases, like 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 the section called “User status and password changing” 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."
  } ]
}

User status and password changing

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"
}

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"
}

Changing the user password

Given that you know the current password, you can ask the server to change a users password. You can choose any password you like, 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 






Access when auth is disabled



When auth is disabled



When auth has been disabled in the configuration, requests can be sent without an Authorization header.


Example request


  • 

GET  http://localhost:7474/db/data/


  • 

Accept: application/json; charset=UTF-8




Example response


  • 

200: OK


  • 

Content-Type: application/json; charset=UTF-8




{
  "extensions" : { },
  "node" : "http://localhost:7474/db/data/node",
  "relationship" : "http://localhost:7474/db/data/relationship",
  "node_index" : "http://localhost:7474/db/data/index/node",
  "relationship_index" : "http://localhost:7474/db/data/index/relationship",
  "extensions_info" : "http://localhost:7474/db/data/ext",
  "relationship_types" : "http://localhost:7474/db/data/relationship/types",
  "batch" : "http://localhost:7474/db/data/batch",
  "cypher" : "http://localhost:7474/db/data/cypher",
  "indexes" : "http://localhost:7474/db/data/schema/index",
  "constraints" : "http://localhost:7474/db/data/schema/constraint",
  "transaction" : "http://localhost:7474/db/data/transaction",
  "node_labels" : "http://localhost:7474/db/data/labels",
  "neo4j_version" : "3.1.0-SNAPSHOT"
}






Copying security configuration from one instance to another



In many cases, such as automated deployments, you may want to start a Neo4j instance with pre-configured authentication and authorization.
This is possible by copying the auth database file from a pre-existing Neo4j instance to your new instance.


This file is located at data/dbms/auth, and simply copying that file into a new Neo4j instance will transfer your password and authorization token.