Token-based authentication is new in Neo4j 2.2, but how does it work?
The first thing to know is that it is enabled by default in conf/neo4j-server.properties by:
# Require (or disable the requirement of) auth to access Neo4j
dbms.security.auth_enabled=true
To understand the implementation, the main place to look is the org.neo4j.server.security.auth package which has some key interfaces, chiefly UserRepository, implemented by FileUserRepository (which stores salted, SHA-256 hashed credentials in data/dbms/auth) and an InMemoryUserRepository for testing. The FileUserRepository also includes a password change required field, a record that needs to change the password looks like:
foobar:SHA-256,253F558188A14B66FB2CCF8C1C75509CC9403E7276B3F1E275F6B13D0D45E730,35F68B1D6C8524CD32AFF1DF7C42F515:password_change_required
AuthManager is responsible for handling username/password authentication and will invoke the creation of the initial neo4j/neo4j user on startup if the UserRepository returns the numberOfUsers as 0.
In terms of setup, org.neo4j.server.modules.AuthorizationModule adds an
org.neo4j.server.rest.dbms.AuthorizationFilter to intercept all requests, it obtains credentials from the HTTP Authorization header by decoding the base64 encoded username:password.
The API includes rate limiting via RateLimitedAuthenticationStrategy to prevent brute-force repeated logon attempts from being processed.
How are users managed?
org.neo4j.server.rest.dbms.UserService provides a JAX-RS endpoint at /user to expose two AuthManager operations, a GET of an AuthorizationRepresentation of a user by passing the username on the path. The password of a user can be set by POSTing to /{username}/password – this can only be done when the requesting principal matches the username.
How do I add more users?
That is a very good question (avoiding the obviously dirty solution of directly modifying the data/dbms/auth file). As already mentioned the UserRepository has the ability to create a User, as used by the AuthManager newUser method, but where is this exposed?
Sadly the answer is that as far as I could tell it’s not at present, so is it a case of neo4j-shell & Groovy to the rescue?
Can we write a script that can obtain the protected AuthManager from the AbstractServer – nice idea in principle, but the shell uses RMI. It’s time for an unmanaged extension.
The code is available from GitHub here, in essence it adds a new REST endpoint to allow the neo4j user to creating other user accounts using a POST request to /useradd/{username} and including password=some_password within the payload.
You can build the extension using Maven’s package target, and copy the resultant jar file from target/neo4j-server-useradd-2.2.1.jar to the /plugins directory of the Neo4j server.
Additionally you’ll need to add the following line to conf/neo4j-server.properties:
org.neo4j.server.thirdparty_jaxrs_classes=org.neo4j.extension.server.unmanaged=/unmanaged
Then you can easily add users to the UserRepository (e.g.
curl --data "password=bar" --user neo4j:neo4j http://localhost:7474/unmanaged/useradd/foo), note that they’ll be made to change their passwords (as shown above in an earlier listing).
Summary
The 2.3 release will be enhancing this area with alternative authentication mechanisms (such as LDAP); if you need authorisation, then this can be handled at present using custom code implementing the org.neo4j.server.rest.security.SecurityRule interface (see the manual for more details).
Image may be NSFW.
Clik here to view.
Image may be NSFW.Clik here to view.
