Memgraph supports authentication and (optional) authorization using a custom built external auth module. The two supported operation modes are:
- authentication only (username/password verification)
- authentication and authorization (username/password verification and user to role mapping)
When a user connects to Memgraph the database will forward the user's supplied username and password to the external auth module and wait for it to deliver the authentication and/or authorization verdict back to the database. Based on the returned verdict, Memgraph will either close the connection to the connected user or it will allow the connection and set-up the user and/or role accordingly.
When Memgraph is switched to use the external auth module for authentication its internal users are automatically disabled. All users are authenticated only using the module, existing local users are ignored (unless they can be authenticated using the module).
In this mode Memgraph will only perform authentication (verification of username and password) using the external auth module. All user to role mappings and user and role permissions are managed through Memgraph.
When a user that has never logged in to the database passes authentication using the external auth module, a user object is created for that user. The user can then be seen using the following query:
This behavior can be changed to disable login to users that don't have an explicitly created user account.
In this mode Memgraph will perform authentication and authorization using the external auth module. The authorization supported is in the form of determining the user to role mapping using the module. User and role permissions are still managed through Memgraph.
When a user that has a role that doesn't yet exist in the database logs in to the database, a role object is created for that user and assigned to that user. The role can then be seen using the following query:
This behavior can be changed to disable login to users that don't have an explicitly created role.
This section contains the list of flags that are used to configure the external auth module authentication and authorization mechanisms used by Memgraph.
|Path to the executable that should be used for user authentication/authorization.|
|Controls whether users should be implicitly created on first login or they should be explicitly created manually.|
|Controls whether roles should be implicitly created on first appearance or they should be explicitly created manually.|
|Specifies whether the module is used only for authentication (value is |
|Specifies the maximum time that Memgraph will wait for a response from the external auth module.|
The external auth module can be written in any programming language. Because of that, the communication protocol between Memgraph and the module is simple to implement.
Memgraph uses inter-process pipes to communicate with the module. The module
will receive auth requests on file descriptor
1000 and has to return auth
responses to file descriptor
1001. You may be wondering why we didn't just
stdout for communication. The standard streams aren't used
because external libraries often tend to write something to
stdout which is
difficult to turn off. By using separate file descriptors,
stdout is left
intact and can be used freely for debugging purposes (along with
The protocol that is used between Memgraph and the module is as follows:
- Each auth request is sent as a JSON encoded object in a single line that is
terminated by a
- Each auth response must be sent as a JSON encoded object in a single line
that is terminated by a
- Auth requests are objects that contain the following keys:
username- the user's username
password- the user's password
- Auth responses must be objects that contain the following keys:
boolindicating whether the user is allowed to log in to the database
stringindicating which role the user should have (must be supplied even when the module is used for authentication only)
If the external auth module crashes during the processing of an auth request,
Memgraph won't allow the user to log in to the database and will automatically
restart the auth module for the next auth request. All crash logs will be seen
in Memgraph's output (typically in
systemd logs using
This very simple example auth module is written in Python, but any programming language can be used.
In the example you can see exactly how the communication protocol works and you
can see the function that is used for authentication (and authorization). When
writing your own modules you just have to reimplement the
function according to your needs.
Because the authentication (and authorization) function has a simple signature, it is easy (and recommended) to write unit (or integration) tests in separate files. For example:
With every Memgraph Enterprise installation we provide our own module that supports authentication and authorization using LDAP. For more information about how the module should be set-up see the reference guide.