Authentication and authorization

Learn how authentication and authorization works in Memgraph. Manage users and roles, secure the database with role-based and fine-grained access control and learn how to integrate with other authentication systems.

Changes to authentication requirements

As of Memgraph v3.5 there are new requirements for authentication and authorization operations, particularly affecting multi-tenant environments:

AUTH privilege requirement

Authentication and authorization queries (such as CREATE USER, CREATE ROLE, GRANT, DENY, REVOKE, etc.) now require the AUTH privilege AND access to the “memgraph” database. Users must be explicitly granted this privilege to perform user and role management operations.

The recommendation is to use the default “memgraph” database as an admin/system database and store graphs under other databases.

System queries in multi-tenant environment

To execute system (auth, replication and multi-database) queries, users must have:

The appropriate privileges (AUTH, REPLICATION, MULTI_DATABASE_EDIT)
AND access to the default “memgraph” database

Multi-tenant environment query syntax changes

SHOW ROLE syntax in multi-tenant environments

SHOW ROLE FOR <USER>: This command does not require database specification and will show all roles assigned to the user across all databases.

// Show all roles for a user (works in all environments)
SHOW ROLE FOR user_name;
SHOW ROLES FOR user_name;

If you need to see roles in a specific database context, you can optionally specify:

Show roles for the user’s main database:

SHOW ROLE FOR user_name ON MAIN;

Show roles for the current database:

SHOW ROLE FOR user_name ON CURRENT;

Show roles for a specific database:

SHOW ROLE FOR user_name ON DATABASE database_name;

SHOW PRIVILEGES syntax in multi-tenant environments

SHOW PRIVILEGES FOR <USER>: In multi-tenant environments, you must specify the database context:

Show privileges for the user’s main database:

SHOW PRIVILEGES FOR user_name ON MAIN;

Show privileges for the current database:

SHOW PRIVILEGES FOR user_name ON CURRENT;

Show privileges for a specific database:

SHOW PRIVILEGES FOR user_name ON DATABASE database_name;

These commands return the aggregated roles and privileges for the user in the specified database context. The ON MAIN option shows information for the user’s main database, ON CURRENT shows information for whatever database is currently active, and ON DATABASE shows information for the explicitly specified database.

SHOW PRIVILEGES FOR <ROLE>: This command does not require database specification and will show all privileges for the role.

// Show all privileges for a role (works in all environments)
SHOW PRIVILEGES FOR role_name;

Multi-tenant recommendations

For multi-tenant environments, we recommend:

Treating the default “memgraph” database as an administrative/system database
Restricting access to the “memgraph” database to privileged users only
Storing application data in tenant-specific databases
Ensuring users who need to perform authentication, replication, or multi-database operations have appropriate access

For detailed information about these requirements and best practices, see the Role-based access control, Multi-tenancy, and Replication documentation.

Run auth queries in a transaction

You can run auth queries, such as CREATE USER, CREATE ROLE, GRANT, and SET ROLE, in an explicit transaction. Other sessions and REPLICAs see none of the changes until COMMIT, and then all of them, so a user never exists without the privileges you meant to give it. Available since Memgraph 3.14.

BEGIN;
CREATE USER alice IDENTIFIED BY 'alice_password';
CREATE ROLE analyst;
GRANT MATCH TO analyst;
SET ROLE FOR alice TO analyst;
COMMIT;

This example uses roles, which need Memgraph Enterprise. The transaction itself works in Memgraph Community too.

Auth transactions are serializable. Each query sees the changes made by the queries before it. Memgraph snapshots each user or role the first time the transaction reads the user or role, and later reads return that snapshot. If anything the transaction has read changes before COMMIT, the commit fails. ROLLBACK discards all of the transaction’s changes. After this transaction, neither bob nor dave exists:

BEGIN;
CREATE USER bob;
CREATE USER dave;
ROLLBACK;

A single auth query outside a transaction works as before.

What an auth transaction can contain

The first query inside a transaction decides the kind of transaction, either data or auth. After an auth query, the transaction accepts only auth queries, including the SHOW queries that read users, roles, and privileges. After any other query type, it refuses auth queries: auth and data queries can’t be mixed within a single transaction.

BEGIN;
CREATE USER carol;
MATCH (n) RETURN count(n);

Either way, the refused query fails with this error:

A transaction that runs an auth query can contain only auth queries. Run other queries in a separate transaction.

The other queries refused in an auth transaction include SHOW TRANSACTIONS, replication queries, and user profile queries.

User and tenant profile changes are refused in every explicit transaction. Run them as single queries.

Conflicts between transactions

Memgraph doesn’t lock users or roles while a transaction is open. At COMMIT, it checks whether another session has changed anything the transaction read or wrote. If it has, nothing is applied and the commit fails with this error:

Cannot resolve conflicting transactions. Retry this transaction when the conflicting transaction is finished.

The error is transient, so a driver’s retry logic runs the transaction again (see conflicting transactions). Two transactions that change different users or roles both commit.

Some queries read more than their names suggest, so they conflict more often:

Listing queries, such as SHOW USERS: the transaction depends on the whole list, so the commit fails if another session created or dropped a user in the meantime.
DROP ROLE: checks every user’s roles, so it conflicts with any role assignment in another session, even of a different role.
The first user: on an instance with no users, two transactions that each create a user conflict. With an Enterprise license, creating the first user also creates the built-in roles, so it conflicts with a concurrent CREATE ROLE.

The commit also fails with this error if another session holds the system lock for more than 100 ms, for example while it runs a replication or multi-tenancy query.

A transaction that grants, denies, or revokes a database, or sets a user’s main database, fails at COMMIT if another session dropped that database in the meantime:

Tried to retrieve an unknown database "sales".

Auth transactions and replication

A REPLICA applies a committed auth transaction whole, so it never holds some of the transaction’s changes without the rest.

Users

Learn how to manage users in Memgraph.

Role-based access control ^Enterprise

Learn how to manage roles, set up their privileges and fine-grained access control.

Multi-role users and multi-tenant roles ^Enterprise

Learn how to assign multiple roles to users simultaneously and understand how permissions are combined from all roles.

Auth system integrations ^Enterprise

Learn how to integrate with third-party auth systems and manage user authentication and access control using Memgraph’s auth module.

Impersonate user ^Enterprise

Learn how the impersonate user feature enables authorized users to execute queries with the full permissions and context of another user.

User profiles ^Enterprise

Learn how to manage user profiles and set resource limits for users to control resource consumption and prevent abuse.

Database management Users