Role-based access control ^Enterprise

Role-Based access control (RBAC) simplifies data security by grouping users into roles based on their tasks. Instead of assigning permissions to each user, RBAC assigns privileges to roles. Users, when linked to roles, gain the necessary access for their responsibilities. For example, in a company, a manager’s role might have different access levels than an employee’s role. Through RBAC, organizations efficiently ensure that users only access data relevant to their role, enhancing security and minimizing risks.

With role-based access control, a database administrator can assign various privileges to roles, but for even more control over who can access certain data, Memgraph Enterprise offers fine-grained access control. Additionally, you can use user profiles to set resource limits for users.

User roles

Users can be assigned multiple roles simultaneously, with permissions from all roles being combined. User roles are abstractions that capture the privilege levels of a set of users.

For example, suppose that Dominik and Marko belong to the upper management of a certain company. It makes sense to grant them a set of privileges that other users are not entitled to so, instead of granting those privileges to each of them, we can create a role with those privileges called manager, which we assign to Dominik and Marko.

In other words, each privilege that is granted to a user role is automatically granted to all the users with that role (unless it has been explicitly denied to that user). Similarly, each privilege that is denied to a user role is automatically denied to all users with that role (even if it has been explicitly granted to that user).

When a user has multiple roles, their permissions are combined using the following rules:

• Grants: If any role grants a permission, the user has that permission
• Denies: If any role denies a permission, the user is denied that permission
• Database Access: If any role grants access to a database, the user has access
• Fine-grained Permissions: Label-based and edge type permissions are merged using grant/deny logic. See Label-based access control below for details on how fine-grained permissions work and are combined.

To create a user role, run the following query:

CREATE ROLE [IF NOT EXISTS] role_name;

If a role already exists, you can use IF NOT EXISTS to only create new roles.

To assign a user with a certain user role, run the following query:

SET ROLE FOR user_name TO role_name [, another_role, ...];

To remove all roles from the user, run the following query:

CLEAR ROLE FOR user_name;

To show all users with a certain role:

SHOW USERS FOR role_name;

To show what roles a user has, run the following query:

SHOW ROLE FOR user_name;

Note: The SHOW ROLE FOR USER command does not require database specification, even in multi-tenant environments. It will show all roles assigned to the user across all databases.

To show the current user’s roles in the current session:

SHOW CURRENT ROLE;

In multi-tenant environments, you can optionally specify which database context to use when showing roles:

1. Show roles for the user’s main database:

SHOW ROLE FOR user_name ON MAIN;

2. Show roles for the current database:

SHOW ROLE FOR user_name ON CURRENT;

3. Show roles for a specific database:

SHOW ROLE FOR user_name ON DATABASE database_name;

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

To list all defined user roles run:

SHOW ROLES;

User profiles

User profiles allow you to set resource limits for individual users to control resource consumption and prevent system abuse.

For detailed information about user profiles, including profile creation, management, and advanced features, see the User profiles documentation.

Privileges

At the moment, privileges are confined to users’ abilities to perform certain OpenCypher queries. Namely, users can be given permission to execute a subset of the following commands:

Authentication and authorization requirements

System queries in multi-tenant environments

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

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

Recommended approach for multi-tenant environments

In multi-tenant environments, we recommend treating the default “memgraph” database as an administrative/system database rather than storing application data in it. This approach provides better security and isolation:

1. Restrict access to the memgraph database: Only grant access to privileged users who need to perform authentication, authorization, replication, or multi-database management operations
2. Use tenant-specific databases: Store application data in dedicated tenant databases rather than the default database
3. Separate administrative functions: Keep user management, system administration, replication management, and multi-database management separate from application data

Example setup for multi-tenant environments

-- Create admin role with full privileges
CREATE ROLE admin;
GRANT ALL PRIVILEGES TO admin;
GRANT DATABASE memgraph TO admin;
 
-- Create tenant-specific roles
CREATE ROLE tenant1_user;
CREATE ROLE tenant2_user;
 
-- Grant appropriate permissions to tenant roles
GRANT MATCH, CREATE, MERGE, SET, DELETE TO tenant1_user;
GRANT MATCH, CREATE, MERGE, SET, DELETE TO tenant2_user;
 
-- Grant access to tenant databases only
GRANT DATABASE tenant1_db TO tenant1_user;
GRANT DATABASE tenant2_db TO tenant2_user;
 
-- Create users
CREATE USER admin_user IDENTIFIED BY 'admin_password';
CREATE USER tenant1_user_account IDENTIFIED BY 'password1';
CREATE USER tenant2_user_account IDENTIFIED BY 'password2';
 
-- Assign roles
SET ROLE FOR admin_user TO admin;
SET ROLE FOR tenant1_user_account TO tenant1_user;
SET ROLE FOR tenant2_user_account TO tenant2_user;

In this setup:

• admin_user has access to the “memgraph” database and can perform all authentication/authorization, replication, and multi-database operations
• tenant1_user_account and tenant2_user_account can only access their respective tenant databases
• Application data is stored in tenant-specific databases, not in the default “memgraph” database

After the first user is created, Memgraph will execute a query if and only if either a user or its role is granted that privilege and neither the user nor its role are denied that privilege. Otherwise, Memgraph will not execute that specific query. Note that DENY is a stronger operation than GRANT. This is also notable from the fact that if neither the user nor its role are explicitly granted or denied a certain privilege, that user will not be able to perform that specific query. This effect is also known as a silent deny. The information above is neatly condensed in the following table:

Once the privileges are changed, they take full effect once the user reconnects to the database.

Grant privileges

To grant a certain set of privileges to a specific user or user role, use the following query:

GRANT privilege_list TO user_or_role;

For example, to grant AUTH and INDEX privileges to users with the moderator role, run:

GRANT AUTH, INDEX TO moderator:

Deny privileges

Similarly, denying privileges is done using the DENY keyword instead of GRANT.

For example, to deny AUTH and INDEX privileges to users with the moderator role, run:

DENY AUTH, INDEX TO moderator:

Revoke privileges

Both denied and granted privileges can be revoked, meaning that their status is not defined for that user or role. Revoking is done using the REVOKE keyword.

For example, to revoke AUTH and INDEX privileges to users with the moderator role, run:

REVOKE AUTH, INDEX FROM moderator:

Although semantically unintuitive, the level of a certain privilege can be raised by using REVOKE. For instance, if a user has been denied the INDEX privilege, but the role it belongs to is granted that privilege, the user is unable to use indexing features.

If the user’s INDEX privilege is revoked, they will be able to use indexing features because the role is granted that privilege.

Manage all privileges at once

To grant, deny or revoke all privileges, use the ALL PRIVILEGES construct:

GRANT ALL PRIVILEGES TO <user>;

DENY ALL PRIVILEGES TO <user>;

REVOKE ALL PRIVILEGES FROM <user>;

Show privileges

To check privilege for a certain user or role, run the following query:

SHOW PRIVILEGES FOR user_or_role;

In multi-tenant environments, privileges can differ depending on the target database. The SHOW PRIVILEGE query can be expanded to show privileges on specific databases as the following:

1. Show privileges for the user’s main database:

SHOW PRIVILEGES FOR user_or_role ON MAIN;

2. Show privileges for the current database:

SHOW PRIVILEGES FOR user_or_role ON CURRENT;

3. Show privileges for a specific database:

SHOW PRIVILEGES FOR user_or_role ON DATABASE database_name;

These commands return the aggregated privileges (including label-based permissions) for the user or role in the specified database context.

Note:

• For users: In multi-tenant environments, you must specify the database context.
• For roles: This command does not require database specification, even in multi-tenant environments. In which case, it will role’s privileges without filtering for database.

Fine-grained access control

Sometimes, authorizing the database by granting and denying clause privileges is not enough to make the database fully secure. Certain nodes and relationships can be confidential and must be restricted from viewing and manipulating by multiple users. Also, disabling users from executing certain commands is sometimes too restrictive.

In response to the need for such authorization, Memgraph has added label-based access control (LBAC) as a more fine-grained access control to enable authorization on node labels and relationship edge types. By applying authorization to graph’s first class citizens, a database administrator can now keep all the data in one database while keeping any private data secure from those who don’t have adequate permission.

Label-based access control

Label-based permissions are set using CREATE, READ, UPDATE, and DELETE permissions, along with NOTHING to deny access:

• NOTHING - denies user visibility and manipulation over nodes and relationships
• CREATE - grants the user creation of a node or relationship
• READ - grants the user visibility over nodes and relationships
• UPDATE - grants the user visibility and the ability to edit nodes and relationships
• DELETE - grants the user deletion of a node or a relationship

Node permissions

Granting a certain set of node permissions can be done similarly to the clause privileges using the following command:

GRANT permission ON NODES CONTAINING LABELS label_list [MATCHING ANY| MATCHING EXACTLY] TO user_or_role;

with the legend:

• permission is either NOTHING, or a comma-separated list containing one or more of: CREATE, READ, UPDATE or DELETE
• label_list is a set of node labels, separated with a comma and with a colon in front of each label (e.g. :Person), or * for creating a global rule matching all labels in the graph
• user_or_role is the already created user or role in Memgraph
• MATCHING ANY means that the rule will apply to any node having one or more of the specified labels, regardless of any additional labels that the node may have
• MATCHING EXACTLY will mean that the rule will apply to any node having all of the labels specified, and no additional labels
• If the MATCHING clause is omitted, MATCHING ANY is assumed by default
• MATCHING clauses cannot be used when creating global (*) rules

For example, granting a READ permission on any nodes with labels User or Product to user charlie would be written as:

GRANT READ ON NODES CONTAINING LABELS :User, :Product MATCHING ANY TO charlie;

Note that the MATCHING ANY clause may be omitted because this is the default for labels. The following statement behaves identically to the previous example:

GRANT READ ON NODES CONTAINING LABELS :User, :Product TO charlie;

Multiple permissions can be granted using multiple statements, building up the allowed permissions piece-by-piece:

GRANT CREATE ON NODES CONTAINING LABELS :Item TO charlie;
GRANT READ ON NODES CONTAINING LABELS :Item TO charlie;
GRANT UPDATE ON NODES CONTAINING LABELS :Item TO charlie;

Or they can be granted in a single statement using a comma-separated permission list:

GRANT CREATE, READ, UPDATE ON NODES CONTAINING LABELS :Item TO charlie;

Global permissions for all labels can be granted using * instead of a list of labels:

GRANT READ ON NODES CONTAINING LABELS * TO charlie;

For denying visibility to a node, use the NOTHING permission. Granting NOTHING creates an explicit DENY rule for the given label specification, which overrides any existing permissions.

GRANT NOTHING ON NODES CONTAINING LABELS :User, :Person TO charlie;

Permissions can be revoked using the following syntax:

REVOKE permission ON NODES CONTAINING LABELS label_list [MATCHING ANY| MATCHING EXACTLY] FROM user_or_role;

The rules for specifying REVOKE label specifications are identical to those when using GRANT.

Note that revoking all permissions for a label specification is not the same as GRANTing NOTHING. The former removes already GRANTed permissions for the label specification; the latter sets an explicit DENY on that label specification. This distinction is particularly important when it comes to merging permissions and combining matching rules.

Relationship permissions

Edge type permissions work similarly to node permissions, and have the same permission types (CREATE, READ, UPDATE, DELETE, and NOTHING).

Permissions can be granted using the following syntax:

GRANT permission ON EDGES OF TYPE edge_type_list TO user_or_role;

where:

• permission is either NOTHING, or a comma-separated list containing one or more of: CREATE, READ, UPDATE or DELETE
• edge_type_list is a set of edge types, separated with a comma and with a colon in front of each type (e.g. :KNOWS, :FOLLOWS), or * for all edge types
• user_or_role is the already created user or role in Memgraph

Note that edge type permissions do not support MATCHING clauses: edges can only have a single type, so matching modes are not applicable.

For example, granting READ permission on edge type :CONNECTS to user charlie:

GRANT READ ON EDGES OF TYPE :CONNECTS TO charlie;

Granting multiple permissions on multiple edge types:

GRANT CREATE, READ, UPDATE ON EDGES OF TYPE :KNOWS, :FOLLOWS TO charlie;

Global permissions for all edge types:

GRANT READ ON EDGES OF TYPE * TO charlie;

Revoking edge type permissions uses similar syntax:

REVOKE permission ON EDGES OF TYPE edge_type_list FROM user_or_role;

For example:

REVOKE CREATE ON EDGES OF TYPE :KNOWS FROM charlie;

As with node permissions, revoking all permissions is not the same as granting NOTHING. Revoking removes granted permissions, while NOTHING creates an explicit DENY rule.

Merging permissions

When a user has multiple roles, or when a user has both role-based and user-specific permissions, individual permission bits (CREATE, READ, UPDATE, DELETE) are combined using OR logic for grants and explicit denies:

• If any role or the user grants a specific permission on a label specification, the user has that permission
• If any role or the user grants NOTHING (explicit deny) on a label specification, the user is denied all access to that label specification, overriding any grants
• Each label specification is evaluated independently based on its label list and matching mode

For example, if a user has Role A granting READ on :Item and Role B granting UPDATE on :Item, the user will have both READ and UPDATE permissions on :Item nodes. However, if Role C grants NOTHING on :Item, the explicit deny overrides all grants, and the user will have no access to any :Item nodes.

Combining matching rules

When a node matches multiple label specifications, all matching rules are applied and their permissions are combined:

• The effective permissions for a node are the union (OR) of all permissions from matching rules
• If any matching rule grants NOTHING, the node is denied: explicit deny overrides all grants
• Rules are matched based on their label specification and matching mode

For example, given the following rules:

GRANT READ ON NODES CONTAINING LABELS :User MATCHING ANY TO charlie;
GRANT UPDATE ON NODES CONTAINING LABELS :Employee MATCHING ANY TO charlie;

A node with labels :User:Employee matches both rules. charlie will have both READ and UPDATE permissions on this node, since permissions from all matching rules are combined.

However, if we add an explicit deny:

GRANT NOTHING ON NODES CONTAINING LABELS :Admin MATCHING ANY TO charlie;

A node with labels :User:Employee:Admin matches all three rules. charlie will have NOTHING (explicit deny) on this node, since NOTHING takes precedence over any granted permissions.

The MATCHING mode also affects which rules apply:

GRANT READ ON NODES CONTAINING LABELS :User, :Employee MATCHING EXACTLY TO charlie;
GRANT UPDATE ON NODES CONTAINING LABELS :Employee MATCHING ANY TO charlie;

• A node with labels :User:Employee (only these two labels) matches the first rule exactly, and the second rule (has :Employee). charlie has both READ and UPDATE
• A node with labels :User:Employee:Admin matches only the second rule (has :Employee, but not exactly :User:Employee). charlie has only UPDATE
• A node with label :Employee matches only the second rule. charlie has only UPDATE

Global permissions and label-specific rules

Global permissions (granted on *) act as a fallback when no specific label specification matches a node. When a node matches a specific label rule, that rule takes precedence over the global permission.

For example:

GRANT READ, UPDATE ON NODES CONTAINING LABELS * TO charlie;
GRANT NOTHING ON NODES CONTAINING LABELS :Confidential MATCHING ANY TO charlie;

• A node with label :User has no specific rule match, so the global * permission applies. charlie has READ and UPDATE
• A node with label :Confidential matches the specific rule. The specific NOTHING rule overrides the global permission, so charlie has no access

Another example:

GRANT READ ON NODES CONTAINING LABELS * TO charlie;
GRANT UPDATE ON NODES CONTAINING LABELS :Document MATCHING ANY TO charlie;

• A node with label :User matches only the global rule. charlie has READ
• A node with label :Document matches the specific rule. charlie has UPDATE from the specific rule, but the global READ is replaced by the specific rule, so charlie has only UPDATE
• A node with labels :Document:Draft matches the specific rule (has :Document). charlie has only UPDATE

Key principle: Once any specific label rule matches a node, the global * permission is not considered for that node.

Show privileges for label-based access control

To check which privileges an existing user or role has in Memgraph, it is enough to write

SHOW PRIVILEGES FOR user_or_role;

In multi-tenant environments, privileges can differ depending on the target database. The SHOW PRIVILEGE query can be expanded to show privileges on specific databases as the following:

1. Show privileges for the user’s main database:

SHOW PRIVILEGES FOR user_or_role ON MAIN;

2. Show privileges for the current database:

SHOW PRIVILEGES FOR user_or_role ON CURRENT;

3. Show privileges for a specific database:

SHOW PRIVILEGES FOR user_or_role ON DATABASE database_name;

These commands return the aggregated privileges (including label-based permissions) for the user or role in the specified database context.

Note:

• For users: In multi-tenant environments, you must specify the database context.
• For roles: This command does not require database specification, even in multi-tenant environments. In which case, it will role’s privileges without filtering for database.

Templates for granting privileges

To grant all privileges to a superuser (admin):

GRANT ALL PRIVILEGES TO admin;
GRANT DATABASE * to admin;
GRANT CREATE, READ, UPDATE, DELETE ON NODES CONTAINING LABELS * TO admin;
GRANT CREATE, READ, UPDATE, DELETE ON EDGES OF TYPE * TO admin;

To grant all read and write privileges:

DENY ALL PRIVILEGES TO readWrite;
GRANT CREATE, DELETE, MERGE, SET, REMOVE, INDEX, MATCH, STATS TO readWrite;
GRANT CREATE, READ, UPDATE, DELETE ON NODES CONTAINING LABELS * TO readWrite;
GRANT CREATE, READ, UPDATE, DELETE ON EDGES OF TYPE * TO readWrite;

To grant read only privileges:

DENY ALL PRIVILEGES TO readonly;
GRANT MATCH, STATS TO readonly;
GRANT READ ON NODES CONTAINING LABELS * TO readonly;
GRANT READ ON EDGES OF TYPE * TO readonly;

Examples

Below are several examples of using the Enterprise security features.

Grant read permissions

Bob is a data analyst for the company. He is making sure he can extract any useful insights from the data imported into the database. For now, all the data is labeled with the DataPoint label. Alice has already created a data analyst role as well as Bob’s account in Memgraph with:

CREATE ROLE analyst;
CREATE USER Bob IDENTIFIED BY 'test';
SET ROLE FOR Bob TO analyst;
GRANT DATABASE exampledb TO Bob;

Unfortunately, when he writes:

MATCH (n:DataPoint) RETURN n;

he gets an error that he can not execute the query. Why is that? The first problem that we encounter is that Bob can not perform MATCH queries, which we must explicitly grant.

The database administrator grants him and all the data analysts the MATCH query to traverse the graph with:

GRANT MATCH TO analyst;

Now Bob is able to perform a match. However, by executing the same query again, he is not able to get any results.

Since Bob is not an administrator, he was not able to see any data points in the graph. In other words, he does not have READ permission on the DataPoint label.

Alice now updates Bob’s permissions by executing:

GRANT READ ON NODES CONTAINING LABELS :DataPoint TO analyst;

Bob is now executing his queries normally and is able to get insights from the database with respect to all the data points in the graph!

Additionally, in the company, it was decided that all the data points would be connected in a time series fashion, depending on when they were ingested into the database. One DataPoint should therefore be connected to the previously inserted one. The relationship type is called :NEXT.

Bob now again has problems, because when he executes:

MATCH (n:DataPoint)-[e:NEXT]->(m:DataPoint);

he is not able to see the patterns. Although Bob can see all the data points, he doesn’t have permission to view the relationships. The database administrator executes the following command to solve the problem:

GRANT READ ON EDGES OF TYPE :NEXT TO analyst;

Since the users are initially constructed without any permission, they would need an explicit grant for every new label that appears in the database. This approach is called whitelisting, and is more secure for adding new entities in the database since confidential nodes and relationships are not leaked into the database before securing them.

Grant update permissions

Charlie is a tester and customer care specialist. He is in charge of reporting bugs and fixing issues in the database. A common problem that he is facing is updating the classes of the data points if they are labeled incorrectly. For example, the class of one DataPoint might be ‘dog’, while in fact it is an ‘elephant’, but it was wrongly selected in the rush of labeling many data points. Charlie needs to update the wrongly labeled data points, and he already has the IDs of all the nodes he must update.

The administrator has already set up his account with the following commands:

CREATE ROLE tester;
CREATE USER Charlie IDENTIFIED BY 'test';
SET ROLE FOR Charlie TO tester;
GRANT DATABASE exampledb TO Charlie;
 
GRANT MATCH, SET TO tester;
 
GRANT READ ON NODES CONTAINING LABELS :DataPoint TO tester;
GRANT READ ON EDGES OF TYPE :NEXT TO tester;

He now has read privileges just like all the data analysts, but when he gets an authorization error while executing:

MATCH (n:DataPoint {id:505}) SET n.labelY = 'elephant';

The error occurs because Charlie does not have permission to update the existing nodes in the graph. The database administrator needs to update Charlie’s permissions and grant him access to update the node properties with:

GRANT UPDATE ON NODES CONTAINING LABELS :DataPoint TO tester;

Charlie is now able to update the labeled categories of any data point in the graph! The same permission applies if he needs to update a relationship property in the graph.

Grant full access permissions

David is the data engineer for the company. He is very skilled in database systems, and he has been assigned the task of deleting every data point in the system that’s older than one year. Alice has his account set up with the following commands:

CREATE ROLE dataEngineer;
CREATE USER David IDENTIFIED BY 'test';
SET ROLE FOR David TO dataEngineer;
GRANT DATABASE exampledb TO David;
 
GRANT MATCH, DELETE TO dataEngineer;
 
GRANT UPDATE ON NODES CONTAINING LABELS :DataPoint TO dataEngineer;
GRANT UPDATE ON EDGES OF TYPE :NEXT TO dataEngineer;

However, UPDATE privilege capabilities only grant manipulation of properties, not the nodes and relationships themselves. Therefore, the query:

MATCH (n:DataPoint) WHERE localDateTime() - n.date > Duration({day:365}) DETACH DELETE n;

results in an error. To delete nodes and relationships, David needs both CREATE and DELETE permissions (as well as READ to query them). By executing the following commands:

GRANT CREATE, READ, DELETE ON NODES CONTAINING LABELS :DataPoint TO dataEngineer;
GRANT CREATE, READ, DELETE ON EDGES OF TYPE :NEXT TO dataEngineer;

The permission is executed on relationships as well, since David needs to detach the nodes prior to deleting them. David is now able to successfully delete the deprecated nodes.

Deny visibility

Eve is the new senior engineer, and she is making excellent progress in the company. The management therefore decided to grant her visibility and manipulation over all the nodes. However, there are certain confidential nodes that are only for the management people to see.

Since there could be a lot of different node labels or relationship types in the database, a shortcut can be made by granting NOTHING to the entity. The database administrator therefore sets Eve’s role as:

CREATE ROLE seniorEngineer;
CREATE USER Eve IDENTIFIED BY 'test';
SET ROLE FOR Eve TO seniorEngineer;
GRANT DATABASE exampledb TO Eve;
 
GRANT MATCH, DELETE TO seniorEngineer;
 
GRANT CREATE, READ, UPDATE, DELETE ON NODES CONTAINING LABELS * TO seniorEngineer;
GRANT NOTHING ON NODES CONTAINING LABELS :SecretLabel TO seniorEngineer;

When granting NOTHING, the user is denied both visibility and manipulation of the entity. Eve is now able to see all the domain data while the management is happy since they have not leaked any confidential data.