From ba7b00fe3555f8986f950081c5a34387f23468f7 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Tue, 15 Jul 2025 16:03:33 +0200 Subject: [PATCH 01/17] WIP --- .../authentication-and-authorization.mdx | 4 + .../authentication-and-authorization/_meta.ts | 1 + .../auth-system-integrations.mdx | 72 ++++- .../multiple-roles.mdx | 290 ++++++++++++++++++ .../role-based-access-control.mdx | 16 +- .../users.mdx | 4 + 6 files changed, 377 insertions(+), 10 deletions(-) create mode 100644 pages/database-management/authentication-and-authorization/multiple-roles.mdx diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 9fb2be18e..f78cb5f53 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -17,6 +17,10 @@ Learn how to manage users in Memgraph. Learn how to manage roles, set up their privileges and fine-grained access control. +## [Multiple roles per user](/database-management/authentication-and-authorization/multiple-roles) (Enterprise) + +Learn how to assign multiple roles to users simultaneously and understand how permissions are combined from all roles. + ## [Auth system integrations](/database-management/authentication-and-authorization/auth-system-integrations) (Enterprise) Learn how to integrate with third-party auth systems and manage user diff --git a/pages/database-management/authentication-and-authorization/_meta.ts b/pages/database-management/authentication-and-authorization/_meta.ts index 52e2d13d8..57ddebd2e 100644 --- a/pages/database-management/authentication-and-authorization/_meta.ts +++ b/pages/database-management/authentication-and-authorization/_meta.ts @@ -1,6 +1,7 @@ export default { "users": "Users", "role-based-access-control": "Role-based access control", + "multiple-roles": "Multiple roles per user", "auth-system-integrations": "Auth system integrations", "impersonate-user": "Impersonate user" } diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index f5cd5e6c7..af64f5947 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -27,7 +27,7 @@ privileges will still apply but you won't be able to manage them. ### Roles User roles must be defined in Memgraph before using auth modules because these -modules return the role associated with the user. +modules return the role(s) associated with the user. Memgraph now supports multiple roles per user, allowing auth modules to return either a single role or multiple roles. ### Flags @@ -85,8 +85,9 @@ The protocol used between Memgraph and the module is as follows: - Auth responses must be objects that contain the following fields: - `authenticated` - a `bool` indicating whether the user is allowed to log in to the database - - `role` - a `string` indicating which role the user should have (must be - supplied) + - `role` - a `string` indicating which role the user should have (backward compatible) + - `roles` - an array of strings indicating which roles the user should have (new format) + - `username` - the user's username (optional, can be derived from auth token) - `errors` (optional) - if `authenticated` is false, Memgraph will put up a warning with the error message returned by the module @@ -95,6 +96,53 @@ 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 `journalctl`). +### Multiple roles support + +Memgraph now supports multiple roles per user in auth module responses. Auth modules can return either a single role (backward compatible) or multiple roles (new format). + +#### Single role response (backward compatible) + +```python +def authenticate(username, password): + return { + "authenticated": True, + "role": "moderator" # Single role as string + } +``` + +#### Multiple roles response (new format) + +```python +def authenticate(username, password): + return { + "authenticated": True, + "roles": ["admin", "user"] # Multiple roles as array + } +``` + +#### Single role in array format + +```python +def authenticate(username, password): + return { + "authenticated": True, + "roles": ["admin"] # Single role in array + } +``` + +The system will: +1. First check for a `roles` field in the response +2. If `roles` is an array, use all roles in the array +3. If `roles` is a string, use it as a single role +4. If no `roles` field is found, fall back to the `role` field for backward compatibility +5. If no valid roles are found, authentication fails + +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**: Combined using the same grant/deny logic + ### Module example This very simple example auth module is written in Python, but any programming @@ -107,7 +155,15 @@ import io def authenticate(username, password): - return {"authenticated": True, "role": "moderator"} + # Example with multiple roles + if username == "admin_user" and password == "password": + return {"authenticated": True, "roles": ["admin", "user"]} + + # Example with single role (backward compatible) + if username == "moderator_user" and password == "password": + return {"authenticated": True, "role": "moderator"} + + return {"authenticated": False, "errors": "Invalid credentials"} if __name__ == "__main__": @@ -132,8 +188,8 @@ files. For example: #!/usr/bin/python3 import module -assert module.authenticate("sponge", "bob") == {"authenticated": True, "role": "analyst"} -assert module.authenticate("CHUCK", "NORRIS") == {"authenticated": True, "role": "admin"} +assert module.authenticate("admin_user", "password") == {"authenticated": True, "roles": ["admin", "user"]} +assert module.authenticate("moderator_user", "password") == {"authenticated": True, "role": "moderator"} ``` ## Single sign-on @@ -163,6 +219,10 @@ created in the Memgraph DB beforehand. Additionally, you have to grant [label-ba + +SSO identity providers often return multiple roles for users. Memgraph now supports this natively - if your identity provider returns multiple roles, they will all be mapped to Memgraph roles and the user will have permissions from all assigned roles combined. + + ### SAML Memgraph has built-in support for single sign-on (SSO) over the SAML protocol diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx new file mode 100644 index 000000000..8686ec08c --- /dev/null +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -0,0 +1,290 @@ +--- +title: Multiple roles per user +description: Learn how to assign multiple roles to users and understand how permissions are combined in multi-tenant environments. +--- + +import { Callout } from 'nextra/components' + +# Multiple roles per user (Enterprise) + +Memgraph Enterprise now supports assigning multiple roles to users simultaneously, with enhanced support for multi-tenant environments. This feature enables flexible permission management across different databases and better integration with external identity providers that return multiple roles. + +## Overview + +With multiple roles support, users can have different roles assigned to them, and their permissions are combined from all roles. This is particularly powerful in multi-tenant environments where users may need different permissions for different databases. + +Key benefits: +- **Multi-tenant RBAC**: Users can have different roles for different databases +- **SSO Integration**: External identity providers (OIDC, SAML) often return arrays of roles +- **Flexible Permissions**: Combining permissions from multiple specialized roles +- **Database-specific Access**: Fine-grained control over which databases users can access + +## Multi-tenant role management + +### Database-specific role assignments + +In multi-tenant environments, you can assign roles to users for specific databases: + +```cypher +-- Create roles with database-specific access +CREATE ROLE tenant1_admin; +CREATE ROLE tenant2_user; + +-- Grant database access to roles +GRANT DATABASE tenant1_db TO tenant1_admin; +GRANT DATABASE tenant2_db TO tenant2_user; + +-- Create user +CREATE USER bob IDENTIFIED BY 'password'; + +-- Assign database-specific roles +ADD ROLE tenant1_admin TO bob; +ADD ROLE tenant2_user TO bob; +``` + +### Global vs database-specific roles + +Roles can be assigned globally (accessible across all databases) or specifically for certain databases: + +```cypher +-- Global role (accessible across all databases) +CREATE ROLE global_analyst; +GRANT MATCH, STATS TO global_analyst; +ADD ROLE global_analyst TO alice; + +-- Database-specific role (only accessible in specific database) +CREATE ROLE tenant_admin; +GRANT DATABASE tenant_db TO tenant_admin; +GRANT ALL PRIVILEGES TO tenant_admin; +ADD ROLE tenant_admin TO alice; +``` + +## Permission combination rules + +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 (deny takes precedence) +- **Database Access**: If any role grants access to a database, the user has access +- **Fine-grained Permissions**: Combined using the same grant/deny logic +- **Database Filtering**: When accessing a specific database, only roles with access to that database are considered + +## Managing multiple roles + +### Adding roles to users + +To add a role to a user (keeping any existing roles), use: + +```cypher +ADD ROLE role_name TO user_name; +``` + +### Adding database-specific roles + +To add a role that's specific to a database: + +```cypher +-- The role must have access to the database +GRANT DATABASE database_name TO role_name; +ADD ROLE role_name TO user_name; +``` + +### Removing specific roles + +To remove a specific role from a user, use: + +```cypher +REMOVE ROLE role_name FROM user_name; +``` + +### Viewing user roles + +To see all roles assigned to a user: + +```cypher +SHOW ROLES FOR user_name; +``` + +### Viewing roles for a specific database + +To see which roles a user has for a specific database: + +```cypher +SHOW PRIVILEGES FOR user_name ON database_name; +``` + +### Legacy single role commands + +For backward compatibility, the following commands still work: + +```cypher +-- Set a single role (replaces all existing roles) +SET ROLE FOR user_name TO role_name; + +-- Clear all roles +CLEAR ROLE FOR user_name; +``` + + +The `SET ROLE` command is maintained for backward compatibility but is deprecated. Use `ADD ROLE` and `REMOVE ROLE` for better control over multiple roles. + + +## Multi-tenant examples + +### Basic multi-tenant setup + +```cypher +-- Create databases +CREATE DATABASE tenant1_db; +CREATE DATABASE tenant2_db; + +-- Create roles for each tenant +CREATE ROLE tenant1_admin; +CREATE ROLE tenant1_user; +CREATE ROLE tenant2_admin; +CREATE ROLE tenant2_user; + +-- Grant database access +GRANT DATABASE tenant1_db TO tenant1_admin; +GRANT DATABASE tenant1_db TO tenant1_user; +GRANT DATABASE tenant2_db TO tenant2_admin; +GRANT DATABASE tenant2_db TO tenant2_user; + +-- Grant permissions +GRANT ALL PRIVILEGES TO tenant1_admin; +GRANT MATCH, CREATE, MERGE, SET TO tenant1_user; +GRANT ALL PRIVILEGES TO tenant2_admin; +GRANT MATCH, CREATE, MERGE, SET TO tenant2_user; + +-- Create users with multi-tenant roles +CREATE USER alice IDENTIFIED BY 'password'; +ADD ROLE tenant1_admin TO alice; +ADD ROLE tenant2_user TO alice; + +CREATE USER bob IDENTIFIED BY 'password'; +ADD ROLE tenant1_user TO bob; +ADD ROLE tenant2_admin TO bob; +``` + +### Cross-tenant user with different permissions + +```cypher +-- User with different roles across tenants +CREATE USER manager IDENTIFIED BY 'password'; + +-- Admin in tenant1, regular user in tenant2 +ADD ROLE tenant1_admin TO manager; +ADD ROLE tenant2_user TO manager; + +-- Check permissions in each database +SHOW PRIVILEGES FOR manager ON tenant1_db; -- Full admin privileges +SHOW PRIVILEGES FOR manager ON tenant2_db; -- Limited user privileges +``` + +### SSO integration with multi-tenant roles + +When using external auth modules, users can be assigned multiple roles based on their identity provider roles: + +```python +def authenticate(username, password): + # Example: User has multiple roles from identity provider + if username == "cross_tenant_manager" and password == "password": + return { + "authenticated": True, + "roles": ["tenant1_admin", "tenant2_user", "global_analyst"], + "username": "cross_tenant_manager" + } + + return {"authenticated": False, "errors": "Invalid credentials"} +``` + +## Database access control + +### Main database selection + +When a user has multiple roles with access to different databases, the system determines the main database: + +```cypher +-- Create roles with different main databases +CREATE ROLE role1; +CREATE ROLE role2; +GRANT DATABASE db1 TO role1; +GRANT DATABASE db2 TO role2; +SET MAIN DATABASE db1 FOR role1; +SET MAIN DATABASE db2 FOR role2; + +-- User with both roles +CREATE USER user1 IDENTIFIED BY 'password'; +ADD ROLE role1 TO user1; +ADD ROLE role2 TO user1; + +-- The first role's main database becomes the user's main database +SHOW PRIVILEGES FOR user1; -- Shows db1 as main database +``` + +### Database-specific permission filtering + +When accessing a specific database, only roles with access to that database are considered: + +```cypher +-- Role with access to multiple databases +CREATE ROLE multi_db_role; +GRANT DATABASE db1 TO multi_db_role; +GRANT DATABASE db2 TO multi_db_role; +GRANT MATCH, CREATE ON db1 TO multi_db_role; +GRANT MATCH ON db2 TO multi_db_role; + +-- User with this role +CREATE USER user1 IDENTIFIED BY 'password'; +ADD ROLE multi_db_role TO user1; + +-- When accessing db1: has MATCH, CREATE +-- When accessing db2: has only MATCH +``` + +## Best practices for multi-tenant environments + +1. **Use descriptive role names**: Include tenant information in role names (e.g., `tenant1_admin`, `tenant2_user`) +2. **Follow principle of least privilege**: Grant only necessary permissions to each role +3. **Separate global and tenant-specific roles**: Use global roles for cross-tenant access, tenant-specific roles for isolation +4. **Test permission combinations**: Verify that combined permissions work as expected in each database +5. **Document role assignments**: Keep track of which users have which roles for which databases +6. **Use deny sparingly**: Remember that deny takes precedence over grant across all databases + +## Migration from single roles + +Existing users with single roles will continue to work without changes. To migrate to multiple roles in a multi-tenant environment: + +1. **Audit current roles**: Review existing role assignments and database access +2. **Plan multi-tenant structure**: Design how to split roles across databases +3. **Create database-specific roles**: Define roles for each tenant/database +4. **Test in development**: Verify permission combinations work correctly in each database +5. **Migrate gradually**: Use `ADD ROLE` to add new roles before removing old ones + +## Troubleshooting + +### Permission conflicts across databases + +If a user has conflicting permissions across roles in different databases: + +```cypher +-- Role A grants CREATE on db1 +GRANT CREATE ON db1 TO role_a; + +-- Role B denies CREATE on db2 +DENY CREATE ON db2 TO role_b; + +-- User with both roles +ADD ROLE role_a TO user; +ADD ROLE role_b TO user; + +-- Result: User can CREATE on db1, cannot CREATE on db2 +``` + +### Database access conflicts + +Similar rules apply to database access - if any role denies access to a database, the user will be denied access to that database, even if other roles grant access. + +### Performance considerations + +Multiple roles with database filtering may slightly impact permission checking performance, but this is typically negligible in most deployments. The database filtering ensures that only relevant roles are considered for each database access. \ No newline at end of file diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 7f1f93b87..43d71208a 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -22,7 +22,7 @@ control](#fine-grained-access-control). ## User roles -Each user can be assigned at most one user role. User roles are abstractions +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 @@ -37,6 +37,12 @@ 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**: Combined using the same grant/deny logic + To create a user role, run the following query: ```cypher @@ -48,10 +54,10 @@ 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: ```cypher -SET ROLE FOR user_name TO role_name; +SET ROLE FOR user_name TO role_name [, another_role, ...]; ``` -To remove the role from the user, run the following query: +To remove all roles from the user, run the following query: ```cypher CLEAR ROLE FOR user_name; @@ -63,12 +69,14 @@ To show all users with a certain role: SHOW USERS FOR role_name; ``` -To show what role a user has, run the following query: +To show what roles a user has, run the following query: ```cypher SHOW ROLE FOR user_name; ``` +TODO: multi-tenant environment show role for user_name + To list all defined user roles run: ```cypher diff --git a/pages/database-management/authentication-and-authorization/users.mdx b/pages/database-management/authentication-and-authorization/users.mdx index 41b8393ec..60d4e2185 100644 --- a/pages/database-management/authentication-and-authorization/users.mdx +++ b/pages/database-management/authentication-and-authorization/users.mdx @@ -15,6 +15,10 @@ out [role-based access control](/database-management/authentication-and-authorization/role-based-access-control) and [auth system integrations](/database-management/authentication-and-authorization/auth-system-integrations). + +Memgraph Enterprise now supports multiple roles per user, allowing users to have different roles simultaneously with combined permissions. See the [role-based access control](/database-management/authentication-and-authorization/role-based-access-control) section for details on managing multiple roles. + + ## Administer users Creating a user can be done by executing the following command: From 136a0d0c0e7eaab5331adbd6f456ca7840464925 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 17 Jul 2025 11:06:51 +0200 Subject: [PATCH 02/17] WIP --- .../authentication-and-authorization.mdx | 2 +- .../authentication-and-authorization/_meta.ts | 2 +- .../auth-system-integrations.mdx | 4 +- .../multiple-roles.mdx | 311 +++++++++--------- .../role-based-access-control.mdx | 4 + .../users.mdx | 2 +- 6 files changed, 164 insertions(+), 161 deletions(-) diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index f78cb5f53..8f16579b7 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -17,7 +17,7 @@ Learn how to manage users in Memgraph. Learn how to manage roles, set up their privileges and fine-grained access control. -## [Multiple roles per user](/database-management/authentication-and-authorization/multiple-roles) (Enterprise) +## [Multiple roles per user and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) (Enterprise) Learn how to assign multiple roles to users simultaneously and understand how permissions are combined from all roles. diff --git a/pages/database-management/authentication-and-authorization/_meta.ts b/pages/database-management/authentication-and-authorization/_meta.ts index 57ddebd2e..43eade6cb 100644 --- a/pages/database-management/authentication-and-authorization/_meta.ts +++ b/pages/database-management/authentication-and-authorization/_meta.ts @@ -1,7 +1,7 @@ export default { "users": "Users", "role-based-access-control": "Role-based access control", - "multiple-roles": "Multiple roles per user", + "multiple-roles": "Multiple roles per user and multi-tenant roles", "auth-system-integrations": "Auth system integrations", "impersonate-user": "Impersonate user" } diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index af64f5947..73b19c255 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -87,7 +87,7 @@ The protocol used between Memgraph and the module is as follows: in to the database - `role` - a `string` indicating which role the user should have (backward compatible) - `roles` - an array of strings indicating which roles the user should have (new format) - - `username` - the user's username (optional, can be derived from auth token) + - `username` - the user's username (optional) - `errors` (optional) - if `authenticated` is false, Memgraph will put up a warning with the error message returned by the module @@ -140,7 +140,7 @@ The system will: 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 +- **Database Access**: If any role grants and no role denies access to a database, the user has access - **Fine-grained Permissions**: Combined using the same grant/deny logic ### Module example diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index 8686ec08c..f32e3a18f 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -1,189 +1,221 @@ --- -title: Multiple roles per user -description: Learn how to assign multiple roles to users and understand how permissions are combined in multi-tenant environments. +title: Multiple roles per user and multi-tenant roles +description: Learn how to assign database-specific roles to users in multi-tenant environments with special permission filtering logic. --- import { Callout } from 'nextra/components' -# Multiple roles per user (Enterprise) +# Multi-tenant roles (Enterprise) -Memgraph Enterprise now supports assigning multiple roles to users simultaneously, with enhanced support for multi-tenant environments. This feature enables flexible permission management across different databases and better integration with external identity providers that return multiple roles. +Memgraph Enterprise supports multi-tenant roles, which allow users to have different roles assigned to them for specific databases. This feature enables proper tenant isolation and fine-grained access control in multi-tenant environments. ## Overview -With multiple roles support, users can have different roles assigned to them, and their permissions are combined from all roles. This is particularly powerful in multi-tenant environments where users may need different permissions for different databases. +Multi-tenant roles are a specialized form of multiple roles that include special logic for database-specific permission filtering. When a user has multi-tenant roles, their permissions are dynamically filtered based on which database they're accessing, ensuring proper tenant isolation. Key benefits: -- **Multi-tenant RBAC**: Users can have different roles for different databases -- **SSO Integration**: External identity providers (OIDC, SAML) often return arrays of roles -- **Flexible Permissions**: Combining permissions from multiple specialized roles -- **Database-specific Access**: Fine-grained control over which databases users can access +- **Tenant Isolation**: Users can have different permissions for different databases +- **SSO Integration**: Support for external identity providers that return multiple roles -## Multi-tenant role management +## Database access with users and roles -### Database-specific role assignments +### Basic database access -In multi-tenant environments, you can assign roles to users for specific databases: +In Memgraph Enterprise, both users and roles can have database access permissions: ```cypher --- Create roles with database-specific access -CREATE ROLE tenant1_admin; -CREATE ROLE tenant2_user; - --- Grant database access to roles -GRANT DATABASE tenant1_db TO tenant1_admin; -GRANT DATABASE tenant2_db TO tenant2_user; +-- Grant database access to a role +GRANT DATABASE db_name TO user_or_role; --- Create user -CREATE USER bob IDENTIFIED BY 'password'; +-- Deny database access +DENY DATABASE db_name TO user_or_role; --- Assign database-specific roles -ADD ROLE tenant1_admin TO bob; -ADD ROLE tenant2_user TO bob; +-- Revoke database access +REVOKE DATABASE db_name TO user_or_role; ``` -### Global vs database-specific roles - -Roles can be assigned globally (accessible across all databases) or specifically for certain databases: +### How database access works -```cypher --- Global role (accessible across all databases) -CREATE ROLE global_analyst; -GRANT MATCH, STATS TO global_analyst; -ADD ROLE global_analyst TO alice; - --- Database-specific role (only accessible in specific database) -CREATE ROLE tenant_admin; -GRANT DATABASE tenant_db TO tenant_admin; -GRANT ALL PRIVILEGES TO tenant_admin; -ADD ROLE tenant_admin TO alice; -``` +Database access follows these rules: +- **Grants**: If any role or user grants access to a database, database is granted +- **Denies**: If any role or user denies access to a database, database is denied +- **Access**: User or role has database access if it is granted and not denied -## Permission combination rules +## Database access with multiple roles -When a user has multiple roles, their permissions are combined using the following rules: +### Combining database access -- **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 (deny takes precedence) -- **Database Access**: If any role grants access to a database, the user has access -- **Fine-grained Permissions**: Combined using the same grant/deny logic -- **Database Filtering**: When accessing a specific database, only roles with access to that database are considered +When a user has multiple roles, their database access is combined from all roles: -## Managing multiple roles +```cypher +-- Create roles with different database access +CREATE ROLE role1; +CREATE ROLE role2; -### Adding roles to users +-- Grant different database access to each role +GRANT DATABASE db1 TO role1; +GRANT DATABASE db2 TO role2; -To add a role to a user (keeping any existing roles), use: +-- Create user and assign both roles +CREATE USER alice IDENTIFIED BY 'password'; +SET ROLE FOR alice TO role1, role2; -```cypher -ADD ROLE role_name TO user_name; +-- Result: Alice has access to both db1 and db2 ``` -### Adding database-specific roles +### Database access conflicts -To add a role that's specific to a database: +When roles have conflicting database access, deny takes precedence: ```cypher --- The role must have access to the database -GRANT DATABASE database_name TO role_name; -ADD ROLE role_name TO user_name; -``` +-- Role1 grants access to db1 +GRANT DATABASE db1 TO role1; -### Removing specific roles +-- Role2 denies access to db1 +DENY DATABASE db1 TO role2; -To remove a specific role from a user, use: +-- User with both roles +SET ROLE FOR user TO role1, role2; -```cypher -REMOVE ROLE role_name FROM user_name; +-- Result: User is denied access to db1 (deny takes precedence) ``` -### Viewing user roles +## Privileges with multiple roles -To see all roles assigned to a user: +When a user has multiple roles, their privileges are combined according to the following rules: -```cypher -SHOW ROLES FOR user_name; -``` +- **Grant**: If any assigned role with access to the database grants a privilege, the user is granted that privilege. +- **Deny**: If any assigned role with access to the database denies a privilege, the user is denied that privilege—even if another role grants it. +- **Effective privilege**: The user's effective privileges are the union of all granted privileges, minus any that are denied by any role. -### Viewing roles for a specific database +This means that **deny always takes precedence over grant** when there is a conflict. +**Note:** The resulting user privileges contain user's privileges only if the user also has access to the database. -To see which roles a user has for a specific database: +## Creating database-specific roles + +### Using database access for tenant isolation + +You can create roles that are specific to certain databases by controlling their database access: ```cypher -SHOW PRIVILEGES FOR user_name ON database_name; +-- Create tenant-specific roles +CREATE ROLE tenant1_admin; +CREATE ROLE tenant2_user; + +-- Grant database access to specific tenants +GRANT DATABASE tenant1_db TO tenant1_admin; +GRANT DATABASE tenant2_db TO tenant2_user; + +-- Grant appropriate permissions +GRANT ALL PRIVILEGES TO tenant1_admin; +GRANT MATCH, CREATE, MERGE, SET TO tenant2_user; + +-- Create user with both roles +CREATE USER bob IDENTIFIED BY 'password'; +SET ROLE FOR bob TO tenant1_admin, tenant2_user; ``` -### Legacy single role commands +### Limitations of this approach -For backward compatibility, the following commands still work: +While this approach works, it has some limitations: +- Users get access to all databases their roles have access to +- No fine-grained control over which role applies to which database +- Permission filtering is based on database access, not role assignment +- Admin needs to create a set of role for each database + +## Better API: Database-specific role assignment + +### Setting roles ON a database + +Memgraph Enterprise provides a better API for database-specific role assignment using the `ON database` clause: ```cypher --- Set a single role (replaces all existing roles) -SET ROLE FOR user_name TO role_name; +-- Assign role to specific database +SET ROLE FOR user_name TO role_name ON database_name; --- Clear all roles -CLEAR ROLE FOR user_name; +-- Remove role from specific database +CLEAR ROLE FOR user_name ON database_name; + +-- Remove all roles +CLEAR ROLES; ``` - -The `SET ROLE` command is maintained for backward compatibility but is deprecated. Use `ADD ROLE` and `REMOVE ROLE` for better control over multiple roles. - +**Note:** Multiple roles can be specified on a database. However, the list of roles needs to be exhaustive. -## Multi-tenant examples +### How it works -### Basic multi-tenant setup +This API provides true database-specific role assignment: ```cypher --- Create databases -CREATE DATABASE tenant1_db; -CREATE DATABASE tenant2_db; - --- Create roles for each tenant +-- Create roles with database access CREATE ROLE tenant1_admin; -CREATE ROLE tenant1_user; -CREATE ROLE tenant2_admin; CREATE ROLE tenant2_user; --- Grant database access +-- Grant database access to roles GRANT DATABASE tenant1_db TO tenant1_admin; -GRANT DATABASE tenant1_db TO tenant1_user; -GRANT DATABASE tenant2_db TO tenant2_admin; GRANT DATABASE tenant2_db TO tenant2_user; -- Grant permissions GRANT ALL PRIVILEGES TO tenant1_admin; -GRANT MATCH, CREATE, MERGE, SET TO tenant1_user; -GRANT ALL PRIVILEGES TO tenant2_admin; GRANT MATCH, CREATE, MERGE, SET TO tenant2_user; --- Create users with multi-tenant roles +-- Create user with database-specific roles CREATE USER alice IDENTIFIED BY 'password'; -ADD ROLE tenant1_admin TO alice; -ADD ROLE tenant2_user TO alice; +SET ROLE FOR alice TO tenant1_admin ON tenant1_db; +SET ROLE FOR alice TO tenant2_user ON tenant2_db; +``` -CREATE USER bob IDENTIFIED BY 'password'; -ADD ROLE tenant1_user TO bob; -ADD ROLE tenant2_admin TO bob; +**Note:** The list of roles defined in the SET ROLE query is an exhaustive list. + +### Special logic for database filtering + +When using `SET ROLE ... ON database`, the system applies special logic: + +1. **Database Access Check**: Only roles with access to the specified database can be assigned +2. **Permission Filtering**: When accessing a database, only roles assigned to that database are considered +3. **Isolation**: Users cannot access permissions from roles assigned to other databases +4. **Automatic Filtering**: The system automatically filters permissions based on the current database context + +## Multi-tenant role management + +### Adding database-specific roles + +To assign a role to a user for a specific database: + +```cypher +-- The role must have access to the database +GRANT DATABASE database_name TO role_name; +SET ROLE FOR user_name TO role_name ON database_name; ``` -### Cross-tenant user with different permissions +### Clearing database-specific roles + +To remove a role from a specific database: ```cypher --- User with different roles across tenants -CREATE USER manager IDENTIFIED BY 'password'; +CLEAR ROLE FOR user_name ON database_name; +``` + +### Viewing multi-tenant roles --- Admin in tenant1, regular user in tenant2 -ADD ROLE tenant1_admin TO manager; -ADD ROLE tenant2_user TO manager; +To see which roles a user has for a specific database: --- Check permissions in each database -SHOW PRIVILEGES FOR manager ON tenant1_db; -- Full admin privileges -SHOW PRIVILEGES FOR manager ON tenant2_db; -- Limited user privileges +```cypher +SHOW ROLES FOR user_name ON database_name; ``` +### Viewing permissions for a specific database + +To see what permissions a user has in a specific database: + +```cypher +SHOW PRIVILEGES FOR user_name ON database_name; +``` + + ### SSO integration with multi-tenant roles -When using external auth modules, users can be assigned multiple roles based on their identity provider roles: +When using external auth modules, users can be assigned multi-tenant roles based on their identity provider roles: ```python def authenticate(username, password): @@ -191,7 +223,8 @@ def authenticate(username, password): if username == "cross_tenant_manager" and password == "password": return { "authenticated": True, - "roles": ["tenant1_admin", "tenant2_user", "global_analyst"], + "roles": ["tenant1_admin", "tenant2_user"], + "role_databases": ["tenant1_db", "tenant2_db"], "username": "cross_tenant_manager" } @@ -202,7 +235,7 @@ def authenticate(username, password): ### Main database selection -When a user has multiple roles with access to different databases, the system determines the main database: +When a user has multi-tenant roles with access to different databases, the system determines the main database: ```cypher -- Create roles with different main databases @@ -215,16 +248,19 @@ SET MAIN DATABASE db2 FOR role2; -- User with both roles CREATE USER user1 IDENTIFIED BY 'password'; -ADD ROLE role1 TO user1; -ADD ROLE role2 TO user1; +SET ROLE role1 FOR user1 ON db1; +SET ROLE role2 FOR user1 ON db2; --- The first role's main database becomes the user's main database -SHOW PRIVILEGES FOR user1; -- Shows db1 as main database ``` + +In case of an SSO connection, no user information is stored in Memgraph; instead the auth module returns roles associated with the connection. +In this case, there are no guarantees which role's main database will be selected. Use "database" in the session arguments to define the target database. + + ### Database-specific permission filtering -When accessing a specific database, only roles with access to that database are considered: +The special logic ensures that when accessing a specific database, only roles assigned to that database are considered: ```cypher -- Role with access to multiple databases @@ -236,7 +272,8 @@ GRANT MATCH ON db2 TO multi_db_role; -- User with this role CREATE USER user1 IDENTIFIED BY 'password'; -ADD ROLE multi_db_role TO user1; +SET ROLE multi_db_role FOR user1 ON db1; +SET ROLE multi_db_role FOR user1 ON db2; -- When accessing db1: has MATCH, CREATE -- When accessing db2: has only MATCH @@ -246,45 +283,7 @@ ADD ROLE multi_db_role TO user1; 1. **Use descriptive role names**: Include tenant information in role names (e.g., `tenant1_admin`, `tenant2_user`) 2. **Follow principle of least privilege**: Grant only necessary permissions to each role -3. **Separate global and tenant-specific roles**: Use global roles for cross-tenant access, tenant-specific roles for isolation -4. **Test permission combinations**: Verify that combined permissions work as expected in each database +3. **Separate tenant-specific roles**: Create distinct roles for each tenant to ensure proper isolation +4. **Test permission combinations**: Verify that multi-tenant permissions work correctly in each database 5. **Document role assignments**: Keep track of which users have which roles for which databases 6. **Use deny sparingly**: Remember that deny takes precedence over grant across all databases - -## Migration from single roles - -Existing users with single roles will continue to work without changes. To migrate to multiple roles in a multi-tenant environment: - -1. **Audit current roles**: Review existing role assignments and database access -2. **Plan multi-tenant structure**: Design how to split roles across databases -3. **Create database-specific roles**: Define roles for each tenant/database -4. **Test in development**: Verify permission combinations work correctly in each database -5. **Migrate gradually**: Use `ADD ROLE` to add new roles before removing old ones - -## Troubleshooting - -### Permission conflicts across databases - -If a user has conflicting permissions across roles in different databases: - -```cypher --- Role A grants CREATE on db1 -GRANT CREATE ON db1 TO role_a; - --- Role B denies CREATE on db2 -DENY CREATE ON db2 TO role_b; - --- User with both roles -ADD ROLE role_a TO user; -ADD ROLE role_b TO user; - --- Result: User can CREATE on db1, cannot CREATE on db2 -``` - -### Database access conflicts - -Similar rules apply to database access - if any role denies access to a database, the user will be denied access to that database, even if other roles grant access. - -### Performance considerations - -Multiple roles with database filtering may slightly impact permission checking performance, but this is typically negligible in most deployments. The database filtering ensures that only relevant roles are considered for each database access. \ No newline at end of file diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 43d71208a..71cc02cc8 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -20,6 +20,10 @@ privileges to roles, but for even more control over who can access certain data, Memgraph Enterprise offers [fine-grained access control](#fine-grained-access-control). + +[Multiple roles per user and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) for more information regarding assigning multiple roles to users or assigning roles for a specific database. + + ## User roles Users can be assigned multiple roles simultaneously, with permissions from all roles being combined. User roles are abstractions diff --git a/pages/database-management/authentication-and-authorization/users.mdx b/pages/database-management/authentication-and-authorization/users.mdx index 60d4e2185..67576102c 100644 --- a/pages/database-management/authentication-and-authorization/users.mdx +++ b/pages/database-management/authentication-and-authorization/users.mdx @@ -16,7 +16,7 @@ control](/database-management/authentication-and-authorization/role-based-access and [auth system integrations](/database-management/authentication-and-authorization/auth-system-integrations). -Memgraph Enterprise now supports multiple roles per user, allowing users to have different roles simultaneously with combined permissions. See the [role-based access control](/database-management/authentication-and-authorization/role-based-access-control) section for details on managing multiple roles. +Memgraph Enterprise now supports database-specific roles for a user, allowing users to have different roles on specific databases. See the [role-based access control](/database-management/authentication-and-authorization/role-based-access-control) section for details on managing multiple roles. ## Administer users From 8f7a4a4c504c10abb8fa24370124c9d91c59b3fa Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 15:08:06 +0200 Subject: [PATCH 03/17] env var --- .../auth-system-integrations.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index 73b19c255..832a5eb5d 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -206,12 +206,21 @@ identity service roles correspond to Memgraph’s. The role mapping is defined as a string where individual mappings are separated by a semicolon `;`. Each mapping is structured as follows: -`{identity service role}:{Memgraph role}`. +`{identity service role}:{Memgraph role}, {another Memgraph role}, ...`. + +One identity service role can be mapped to one or more Memgraph roles. +When a user logs in and is assigned an identity service role that is mapped to an array of Memgraph roles, the user is assigned all of the mapped Memgraph roles. +For more information regarding how multi-role users are handled by Mmegraph, please visit [Multiple roles per user and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles). For example, the `entra.admin:memadmin; entra.user:memuser` mapping defines that the identity service roles `entra.admin` and `entra.user` respectively map to Memgraph’s `memadmin` and `memuser` roles. +`entra.admin:memadmin; entra.user:memuser, memdev` maps `entra.user` to `memuser` and `memdev`. + +Different services use different parameters for defining roles. +Use `MEMGRAPH_SSO_{provider}_{protocol}_ROLE_FILED` to specify the token parameter that specifies the assigned roles. + For correct operation, the Memgraph roles defined in the mapping need to be From 1ebc068c6633112c86e6da8126878a152cf2036f Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 16:38:37 +0200 Subject: [PATCH 04/17] auth database --- .../authentication-and-authorization.mdx | 22 +++++++ .../multiple-roles.mdx | 57 ++++++++++++++++++ .../role-based-access-control.mdx | 60 +++++++++++++++++++ pages/database-management/multi-tenancy.md | 59 ++++++++++++++++++ pages/help-center/errors/auth.mdx | 40 +++++++++++++ 5 files changed, 238 insertions(+) diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 8f16579b7..2300c5505 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -9,6 +9,28 @@ 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. +## Recent changes to authentication requirements + +Recent updates to Memgraph have introduced 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. Users must be explicitly granted this privilege to perform user and role management operations. + +### Default database access requirement + +In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. + +### 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 operations have appropriate access + +For detailed information about these requirements and best practices, see the [Role-based access control](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements) and [Multi-tenancy](/database-management/multi-tenancy#default-database-best-practices) documentation. + ## [Users](/database-management/authentication-and-authorization/users) Learn how to manage users in Memgraph. diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index f32e3a18f..faff85141 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -17,6 +17,59 @@ Key benefits: - **Tenant Isolation**: Users can have different permissions for different databases - **SSO Integration**: Support for external identity providers that return multiple roles +## Authentication and authorization requirements + +Recent changes to Memgraph have introduced new requirements for authentication and authorization operations in multi-tenant environments. These changes affect how users can perform user and role management operations. + +### AUTH privilege requirement + +Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be explicitly granted this privilege to perform user and role management operations. + +### Default database access requirement + +In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. + + +**Multi-tenant environments**: This requirement is only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, this requirement is automatically satisfied. + + +### Impact on multi-tenant role management + +When using multi-tenant roles, ensure that users who need to perform authentication and authorization operations have: +1. The `AUTH` privilege granted to their roles +2. Access to the default "memgraph" database +3. Appropriate role assignments for the "memgraph" database + +#### Example: Admin user with multi-tenant roles + +```cypher +-- Create admin role with full privileges +CREATE ROLE system_admin; +GRANT ALL PRIVILEGES TO system_admin; +GRANT DATABASE memgraph TO system_admin; + +-- Create tenant-specific admin roles +CREATE ROLE tenant1_admin; +CREATE ROLE tenant2_admin; +GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant1_admin; +GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant2_admin; +GRANT DATABASE tenant1_db TO tenant1_admin; +GRANT DATABASE tenant2_db TO tenant2_admin; + +-- Create admin user +CREATE USER admin_user IDENTIFIED BY 'admin_password'; + +-- Assign roles with database-specific assignments +SET ROLE FOR admin_user TO system_admin ON memgraph; +SET ROLE FOR admin_user TO tenant1_admin ON tenant1_db; +SET ROLE FOR admin_user TO tenant2_admin ON tenant2_db; +``` + +In this setup, `admin_user` can: +- Perform authentication/authorization operations when connected to the "memgraph" database +- Manage tenant1_db data when connected to tenant1_db +- Manage tenant2_db data when connected to tenant2_db + ## Database access with users and roles ### Basic database access @@ -287,3 +340,7 @@ SET ROLE multi_db_role FOR user1 ON db2; 4. **Test permission combinations**: Verify that multi-tenant permissions work correctly in each database 5. **Document role assignments**: Keep track of which users have which roles for which databases 6. **Use deny sparingly**: Remember that deny takes precedence over grant across all databases +7. **Treat memgraph database as admin database**: In multi-tenant environments, restrict access to the default "memgraph" database to privileged users only +8. **Ensure AUTH privilege access**: Users who need to perform authentication/authorization operations must have both the `AUTH` privilege and access to the "memgraph" database +9. **Separate application data**: Store all application data in tenant-specific databases, not in the default "memgraph" database +10. **Plan for authentication operations**: Design your role structure to ensure that users who need to manage users and roles have appropriate access to the "memgraph" database diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 71cc02cc8..8ea2fc26e 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -121,6 +121,66 @@ of the following commands: | Privileges to specific labels. | `ALL LABELS` | | Privileges to specific relationships types. | `ALL EDGE TYPES` | +## Authentication and authorization requirements + +Recent changes to Memgraph have modified how user privileges are generated for authentication and authorization operations. These changes affect multi-tenant environments where users have access to databases other than the default "memgraph" database. + +### AUTH privilege requirement + +Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be explicitly granted this privilege to perform user and role management operations. + +### Default database access requirement + +In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. + + +**Multi-tenant environments**: This requirement is only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, this requirement is automatically satisfied. + + +### 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 and authorization 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 and system administration separate from application data + +#### Example setup for multi-tenant environments + +```cypher +-- 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 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 diff --git a/pages/database-management/multi-tenancy.md b/pages/database-management/multi-tenancy.md index f40366fef..31a5b8218 100644 --- a/pages/database-management/multi-tenancy.md +++ b/pages/database-management/multi-tenancy.md @@ -20,6 +20,65 @@ A default database named 'memgraph' is automatically created during startup. New users are granted access only to this default database. The default database name cannot be altered. +### Default database best practices + +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, especially given recent changes to authentication and authorization requirements. + +#### Why treat memgraph as an admin database? + +Recent changes to Memgraph require that users have both the `AUTH` privilege and access to the default "memgraph" database to execute authentication and authorization queries. This requirement affects multi-tenant environments where users might have access to other databases but not the default one. + +#### Recommended setup + +1. **Restrict memgraph database access**: Only grant access to the "memgraph" database to privileged users who need to perform system administration tasks +2. **Use tenant-specific databases**: Store all application data in dedicated tenant databases +3. **Separate concerns**: Keep user management, role management, and system administration separate from application data + +#### Example configuration + +```cypher +-- Create admin role with full system privileges +CREATE ROLE system_admin; +GRANT ALL PRIVILEGES TO system_admin; +GRANT DATABASE memgraph TO system_admin; + +-- Create tenant-specific roles (no access to memgraph database) +CREATE ROLE tenant1_admin; +CREATE ROLE tenant1_user; +CREATE ROLE tenant2_admin; +CREATE ROLE tenant2_user; + +-- Grant appropriate permissions to tenant roles +GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant1_admin; +GRANT MATCH, CREATE, MERGE, SET, DELETE TO tenant1_user; +GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant2_admin; +GRANT MATCH, CREATE, MERGE, SET, DELETE TO tenant2_user; + +-- Grant access only to tenant databases +GRANT DATABASE tenant1_db TO tenant1_admin, tenant1_user; +GRANT DATABASE tenant2_db TO tenant2_admin, tenant2_user; + +-- Create users +CREATE USER system_admin_user IDENTIFIED BY 'admin_password'; +CREATE USER tenant1_admin_user IDENTIFIED BY 't1_admin_pass'; +CREATE USER tenant1_regular_user IDENTIFIED BY 't1_user_pass'; +CREATE USER tenant2_admin_user IDENTIFIED BY 't2_admin_pass'; +CREATE USER tenant2_regular_user IDENTIFIED BY 't2_user_pass'; + +-- Assign roles +SET ROLE FOR system_admin_user TO system_admin; +SET ROLE FOR tenant1_admin_user TO tenant1_admin; +SET ROLE FOR tenant1_regular_user TO tenant1_user; +SET ROLE FOR tenant2_admin_user TO tenant2_admin; +SET ROLE FOR tenant2_regular_user TO tenant2_user; +``` + +In this configuration: +- `system_admin_user` can perform all authentication/authorization operations and has access to the "memgraph" database +- Tenant users can only access their respective tenant databases +- Application data is completely isolated in tenant-specific databases +- The "memgraph" database serves purely as an administrative database + ## Isolated databases Isolated databases within Memgraph function as distinct single-database Memgraph diff --git a/pages/help-center/errors/auth.mdx b/pages/help-center/errors/auth.mdx index 267972e82..cb71bdb14 100644 --- a/pages/help-center/errors/auth.mdx +++ b/pages/help-center/errors/auth.mdx @@ -33,5 +33,45 @@ be missing. Queries that modify a user's authentication data are forbidden while using an auth module. Users are handled by the module and local users are disabled. +## User doesn't have AUTH privilege + +This error occurs when a user attempts to execute authentication or authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) without the required `AUTH` privilege. + +### Solution + +Grant the `AUTH` privilege to the user or their role: + +```cypher +-- Grant AUTH privilege to a user +GRANT AUTH TO username; + +-- Grant AUTH privilege to a role +GRANT AUTH TO role_name; +``` + +### Multi-tenant environments + +In multi-tenant environments, users must also have access to the default "memgraph" database to execute authentication and authorization queries. See the [authentication requirements documentation](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements) for more details. + +## User doesn't have access to the memgraph database [#error-4] + +This error occurs in multi-tenant environments when a user attempts to execute authentication or authorization queries but doesn't have access to the default "memgraph" database. + +### Solution + +Grant access to the "memgraph" database to the user or their role: + +```cypher +-- Grant access to memgraph database for a user +GRANT DATABASE memgraph TO username; + +-- Grant access to memgraph database for a role +GRANT DATABASE memgraph TO role_name; +``` + +### Best practice + +In multi-tenant environments, we recommend treating the "memgraph" database as an administrative/system database and restricting access to privileged users only. See the [multi-tenancy documentation](/database-management/multi-tenancy#default-database-best-practices) for recommended setup patterns. + \ No newline at end of file From 02e958a8ee21a4a0ba2e0f11d91731c4c4c13594 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 16:43:22 +0200 Subject: [PATCH 05/17] repl/mt database --- pages/clustering/replication.mdx | 36 +++++++++++ .../authentication-and-authorization.mdx | 8 ++- .../multiple-roles.mdx | 17 ++++-- .../role-based-access-control.mdx | 16 +++-- pages/database-management/multi-tenancy.md | 42 ++++++++++++- pages/help-center/errors/auth.mdx | 60 +++++++++++++++++++ 6 files changed, 165 insertions(+), 14 deletions(-) diff --git a/pages/clustering/replication.mdx b/pages/clustering/replication.mdx index 9ce205d61..c25e2d7a9 100644 --- a/pages/clustering/replication.mdx +++ b/pages/clustering/replication.mdx @@ -154,6 +154,42 @@ When dropping a database used on a REPLICA, the REPLICA will receive the command and will partially drop the database. It will hide the database and prevent any new usage. Once all clients have released the database, it will be deleted entirely. +## Replication queries and the memgraph database + +Recent changes to Memgraph have modified how replication queries are executed. Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) now target the default "memgraph" database and require access to it. + +### Requirements for replication queries + +To execute replication queries, users must have: +1. The `REPLICATION` privilege +2. Access to the default "memgraph" database + +### Impact on multi-tenant environments + +In multi-tenant environments where users might not have access to the "memgraph" database, replication management operations will fail. This reinforces the recommendation to treat the "memgraph" database as an administrative/system database. + +#### Example: Admin user with replication privileges + +```cypher +-- Create admin role with replication privileges +CREATE ROLE replication_admin; +GRANT REPLICATION TO replication_admin; +GRANT DATABASE memgraph TO replication_admin; + +-- Create user with replication admin role +CREATE USER repl_admin IDENTIFIED BY 'admin_password'; +SET ROLE FOR repl_admin TO replication_admin; +``` + +In this setup, `repl_admin` can: +- Execute all replication queries (`REGISTER REPLICA`, `SHOW REPLICAS`, etc.) +- Access the "memgraph" database for administrative operations +- Manage the replication cluster configuration + +### Best practice + +For replication management, ensure that users who need to perform replication operations have both the `REPLICATION` privilege and access to the "memgraph" database. This aligns with the overall recommendation to treat the "memgraph" database as an administrative database in multi-tenant environments. + ## Running multiple instances When running multiple instances, each on its own machine, run Memgraph as you diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 2300c5505..ca93ce071 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -21,15 +21,19 @@ Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. +### Replication and multi-database queries + +Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. + ### 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 operations have appropriate access +- 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](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements) and [Multi-tenancy](/database-management/multi-tenancy#default-database-best-practices) documentation. +For detailed information about these requirements and best practices, see the [Role-based access control](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements), [Multi-tenancy](/database-management/multi-tenancy#default-database-best-practices), and [Replication](/clustering/replication#replication-queries-and-the-memgraph-database) documentation. ## [Users](/database-management/authentication-and-authorization/users) diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index faff85141..2d5ee976e 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -29,14 +29,18 @@ Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. +### Replication and multi-database queries + +Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. + -**Multi-tenant environments**: This requirement is only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, this requirement is automatically satisfied. +**Multi-tenant environments**: These requirements are only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, these requirements are automatically satisfied. ### Impact on multi-tenant role management -When using multi-tenant roles, ensure that users who need to perform authentication and authorization operations have: -1. The `AUTH` privilege granted to their roles +When using multi-tenant roles, ensure that users who need to perform authentication, authorization, replication, or multi-database operations have: +1. The appropriate privileges (`AUTH`, `REPLICATION`, `MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) 2. Access to the default "memgraph" database 3. Appropriate role assignments for the "memgraph" database @@ -67,6 +71,7 @@ SET ROLE FOR admin_user TO tenant2_admin ON tenant2_db; In this setup, `admin_user` can: - Perform authentication/authorization operations when connected to the "memgraph" database +- Execute replication and multi-database queries when connected to the "memgraph" database - Manage tenant1_db data when connected to tenant1_db - Manage tenant2_db data when connected to tenant2_db @@ -342,5 +347,7 @@ SET ROLE multi_db_role FOR user1 ON db2; 6. **Use deny sparingly**: Remember that deny takes precedence over grant across all databases 7. **Treat memgraph database as admin database**: In multi-tenant environments, restrict access to the default "memgraph" database to privileged users only 8. **Ensure AUTH privilege access**: Users who need to perform authentication/authorization operations must have both the `AUTH` privilege and access to the "memgraph" database -9. **Separate application data**: Store all application data in tenant-specific databases, not in the default "memgraph" database -10. **Plan for authentication operations**: Design your role structure to ensure that users who need to manage users and roles have appropriate access to the "memgraph" database +9. **Ensure replication privilege access**: Users who need to perform replication operations must have both the `REPLICATION` privilege and access to the "memgraph" database +10. **Ensure multi-database privilege access**: Users who need to perform multi-database operations must have the appropriate privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) and access to the "memgraph" database +11. **Separate application data**: Store all application data in tenant-specific databases, not in the default "memgraph" database +12. **Plan for administrative operations**: Design your role structure to ensure that users who need to manage users, roles, replication, or multi-database operations have appropriate access to the "memgraph" database diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 8ea2fc26e..00af1ca1e 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -133,17 +133,25 @@ Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. +### Replication and multi-database queries + +Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. + +To execute these queries, users must have: +- The appropriate privileges (`REPLICATION`, `MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) +- Access to the default "memgraph" database + -**Multi-tenant environments**: This requirement is only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, this requirement is automatically satisfied. +**Multi-tenant environments**: These requirements are only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, these requirements are automatically satisfied. ### 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 and authorization operations +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 and system administration separate from application data +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 @@ -177,7 +185,7 @@ 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 operations +- `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 diff --git a/pages/database-management/multi-tenancy.md b/pages/database-management/multi-tenancy.md index 31a5b8218..b358e23b1 100644 --- a/pages/database-management/multi-tenancy.md +++ b/pages/database-management/multi-tenancy.md @@ -26,13 +26,13 @@ In multi-tenant environments, we recommend treating the default "memgraph" datab #### Why treat memgraph as an admin database? -Recent changes to Memgraph require that users have both the `AUTH` privilege and access to the default "memgraph" database to execute authentication and authorization queries. This requirement affects multi-tenant environments where users might have access to other databases but not the default one. +Recent changes to Memgraph require that users have both the `AUTH` privilege and access to the default "memgraph" database to execute authentication and authorization queries. Additionally, replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, etc.) also now target the "memgraph" database and require access to it. This requirement affects multi-tenant environments where users might have access to other databases but not the default one. #### Recommended setup 1. **Restrict memgraph database access**: Only grant access to the "memgraph" database to privileged users who need to perform system administration tasks 2. **Use tenant-specific databases**: Store all application data in dedicated tenant databases -3. **Separate concerns**: Keep user management, role management, and system administration separate from application data +3. **Separate concerns**: Keep user management, role management, system administration, replication management, and multi-database management separate from application data #### Example configuration @@ -74,7 +74,7 @@ SET ROLE FOR tenant2_regular_user TO tenant2_user; ``` In this configuration: -- `system_admin_user` can perform all authentication/authorization operations and has access to the "memgraph" database +- `system_admin_user` can perform all authentication/authorization, replication, and multi-database operations and has access to the "memgraph" database - Tenant users can only access their respective tenant databases - Application data is completely isolated in tenant-specific databases - The "memgraph" database serves purely as an administrative database @@ -140,6 +140,42 @@ Access to all databases can be granted or revoked using wildcards: `GRANT DATABASE * TO user;`, `DENY DATABASE * TO user;` or `REVOKE DATABASE * FROM user;`. +### Multi-database queries and the memgraph database + +Recent changes to Memgraph have modified how multi-database queries are executed. Multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) now target the default "memgraph" database and require access to it. + +#### Requirements for multi-database queries + +To execute multi-database queries, users must have: +1. The appropriate multi-database privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) +2. Access to the default "memgraph" database + +#### Impact on multi-tenant environments + +In multi-tenant environments where users might not have access to the "memgraph" database, multi-database management operations will fail. This reinforces the recommendation to treat the "memgraph" database as an administrative/system database. + +#### Example: Admin user with multi-database privileges + +```cypher +-- Create admin role with multi-database privileges +CREATE ROLE multi_db_admin; +GRANT MULTI_DATABASE_USE, MULTI_DATABASE_EDIT TO multi_db_admin; +GRANT DATABASE memgraph TO multi_db_admin; + +-- Create user with multi-database admin role +CREATE USER db_admin IDENTIFIED BY 'admin_password'; +SET ROLE FOR db_admin TO multi_db_admin; +``` + +In this setup, `db_admin` can: +- Execute all multi-database queries (`SHOW DATABASES`, `CREATE DATABASE`, etc.) +- Access the "memgraph" database for administrative operations +- Manage the multi-tenant database configuration + +#### Best practice + +For multi-database management, ensure that users who need to perform multi-database operations have both the appropriate multi-database privileges and access to the "memgraph" database. This aligns with the overall recommendation to treat the "memgraph" database as an administrative database in multi-tenant environments. + ### Additional multi-tenant privileges Administrators manage multi-tenant privileges with: diff --git a/pages/help-center/errors/auth.mdx b/pages/help-center/errors/auth.mdx index cb71bdb14..976243787 100644 --- a/pages/help-center/errors/auth.mdx +++ b/pages/help-center/errors/auth.mdx @@ -73,5 +73,65 @@ GRANT DATABASE memgraph TO role_name; In multi-tenant environments, we recommend treating the "memgraph" database as an administrative/system database and restricting access to privileged users only. See the [multi-tenancy documentation](/database-management/multi-tenancy#default-database-best-practices) for recommended setup patterns. +## User doesn't have REPLICATION privilege + +This error occurs when a user attempts to execute replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) without the required `REPLICATION` privilege. + +### Solution + +Grant the `REPLICATION` privilege to the user or their role: + +```cypher +-- Grant REPLICATION privilege to a user +GRANT REPLICATION TO username; + +-- Grant REPLICATION privilege to a role +GRANT REPLICATION TO role_name; +``` + +### Multi-tenant environments + +In multi-tenant environments, users must also have access to the default "memgraph" database to execute replication queries. See the [replication documentation](/clustering/replication#replication-queries-and-the-memgraph-database) for more details. + +## User doesn't have MULTI_DATABASE_USE privilege [#error-6] + +This error occurs when a user attempts to execute multi-database queries (such as `SHOW DATABASES`, `USE DATABASE`) without the required `MULTI_DATABASE_USE` privilege. + +### Solution + +Grant the `MULTI_DATABASE_USE` privilege to the user or their role: + +```cypher +-- Grant MULTI_DATABASE_USE privilege to a user +GRANT MULTI_DATABASE_USE TO username; + +-- Grant MULTI_DATABASE_USE privilege to a role +GRANT MULTI_DATABASE_USE TO role_name; +``` + +### Multi-tenant environments + +In multi-tenant environments, users must also have access to the default "memgraph" database to execute multi-database queries. See the [multi-tenancy documentation](/database-management/multi-tenancy#multi-database-queries-and-the-memgraph-database) for more details. + +## User doesn't have MULTI_DATABASE_EDIT privilege [#error-7] + +This error occurs when a user attempts to execute multi-database management queries (such as `CREATE DATABASE`, `DROP DATABASE`) without the required `MULTI_DATABASE_EDIT` privilege. + +### Solution + +Grant the `MULTI_DATABASE_EDIT` privilege to the user or their role: + +```cypher +-- Grant MULTI_DATABASE_EDIT privilege to a user +GRANT MULTI_DATABASE_EDIT TO username; + +-- Grant MULTI_DATABASE_EDIT privilege to a role +GRANT MULTI_DATABASE_EDIT TO role_name; +``` + +### Multi-tenant environments + +In multi-tenant environments, users must also have access to the default "memgraph" database to execute multi-database management queries. See the [multi-tenancy documentation](/database-management/multi-tenancy#multi-database-queries-and-the-memgraph-database) for more details. + \ No newline at end of file From 2a47f1bec43497388f1a9123fe1a072f5bd189d5 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 17:30:44 +0200 Subject: [PATCH 06/17] SHOW ROLES/PRIVILEGES ON --- .../authentication-and-authorization.mdx | 48 ++++++++++++++++ .../multiple-roles.mdx | 40 +++++++++++++ .../role-based-access-control.mdx | 57 +++++++++++++++++++ pages/database-management/multi-tenancy.md | 52 +++++++++++++++-- pages/help-center/errors/auth.mdx | 56 ++++++++++++++++++ 5 files changed, 248 insertions(+), 5 deletions(-) diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index ca93ce071..528d9f73b 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -25,6 +25,54 @@ In addition to the `AUTH` privilege, users must also have access to the default Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. +To execute these queries, users must have: +- The appropriate privileges (`REPLICATION`, `MULTI_DATABASE_EDIT`) +- Access to the default "memgraph" database + +## Multi-tenant query syntax changes + +Recent changes to Memgraph have also modified the syntax for certain queries in multi-tenant environments. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context. + +### SHOW ROLE syntax in multi-tenant environments + +In multi-tenant environments, you must specify which database context to use when showing roles: + +1. **Show roles for the user's main database:** +```cypher +SHOW ROLE FOR user_name ON MAIN; +``` + +2. **Show roles for the current database:** +```cypher +SHOW ROLE FOR user_name ON CURRENT; +``` + +3. **Show roles for a specific database:** +```cypher +SHOW ROLE FOR user_name ON DATABASE database_name; +``` + +### SHOW PRIVILEGES syntax in multi-tenant environments + +Similarly, the `SHOW PRIVILEGES` command requires database context specification: + +1. **Show privileges for the user's main database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON MAIN; +``` + +2. **Show privileges for the current database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON CURRENT; +``` + +3. **Show privileges for a specific database:** +```cypher +SHOW PRIVILEGES FOR user_or_role 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. + ### Multi-tenant recommendations For multi-tenant environments, we recommend: diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index 2d5ee976e..ee4f8257b 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -262,6 +262,25 @@ To see which roles a user has for a specific database: SHOW ROLES FOR user_name ON database_name; ``` +In multi-tenant environments, you can also use these additional options: + +1. **Show roles for the user's main database:** +```cypher +SHOW ROLES FOR user_name ON MAIN; +``` + +2. **Show roles for the current database:** +```cypher +SHOW ROLES FOR user_name ON CURRENT; +``` + +3. **Show roles for a specific database:** +```cypher +SHOW ROLES FOR user_name ON DATABASE database_name; +``` + +These commands return the aggregated roles for the user in the specified database context. + ### Viewing permissions for a specific database To see what permissions a user has in a specific database: @@ -270,6 +289,24 @@ To see what permissions a user has in a specific database: SHOW PRIVILEGES FOR user_name ON database_name; ``` +In multi-tenant environments, you can also use these additional options: + +1. **Show privileges for the user's main database:** +```cypher +SHOW PRIVILEGES FOR user_name ON MAIN; +``` + +2. **Show privileges for the current database:** +```cypher +SHOW PRIVILEGES FOR user_name ON CURRENT; +``` + +3. **Show privileges for a specific database:** +```cypher +SHOW PRIVILEGES FOR user_name ON DATABASE database_name; +``` + +These commands return the aggregated privileges for the user in the specified database context. ### SSO integration with multi-tenant roles @@ -351,3 +388,6 @@ SET ROLE multi_db_role FOR user1 ON db2; 10. **Ensure multi-database privilege access**: Users who need to perform multi-database operations must have the appropriate privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) and access to the "memgraph" database 11. **Separate application data**: Store all application data in tenant-specific databases, not in the default "memgraph" database 12. **Plan for administrative operations**: Design your role structure to ensure that users who need to manage users, roles, replication, or multi-database operations have appropriate access to the "memgraph" database +13. **Use explicit database context**: Always specify the database context when using `SHOW ROLE` and `SHOW PRIVILEGES` commands in multi-tenant environments +14. **Choose appropriate context**: Use `ON MAIN` for the user's main database, `ON CURRENT` for the currently active database, or `ON DATABASE` for a specific database +15. **Verify permissions in context**: Always check roles and privileges in the specific database context where they will be used diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 00af1ca1e..f5c40edb7 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -79,6 +79,25 @@ To show what roles a user has, run the following query: SHOW ROLE FOR user_name; ``` +In multi-tenant environments, you must specify which database context to use when showing roles. There are three options: + +1. **Show roles for the user's main database:** +```cypher +SHOW ROLE FOR user_name ON MAIN; +``` + +2. **Show roles for the current database:** +```cypher +SHOW ROLE FOR user_name ON CURRENT; +``` + +3. **Show roles for a specific database:** +```cypher +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. + TODO: multi-tenant environment show role for user_name To list all defined user roles run: @@ -295,6 +314,25 @@ To check privilege for a certain user or role, run the following query: SHOW PRIVILEGES FOR user_or_role; ``` +In multi-tenant environments, you must specify which database context to use when showing privileges. There are three options: + +1. **Show privileges for the user's main database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON MAIN; +``` + +2. **Show privileges for the current database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON CURRENT; +``` + +3. **Show privileges for a specific database:** +```cypher +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. + ## Fine-grained access control Sometimes, authorizing the database by granting and denying clause privileges is @@ -398,6 +436,25 @@ SHOW PRIVILEGES FOR user_or_role; and all the values of clause privileges, as well as label-based permissions will be displayed. +In multi-tenant environments, you must specify which database context to use when showing privileges. There are three options: + +1. **Show privileges for the user's main database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON MAIN; +``` + +2. **Show privileges for the current database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON CURRENT; +``` + +3. **Show privileges for a specific database:** +```cypher +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. + ### Templates for granting privileges To grant all privileges to a superuser (admin): diff --git a/pages/database-management/multi-tenancy.md b/pages/database-management/multi-tenancy.md index b358e23b1..bed438b3b 100644 --- a/pages/database-management/multi-tenancy.md +++ b/pages/database-management/multi-tenancy.md @@ -142,13 +142,55 @@ Access to all databases can be granted or revoked using wildcards: ### Multi-database queries and the memgraph database -Recent changes to Memgraph have modified how multi-database queries are executed. Multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) now target the default "memgraph" database and require access to it. +Recent changes to Memgraph have modified how multi-database queries are executed. Multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) now target the "memgraph" database and require access to it. -#### Requirements for multi-database queries +To execute these queries, users must have: +- The appropriate privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) +- Access to the default "memgraph" database -To execute multi-database queries, users must have: -1. The appropriate multi-database privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) -2. Access to the default "memgraph" database +### Multi-tenant query syntax changes + +Recent changes to Memgraph have also modified the syntax for certain queries in multi-tenant environments. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context. + +#### SHOW ROLE syntax in multi-tenant environments + +In multi-tenant environments, you must specify which database context to use when showing roles: + +1. **Show roles for the user's main database:** +```cypher +SHOW ROLE FOR user_name ON MAIN; +``` + +2. **Show roles for the current database:** +```cypher +SHOW ROLE FOR user_name ON CURRENT; +``` + +3. **Show roles for a specific database:** +```cypher +SHOW ROLE FOR user_name ON DATABASE database_name; +``` + +#### SHOW PRIVILEGES syntax in multi-tenant environments + +Similarly, the `SHOW PRIVILEGES` command requires database context specification: + +1. **Show privileges for the user's main database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON MAIN; +``` + +2. **Show privileges for the current database:** +```cypher +SHOW PRIVILEGES FOR user_or_role ON CURRENT; +``` + +3. **Show privileges for a specific database:** +```cypher +SHOW PRIVILEGES FOR user_or_role 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. #### Impact on multi-tenant environments diff --git a/pages/help-center/errors/auth.mdx b/pages/help-center/errors/auth.mdx index 976243787..4da402001 100644 --- a/pages/help-center/errors/auth.mdx +++ b/pages/help-center/errors/auth.mdx @@ -73,6 +73,62 @@ GRANT DATABASE memgraph TO role_name; In multi-tenant environments, we recommend treating the "memgraph" database as an administrative/system database and restricting access to privileged users only. See the [multi-tenancy documentation](/database-management/multi-tenancy#default-database-best-practices) for recommended setup patterns. +## Database context must be specified for SHOW ROLE in multi-tenant environment + +This error occurs when attempting to use `SHOW ROLE` or `SHOW ROLES` in a multi-tenant environment without specifying the database context. + +### Solution + +In multi-tenant environments, you must specify which database context to use: + +```cypher +-- 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; +``` + +### When this occurs + +This error typically occurs when: +- Running `SHOW ROLE` or `SHOW ROLES` in a multi-tenant environment +- The system detects multiple databases and requires explicit context specification +- The user is connected to a multi-tenant Memgraph instance + +## Database context must be specified for SHOW PRIVILEGES in multi-tenant environment [#error-9] + +This error occurs when attempting to use `SHOW PRIVILEGES` in a multi-tenant environment without specifying the database context. + +### Solution + +In multi-tenant environments, you must specify which database context to use: + +```cypher +-- Show privileges for the user's main database +SHOW PRIVILEGES FOR user_or_role ON MAIN; + +-- Show privileges for the current database +SHOW PRIVILEGES FOR user_or_role ON CURRENT; + +-- Show privileges for a specific database +SHOW PRIVILEGES FOR user_or_role ON DATABASE database_name; +``` + +### When this occurs + +This error typically occurs when: +- Running `SHOW PRIVILEGES` in a multi-tenant environment +- The system detects multiple databases and requires explicit context specification +- The user is connected to a multi-tenant Memgraph instance + +### Best practice + +Always specify the database context when working in multi-tenant environments to ensure you're viewing the correct roles and privileges for the intended database. + ## User doesn't have REPLICATION privilege This error occurs when a user attempts to execute replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) without the required `REPLICATION` privilege. From 0d795ba10dd8ae1dc764466306b7ee09a479715f Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 14:49:21 +0200 Subject: [PATCH 07/17] mt fixes --- .../role-based-access-control.mdx | 12 ++++-- .../users.mdx | 4 ++ pages/database-management/multi-tenancy.md | 13 +++++-- pages/help-center/errors/auth.mdx | 37 ++++++++++++++----- 4 files changed, 49 insertions(+), 17 deletions(-) diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index f5c40edb7..5eb3acad3 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -79,7 +79,9 @@ To show what roles a user has, run the following query: SHOW ROLE FOR user_name; ``` -In multi-tenant environments, you must specify which database context to use when showing roles. There are three options: +**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. + +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:** ```cypher @@ -98,8 +100,6 @@ 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. -TODO: multi-tenant environment show role for user_name - To list all defined user roles run: ```cypher @@ -434,9 +434,13 @@ To check which privileges an existing user or role has in Memgraph, it is enough SHOW PRIVILEGES FOR user_or_role; ``` +**Note**: +- For **roles**: This command does not require database specification, even in multi-tenant environments. It will show all privileges for the role. +- For **users**: In multi-tenant environments, you must specify the database context. + and all the values of clause privileges, as well as label-based permissions will be displayed. -In multi-tenant environments, you must specify which database context to use when showing privileges. There are three options: +In multi-tenant environments, you must specify which database context to use when showing privileges for users. There are three options: 1. **Show privileges for the user's main database:** ```cypher diff --git a/pages/database-management/authentication-and-authorization/users.mdx b/pages/database-management/authentication-and-authorization/users.mdx index 67576102c..7893b0db5 100644 --- a/pages/database-management/authentication-and-authorization/users.mdx +++ b/pages/database-management/authentication-and-authorization/users.mdx @@ -19,6 +19,10 @@ and [auth system integrations](/database-management/authentication-and-authoriza Memgraph Enterprise now supports database-specific roles for a user, allowing users to have different roles on specific databases. See the [role-based access control](/database-management/authentication-and-authorization/role-based-access-control) section for details on managing multiple roles. + +**Backward Compatibility**: Memgraph automatically migrates existing single-role users to the new multi-role format during startup. This migration is transparent and requires no user intervention. Existing users and their roles will continue to work without any changes. + + ## Administer users Creating a user can be done by executing the following command: diff --git a/pages/database-management/multi-tenancy.md b/pages/database-management/multi-tenancy.md index bed438b3b..3f7d33664 100644 --- a/pages/database-management/multi-tenancy.md +++ b/pages/database-management/multi-tenancy.md @@ -110,7 +110,8 @@ Users interact with multi-tenant features through specialized Cypher queries: 1. `CREATE DATABASE name`: Creates a new database. 2. `DROP DATABASE name`: Deletes a specified database. 3. `SHOW DATABASE`: Shows the current used database. It will return `NULL` if - there is not one. + no database is currently in use. You can also use `SHOW CURRENT DATABASE` for the same functionality. This command does not require any special privileges. + 4. `SHOW DATABASES`: Shows only the existing set of multitenant databases. 5. `USE DATABASE name`: Switches focus to a specific database (disabled during transactions). @@ -150,11 +151,15 @@ To execute these queries, users must have: ### Multi-tenant query syntax changes -Recent changes to Memgraph have also modified the syntax for certain queries in multi-tenant environments. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context. +Recent changes to Memgraph have also modified the syntax for certain queries in multi-tenant environments. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context in some cases. + +**SHOW ROLE FOR USER**: This command does not require database specification and will show all roles assigned to the user across all databases. + +**SHOW PRIVILEGES FOR USER**: This command requires database specification in multi-tenant environments. -#### SHOW ROLE syntax in multi-tenant environments +**SHOW PRIVILEGES FOR ROLE**: This command does not require database specification and will show all privileges for the role. -In multi-tenant environments, you must specify which database context to use when showing roles: +In multi-tenant environments, you must specify which database context to use when showing privileges for users: 1. **Show roles for the user's main database:** ```cypher diff --git a/pages/help-center/errors/auth.mdx b/pages/help-center/errors/auth.mdx index 4da402001..32c88b7c5 100644 --- a/pages/help-center/errors/auth.mdx +++ b/pages/help-center/errors/auth.mdx @@ -77,9 +77,19 @@ In multi-tenant environments, we recommend treating the "memgraph" database as a This error occurs when attempting to use `SHOW ROLE` or `SHOW ROLES` in a multi-tenant environment without specifying the database context. +**Note**: This error should no longer occur for `SHOW ROLE FOR USER` commands, as they no longer require database specification. The `SHOW ROLE FOR USER` command will show all roles assigned to the user across all databases. + ### Solution -In multi-tenant environments, you must specify which database context to use: +For `SHOW ROLE FOR USER` commands, you can use them without database specification: + +```cypher +-- 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: ```cypher -- Show roles for the user's main database @@ -95,7 +105,6 @@ SHOW ROLE FOR user_name ON DATABASE database_name; ### When this occurs This error typically occurs when: -- Running `SHOW ROLE` or `SHOW ROLES` in a multi-tenant environment - The system detects multiple databases and requires explicit context specification - The user is connected to a multi-tenant Memgraph instance @@ -103,31 +112,41 @@ This error typically occurs when: This error occurs when attempting to use `SHOW PRIVILEGES` in a multi-tenant environment without specifying the database context. +**Note**: This error only occurs for `SHOW PRIVILEGES FOR USER` commands. The `SHOW PRIVILEGES FOR ROLE` command does not require database specification and will show all privileges for the role. + ### Solution -In multi-tenant environments, you must specify which database context to use: +For `SHOW PRIVILEGES FOR ROLE` commands, you can use them without database specification: + +```cypher +-- Show all privileges for a role (works in all environments) +SHOW PRIVILEGES FOR role_name; +``` + +For `SHOW PRIVILEGES FOR USER` commands in multi-tenant environments, you must specify the database context: ```cypher -- Show privileges for the user's main database -SHOW PRIVILEGES FOR user_or_role ON MAIN; +SHOW PRIVILEGES FOR user_name ON MAIN; -- Show privileges for the current database -SHOW PRIVILEGES FOR user_or_role ON CURRENT; +SHOW PRIVILEGES FOR user_name ON CURRENT; -- Show privileges for a specific database -SHOW PRIVILEGES FOR user_or_role ON DATABASE database_name; +SHOW PRIVILEGES FOR user_name ON DATABASE database_name; ``` ### When this occurs This error typically occurs when: -- Running `SHOW PRIVILEGES` in a multi-tenant environment -- The system detects multiple databases and requires explicit context specification +- Running `SHOW PRIVILEGES FOR USER` in a multi-tenant environment +- The system detects multiple databases and requires explicit context specification for users - The user is connected to a multi-tenant Memgraph instance ### Best practice -Always specify the database context when working in multi-tenant environments to ensure you're viewing the correct roles and privileges for the intended database. +- For roles: Use `SHOW PRIVILEGES FOR role_name` without database specification +- For users: Always specify the database context when working in multi-tenant environments to ensure you're viewing the correct privileges for the intended database ## User doesn't have REPLICATION privilege From c6eccabf8171c979931f3967ae309d6b75ef89e5 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 15:11:44 +0200 Subject: [PATCH 08/17] details --- .../authentication-and-authorization.mdx | 27 ++++++++++++++----- .../multiple-roles.mdx | 8 ++++++ 2 files changed, 29 insertions(+), 6 deletions(-) diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 528d9f73b..f00851da0 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -31,11 +31,19 @@ To execute these queries, users must have: ## Multi-tenant query syntax changes -Recent changes to Memgraph have also modified the syntax for certain queries in multi-tenant environments. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context. +Recent changes to Memgraph have modified the syntax for certain queries in multi-tenant environments. The behavior differs between users and roles: ### SHOW ROLE syntax in multi-tenant environments -In multi-tenant environments, you must specify which database context to use when showing roles: +**SHOW ROLE FOR USER**: This command does not require database specification and will show all roles assigned to the user across all databases. + +```cypher +-- 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: 1. **Show roles for the user's main database:** ```cypher @@ -54,21 +62,28 @@ SHOW ROLE FOR user_name ON DATABASE database_name; ### SHOW PRIVILEGES syntax in multi-tenant environments -Similarly, the `SHOW PRIVILEGES` command requires database context specification: +**SHOW PRIVILEGES FOR ROLE**: This command does not require database specification and will show all privileges for the role. + +```cypher +-- Show all privileges for a role (works in all environments) +SHOW PRIVILEGES FOR role_name; +``` + +**SHOW PRIVILEGES FOR USER**: In multi-tenant environments, you must specify the database context: 1. **Show privileges for the user's main database:** ```cypher -SHOW PRIVILEGES FOR user_or_role ON MAIN; +SHOW PRIVILEGES FOR user_name ON MAIN; ``` 2. **Show privileges for the current database:** ```cypher -SHOW PRIVILEGES FOR user_or_role ON CURRENT; +SHOW PRIVILEGES FOR user_name ON CURRENT; ``` 3. **Show privileges for a specific database:** ```cypher -SHOW PRIVILEGES FOR user_or_role ON DATABASE database_name; +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. diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index ee4f8257b..968bda12b 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -256,6 +256,14 @@ CLEAR ROLE FOR user_name ON database_name; ### Viewing multi-tenant roles +**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. + +```cypher +-- Show all roles for a user (works in all environments) +SHOW ROLE FOR user_name; +SHOW ROLES FOR user_name; +``` + To see which roles a user has for a specific database: ```cypher From 0de7bd84985ebc2ece2a9413a454a839023b8a28 Mon Sep 17 00:00:00 2001 From: andrejtonev <29177572+andrejtonev@users.noreply.github.com> Date: Thu, 21 Aug 2025 16:04:53 +0200 Subject: [PATCH 09/17] Apply suggestions from code review Co-authored-by: Matea Pesic <80577904+matea16@users.noreply.github.com> --- pages/clustering/replication.mdx | 2 +- .../multiple-roles.mdx | 2 +- pages/help-center/errors/auth.mdx | 30 +++++++++---------- 3 files changed, 17 insertions(+), 17 deletions(-) diff --git a/pages/clustering/replication.mdx b/pages/clustering/replication.mdx index c25e2d7a9..301f2bc21 100644 --- a/pages/clustering/replication.mdx +++ b/pages/clustering/replication.mdx @@ -168,7 +168,7 @@ To execute replication queries, users must have: In multi-tenant environments where users might not have access to the "memgraph" database, replication management operations will fail. This reinforces the recommendation to treat the "memgraph" database as an administrative/system database. -#### Example: Admin user with replication privileges +{

Example: Admin user with replication privileges

} ```cypher -- Create admin role with replication privileges diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index 968bda12b..b38a00a36 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -44,7 +44,7 @@ When using multi-tenant roles, ensure that users who need to perform authenticat 2. Access to the default "memgraph" database 3. Appropriate role assignments for the "memgraph" database -#### Example: Admin user with multi-tenant roles +{

Example: Admin user with multi-tenant roles

```cypher -- Create admin role with full privileges diff --git a/pages/help-center/errors/auth.mdx b/pages/help-center/errors/auth.mdx index 32c88b7c5..1ec7da225 100644 --- a/pages/help-center/errors/auth.mdx +++ b/pages/help-center/errors/auth.mdx @@ -37,7 +37,7 @@ an auth module. Users are handled by the module and local users are disabled. This error occurs when a user attempts to execute authentication or authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) without the required `AUTH` privilege. -### Solution +{

Solution

} Grant the `AUTH` privilege to the user or their role: @@ -49,7 +49,7 @@ GRANT AUTH TO username; GRANT AUTH TO role_name; ``` -### Multi-tenant environments +{

Multi-tenant environments

} In multi-tenant environments, users must also have access to the default "memgraph" database to execute authentication and authorization queries. See the [authentication requirements documentation](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements) for more details. @@ -57,7 +57,7 @@ In multi-tenant environments, users must also have access to the default "memgra This error occurs in multi-tenant environments when a user attempts to execute authentication or authorization queries but doesn't have access to the default "memgraph" database. -### Solution +{

Solution

} Grant access to the "memgraph" database to the user or their role: @@ -69,7 +69,7 @@ GRANT DATABASE memgraph TO username; GRANT DATABASE memgraph TO role_name; ``` -### Best practice +{

Best practice

} In multi-tenant environments, we recommend treating the "memgraph" database as an administrative/system database and restricting access to privileged users only. See the [multi-tenancy documentation](/database-management/multi-tenancy#default-database-best-practices) for recommended setup patterns. @@ -79,7 +79,7 @@ This error occurs when attempting to use `SHOW ROLE` or `SHOW ROLES` in a multi- **Note**: This error should no longer occur for `SHOW ROLE FOR USER` commands, as they no longer require database specification. The `SHOW ROLE FOR USER` command will show all roles assigned to the user across all databases. -### Solution +{

Solution

} For `SHOW ROLE FOR USER` commands, you can use them without database specification: @@ -102,7 +102,7 @@ SHOW ROLE FOR user_name ON CURRENT; SHOW ROLE FOR user_name ON DATABASE database_name; ``` -### When this occurs +{

When this occurs

} This error typically occurs when: - The system detects multiple databases and requires explicit context specification @@ -114,7 +114,7 @@ This error occurs when attempting to use `SHOW PRIVILEGES` in a multi-tenant env **Note**: This error only occurs for `SHOW PRIVILEGES FOR USER` commands. The `SHOW PRIVILEGES FOR ROLE` command does not require database specification and will show all privileges for the role. -### Solution +{

Solution

} For `SHOW PRIVILEGES FOR ROLE` commands, you can use them without database specification: @@ -136,14 +136,14 @@ SHOW PRIVILEGES FOR user_name ON CURRENT; SHOW PRIVILEGES FOR user_name ON DATABASE database_name; ``` -### When this occurs +{

When this occurs

} This error typically occurs when: - Running `SHOW PRIVILEGES FOR USER` in a multi-tenant environment - The system detects multiple databases and requires explicit context specification for users - The user is connected to a multi-tenant Memgraph instance -### Best practice +{

Best practice

} - For roles: Use `SHOW PRIVILEGES FOR role_name` without database specification - For users: Always specify the database context when working in multi-tenant environments to ensure you're viewing the correct privileges for the intended database @@ -152,7 +152,7 @@ This error typically occurs when: This error occurs when a user attempts to execute replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) without the required `REPLICATION` privilege. -### Solution +{

Solution

} Grant the `REPLICATION` privilege to the user or their role: @@ -164,7 +164,7 @@ GRANT REPLICATION TO username; GRANT REPLICATION TO role_name; ``` -### Multi-tenant environments +{

Multi-tenant environments

} In multi-tenant environments, users must also have access to the default "memgraph" database to execute replication queries. See the [replication documentation](/clustering/replication#replication-queries-and-the-memgraph-database) for more details. @@ -172,7 +172,7 @@ In multi-tenant environments, users must also have access to the default "memgra This error occurs when a user attempts to execute multi-database queries (such as `SHOW DATABASES`, `USE DATABASE`) without the required `MULTI_DATABASE_USE` privilege. -### Solution +{

Solution

} Grant the `MULTI_DATABASE_USE` privilege to the user or their role: @@ -184,7 +184,7 @@ GRANT MULTI_DATABASE_USE TO username; GRANT MULTI_DATABASE_USE TO role_name; ``` -### Multi-tenant environments +{

Multi-tenant environments

} In multi-tenant environments, users must also have access to the default "memgraph" database to execute multi-database queries. See the [multi-tenancy documentation](/database-management/multi-tenancy#multi-database-queries-and-the-memgraph-database) for more details. @@ -192,7 +192,7 @@ In multi-tenant environments, users must also have access to the default "memgra This error occurs when a user attempts to execute multi-database management queries (such as `CREATE DATABASE`, `DROP DATABASE`) without the required `MULTI_DATABASE_EDIT` privilege. -### Solution +{

Solution

} Grant the `MULTI_DATABASE_EDIT` privilege to the user or their role: @@ -204,7 +204,7 @@ GRANT MULTI_DATABASE_EDIT TO username; GRANT MULTI_DATABASE_EDIT TO role_name; ``` -### Multi-tenant environments +{

Multi-tenant environments

} In multi-tenant environments, users must also have access to the default "memgraph" database to execute multi-database management queries. See the [multi-tenancy documentation](/database-management/multi-tenancy#multi-database-queries-and-the-memgraph-database) for more details. From 1a831288f194b435a846ee6cba04c0048273e6eb Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 17:30:57 +0200 Subject: [PATCH 10/17] recent changes -> as of v3.5 --- pages/clustering/replication.mdx | 7 ++++-- .../authentication-and-authorization.mdx | 22 ++++++++++--------- .../multiple-roles.mdx | 4 ---- .../role-based-access-control.mdx | 10 +++++++-- pages/database-management/multi-tenancy.md | 8 +++---- 5 files changed, 29 insertions(+), 22 deletions(-) diff --git a/pages/clustering/replication.mdx b/pages/clustering/replication.mdx index 301f2bc21..00018b55c 100644 --- a/pages/clustering/replication.mdx +++ b/pages/clustering/replication.mdx @@ -154,9 +154,12 @@ When dropping a database used on a REPLICA, the REPLICA will receive the command and will partially drop the database. It will hide the database and prevent any new usage. Once all clients have released the database, it will be deleted entirely. -## Replication queries and the memgraph database + + +As of Memgraph v3.5 replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) target the default "memgraph" database and require access to it. +The recommendation is to use the default "memgraph" database as an admin/system database and store graphs under other databases. -Recent changes to Memgraph have modified how replication queries are executed. Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) now target the default "memgraph" database and require access to it. + ### Requirements for replication queries diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index f00851da0..26d725f47 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -9,30 +9,32 @@ 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. -## Recent changes to authentication requirements +## Changes to authentication requirements (active from Memgraph v3.5) -Recent updates to Memgraph have introduced new requirements for authentication and authorization operations, particularly affecting multi-tenant environments: +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. 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. + + + ### Default database access requirement In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. -### Replication and multi-database queries +### System queries and multi-database queries -Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. - -To execute these queries, users must have: -- The appropriate privileges (`REPLICATION`, `MULTI_DATABASE_EDIT`) -- Access to the default "memgraph" database +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 query syntax changes -Recent changes to Memgraph have modified the syntax for certain queries in multi-tenant environments. The behavior differs between users and roles: - ### 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. diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index b38a00a36..d3d265b96 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -17,10 +17,6 @@ Key benefits: - **Tenant Isolation**: Users can have different permissions for different databases - **SSO Integration**: Support for external identity providers that return multiple roles -## Authentication and authorization requirements - -Recent changes to Memgraph have introduced new requirements for authentication and authorization operations in multi-tenant environments. These changes affect how users can perform user and role management operations. - ### AUTH privilege requirement Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be explicitly granted this privilege to perform user and role management operations. diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 5eb3acad3..97750fc60 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -142,7 +142,13 @@ of the following commands: ## Authentication and authorization requirements -Recent changes to Memgraph have modified how user privileges are generated for authentication and authorization operations. These changes affect multi-tenant environments where users have access to databases other than the default "memgraph" database. + + +As of Memgraph v3.5 users can have different privileges on different databases. This is due to v3.5 introducing users with multiple roles and database specific roles. +All system queries (auth, replication and multi-database) now target the default "memgraph" database. Meaning that in order to execute one of these queries, a user must have the appropriate privilege AND access to "memgraph" database. +The recommendation is to use the default "memgraph" database as an admin/system database and store graphs under other databases. + + ### AUTH privilege requirement @@ -158,7 +164,7 @@ Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA` To execute these queries, users must have: - The appropriate privileges (`REPLICATION`, `MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) -- Access to the default "memgraph" database +- **AND** access to the default "memgraph" database **Multi-tenant environments**: These requirements are only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, these requirements are automatically satisfied. diff --git a/pages/database-management/multi-tenancy.md b/pages/database-management/multi-tenancy.md index 3f7d33664..6ad2903b0 100644 --- a/pages/database-management/multi-tenancy.md +++ b/pages/database-management/multi-tenancy.md @@ -26,7 +26,7 @@ In multi-tenant environments, we recommend treating the default "memgraph" datab #### Why treat memgraph as an admin database? -Recent changes to Memgraph require that users have both the `AUTH` privilege and access to the default "memgraph" database to execute authentication and authorization queries. Additionally, replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, etc.) also now target the "memgraph" database and require access to it. This requirement affects multi-tenant environments where users might have access to other databases but not the default one. +As of Memgraph v3.5, users have to have both the `AUTH` privilege and access to the default "memgraph" database to execute authentication and authorization queries. Additionally, replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, etc.) also now target the "memgraph" database and require access to it. This requirement affects multi-tenant environments where users might have access to other databases but not the default one. #### Recommended setup @@ -143,15 +143,15 @@ Access to all databases can be granted or revoked using wildcards: ### Multi-database queries and the memgraph database -Recent changes to Memgraph have modified how multi-database queries are executed. Multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) now target the "memgraph" database and require access to it. +As of Memgraph v3.5 multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) target the "memgraph" database and require access to it. To execute these queries, users must have: - The appropriate privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) -- Access to the default "memgraph" database +- **AND** access to the default "memgraph" database ### Multi-tenant query syntax changes -Recent changes to Memgraph have also modified the syntax for certain queries in multi-tenant environments. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context in some cases. +As of Memgraph v3.5 the syntax for certain queries in multi-tenant environments have changed. The `SHOW ROLE` and `SHOW PRIVILEGES` commands now require specifying the database context in some cases. **SHOW ROLE FOR USER**: This command does not require database specification and will show all roles assigned to the user across all databases. From 92ecf63e72bee9c22c842f61492d71ef303d0c8f Mon Sep 17 00:00:00 2001 From: matea16 Date: Thu, 21 Aug 2025 17:44:17 +0200 Subject: [PATCH 11/17] typo --- .../multiple-roles.mdx | 226 ++++++++++++------ 1 file changed, 149 insertions(+), 77 deletions(-) diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index b38a00a36..5c71aa889 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -7,71 +7,95 @@ import { Callout } from 'nextra/components' # Multi-tenant roles (Enterprise) -Memgraph Enterprise supports multi-tenant roles, which allow users to have different roles assigned to them for specific databases. This feature enables proper tenant isolation and fine-grained access control in multi-tenant environments. +Memgraph Enterprise supports multi-tenant roles, which allow users to have +different roles assigned to them for specific databases. This feature enables +proper tenant isolation and fine-grained access control in multi-tenant +environments. ## Overview -Multi-tenant roles are a specialized form of multiple roles that include special logic for database-specific permission filtering. When a user has multi-tenant roles, their permissions are dynamically filtered based on which database they're accessing, ensuring proper tenant isolation. +Multi-tenant roles are a specialized form of multiple roles that include special +logic for database-specific permission filtering. When a user has multi-tenant +roles, their permissions are dynamically filtered based on which database +they're accessing, ensuring proper tenant isolation. Key benefits: -- **Tenant Isolation**: Users can have different permissions for different databases -- **SSO Integration**: Support for external identity providers that return multiple roles +- **Tenant Isolation**: Users can have different permissions for different + databases +- **SSO Integration**: Support for external identity providers that return + multiple roles ## Authentication and authorization requirements -Recent changes to Memgraph have introduced new requirements for authentication and authorization operations in multi-tenant environments. These changes affect how users can perform user and role management operations. +Recent changes to Memgraph have introduced new requirements for authentication +and authorization operations in multi-tenant environments. These changes affect +how users can perform user and role management operations. ### AUTH privilege requirement -Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be explicitly granted this privilege to perform user and role management operations. +Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, +`GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be +explicitly granted this privilege to perform user and role management +operations. ### Default database access requirement -In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. +In addition to the `AUTH` privilege, users must also have access to the default +"memgraph" database to execute authentication and authorization queries. This +requirement applies even when the user is working in other databases within a +multi-tenant environment. ### Replication and multi-database queries -Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. +Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP +REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE +DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and +require access to it. - -**Multi-tenant environments**: These requirements are only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, these requirements are automatically satisfied. - + **Multi-tenant environments**: These requirements are +only a concern in multi-tenant environments where users have access to databases +other than the default "memgraph" database. In single-database deployments, +these requirements are automatically satisfied. ### Impact on multi-tenant role management -When using multi-tenant roles, ensure that users who need to perform authentication, authorization, replication, or multi-database operations have: -1. The appropriate privileges (`AUTH`, `REPLICATION`, `MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) +When using multi-tenant roles, ensure that users who need to perform +authentication, authorization, replication, or multi-database operations have: +1. The appropriate privileges (`AUTH`, `REPLICATION`, `MULTI_DATABASE_USE`, + `MULTI_DATABASE_EDIT`) 2. Access to the default "memgraph" database 3. Appropriate role assignments for the "memgraph" database -{

Example: Admin user with multi-tenant roles

+{

Example: Admin user with multi-tenant roles

} ```cypher --- Create admin role with full privileges -CREATE ROLE system_admin; -GRANT ALL PRIVILEGES TO system_admin; -GRANT DATABASE memgraph TO system_admin; - --- Create tenant-specific admin roles -CREATE ROLE tenant1_admin; -CREATE ROLE tenant2_admin; -GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant1_admin; -GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant2_admin; -GRANT DATABASE tenant1_db TO tenant1_admin; -GRANT DATABASE tenant2_db TO tenant2_admin; - --- Create admin user -CREATE USER admin_user IDENTIFIED BY 'admin_password'; - --- Assign roles with database-specific assignments -SET ROLE FOR admin_user TO system_admin ON memgraph; -SET ROLE FOR admin_user TO tenant1_admin ON tenant1_db; -SET ROLE FOR admin_user TO tenant2_admin ON tenant2_db; + -- Create admin role with full privileges + CREATE ROLE system_admin; + GRANT ALL PRIVILEGES TO system_admin; + GRANT DATABASE memgraph TO system_admin; + + -- Create tenant-specific admin roles + CREATE ROLE tenant1_admin; + CREATE ROLE tenant2_admin; + GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant1_admin; + GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant2_admin; + GRANT DATABASE tenant1_db TO tenant1_admin; + GRANT DATABASE tenant2_db TO tenant2_admin; + + -- Create admin user + CREATE USER admin_user IDENTIFIED BY 'admin_password'; + + -- Assign roles with database-specific assignments + SET ROLE FOR admin_user TO system_admin ON memgraph; + SET ROLE FOR admin_user TO tenant1_admin ON tenant1_db; + SET ROLE FOR admin_user TO tenant2_admin ON tenant2_db; ``` In this setup, `admin_user` can: -- Perform authentication/authorization operations when connected to the "memgraph" database -- Execute replication and multi-database queries when connected to the "memgraph" database +- Perform authentication/authorization operations when connected to the + "memgraph" database +- Execute replication and multi-database queries when connected to the + "memgraph" database - Manage tenant1_db data when connected to tenant1_db - Manage tenant2_db data when connected to tenant2_db @@ -79,7 +103,8 @@ In this setup, `admin_user` can: ### Basic database access -In Memgraph Enterprise, both users and roles can have database access permissions: +In Memgraph Enterprise, both users and roles can have database access +permissions: ```cypher -- Grant database access to a role @@ -95,15 +120,18 @@ REVOKE DATABASE db_name TO user_or_role; ### How database access works Database access follows these rules: -- **Grants**: If any role or user grants access to a database, database is granted -- **Denies**: If any role or user denies access to a database, database is denied +- **Grants**: If any role or user grants access to a database, database is + granted +- **Denies**: If any role or user denies access to a database, database is + denied - **Access**: User or role has database access if it is granted and not denied ## Database access with multiple roles ### Combining database access -When a user has multiple roles, their database access is combined from all roles: +When a user has multiple roles, their database access is combined from all +roles: ```cypher -- Create roles with different database access @@ -140,20 +168,26 @@ SET ROLE FOR user TO role1, role2; ## Privileges with multiple roles -When a user has multiple roles, their privileges are combined according to the following rules: +When a user has multiple roles, their privileges are combined according to the +following rules: -- **Grant**: If any assigned role with access to the database grants a privilege, the user is granted that privilege. -- **Deny**: If any assigned role with access to the database denies a privilege, the user is denied that privilege—even if another role grants it. -- **Effective privilege**: The user's effective privileges are the union of all granted privileges, minus any that are denied by any role. +- **Grant**: If any assigned role with access to the database grants a + privilege, the user is granted that privilege. +- **Deny**: If any assigned role with access to the database denies a privilege, + the user is denied that privilege—even if another role grants it. +- **Effective privilege**: The user's effective privileges are the union of all + granted privileges, minus any that are denied by any role. -This means that **deny always takes precedence over grant** when there is a conflict. -**Note:** The resulting user privileges contain user's privileges only if the user also has access to the database. +This means that **deny always takes precedence over grant** when there is a +conflict. **Note:** The resulting user privileges contain user's privileges only +if the user also has access to the database. ## Creating database-specific roles ### Using database access for tenant isolation -You can create roles that are specific to certain databases by controlling their database access: +You can create roles that are specific to certain databases by controlling their +database access: ```cypher -- Create tenant-specific roles @@ -185,7 +219,8 @@ While this approach works, it has some limitations: ### Setting roles ON a database -Memgraph Enterprise provides a better API for database-specific role assignment using the `ON database` clause: +Memgraph Enterprise provides a better API for database-specific role assignment +using the `ON database` clause: ```cypher -- Assign role to specific database @@ -198,7 +233,8 @@ CLEAR ROLE FOR user_name ON database_name; CLEAR ROLES; ``` -**Note:** Multiple roles can be specified on a database. However, the list of roles needs to be exhaustive. +**Note:** Multiple roles can be specified on a database. However, the list of +roles needs to be exhaustive. ### How it works @@ -229,10 +265,14 @@ SET ROLE FOR alice TO tenant2_user ON tenant2_db; When using `SET ROLE ... ON database`, the system applies special logic: -1. **Database Access Check**: Only roles with access to the specified database can be assigned -2. **Permission Filtering**: When accessing a database, only roles assigned to that database are considered -3. **Isolation**: Users cannot access permissions from roles assigned to other databases -4. **Automatic Filtering**: The system automatically filters permissions based on the current database context +1. **Database Access Check**: Only roles with access to the specified database + can be assigned +2. **Permission Filtering**: When accessing a database, only roles assigned to + that database are considered +3. **Isolation**: Users cannot access permissions from roles assigned to other + databases +4. **Automatic Filtering**: The system automatically filters permissions based + on the current database context ## Multi-tenant role management @@ -256,7 +296,9 @@ CLEAR ROLE FOR user_name ON database_name; ### Viewing multi-tenant roles -**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. +**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. ```cypher -- Show all roles for a user (works in all environments) @@ -287,7 +329,8 @@ SHOW ROLES FOR user_name ON CURRENT; SHOW ROLES FOR user_name ON DATABASE database_name; ``` -These commands return the aggregated roles for the user in the specified database context. +These commands return the aggregated roles for the user in the specified +database context. ### Viewing permissions for a specific database @@ -314,11 +357,13 @@ SHOW PRIVILEGES FOR user_name ON CURRENT; SHOW PRIVILEGES FOR user_name ON DATABASE database_name; ``` -These commands return the aggregated privileges for the user in the specified database context. +These commands return the aggregated privileges for the user in the specified +database context. ### SSO integration with multi-tenant roles -When using external auth modules, users can be assigned multi-tenant roles based on their identity provider roles: +When using external auth modules, users can be assigned multi-tenant roles based +on their identity provider roles: ```python def authenticate(username, password): @@ -338,7 +383,8 @@ def authenticate(username, password): ### Main database selection -When a user has multi-tenant roles with access to different databases, the system determines the main database: +When a user has multi-tenant roles with access to different databases, the +system determines the main database: ```cypher -- Create roles with different main databases @@ -356,14 +402,18 @@ SET ROLE role2 FOR user1 ON db2; ``` - -In case of an SSO connection, no user information is stored in Memgraph; instead the auth module returns roles associated with the connection. -In this case, there are no guarantees which role's main database will be selected. Use "database" in the session arguments to define the target database. + + In case of an SSO connection, no user information is stored in Memgraph; + instead the auth module returns roles associated with the connection. In + this case, there are no guarantees which role's main database will be + selected. Use "database" in the session arguments to define the target + database. ### Database-specific permission filtering -The special logic ensures that when accessing a specific database, only roles assigned to that database are considered: +The special logic ensures that when accessing a specific database, only roles +assigned to that database are considered: ```cypher -- Role with access to multiple databases @@ -384,18 +434,40 @@ SET ROLE multi_db_role FOR user1 ON db2; ## Best practices for multi-tenant environments -1. **Use descriptive role names**: Include tenant information in role names (e.g., `tenant1_admin`, `tenant2_user`) -2. **Follow principle of least privilege**: Grant only necessary permissions to each role -3. **Separate tenant-specific roles**: Create distinct roles for each tenant to ensure proper isolation -4. **Test permission combinations**: Verify that multi-tenant permissions work correctly in each database -5. **Document role assignments**: Keep track of which users have which roles for which databases -6. **Use deny sparingly**: Remember that deny takes precedence over grant across all databases -7. **Treat memgraph database as admin database**: In multi-tenant environments, restrict access to the default "memgraph" database to privileged users only -8. **Ensure AUTH privilege access**: Users who need to perform authentication/authorization operations must have both the `AUTH` privilege and access to the "memgraph" database -9. **Ensure replication privilege access**: Users who need to perform replication operations must have both the `REPLICATION` privilege and access to the "memgraph" database -10. **Ensure multi-database privilege access**: Users who need to perform multi-database operations must have the appropriate privileges (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) and access to the "memgraph" database -11. **Separate application data**: Store all application data in tenant-specific databases, not in the default "memgraph" database -12. **Plan for administrative operations**: Design your role structure to ensure that users who need to manage users, roles, replication, or multi-database operations have appropriate access to the "memgraph" database -13. **Use explicit database context**: Always specify the database context when using `SHOW ROLE` and `SHOW PRIVILEGES` commands in multi-tenant environments -14. **Choose appropriate context**: Use `ON MAIN` for the user's main database, `ON CURRENT` for the currently active database, or `ON DATABASE` for a specific database -15. **Verify permissions in context**: Always check roles and privileges in the specific database context where they will be used +1. **Use descriptive role names**: Include tenant information in role names + (e.g., `tenant1_admin`, `tenant2_user`) +2. **Follow principle of least privilege**: Grant only necessary permissions to + each role +3. **Separate tenant-specific roles**: Create distinct roles for each tenant to + ensure proper isolation +4. **Test permission combinations**: Verify that multi-tenant permissions work + correctly in each database +5. **Document role assignments**: Keep track of which users have which roles for + which databases +6. **Use deny sparingly**: Remember that deny takes precedence over grant across + all databases +7. **Treat memgraph database as admin database**: In multi-tenant environments, + restrict access to the default "memgraph" database to privileged users only +8. **Ensure AUTH privilege access**: Users who need to perform + authentication/authorization operations must have both the `AUTH` privilege + and access to the "memgraph" database +9. **Ensure replication privilege access**: Users who need to perform + replication operations must have both the `REPLICATION` privilege and access + to the "memgraph" database +10. **Ensure multi-database privilege access**: Users who need to perform + multi-database operations must have the appropriate privileges + (`MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) and access to the "memgraph" + database +11. **Separate application data**: Store all application data in tenant-specific + databases, not in the default "memgraph" database +12. **Plan for administrative operations**: Design your role structure to ensure + that users who need to manage users, roles, replication, or multi-database + operations have appropriate access to the "memgraph" database +13. **Use explicit database context**: Always specify the database context when + using `SHOW ROLE` and `SHOW PRIVILEGES` commands in multi-tenant + environments +14. **Choose appropriate context**: Use `ON MAIN` for the user's main database, + `ON CURRENT` for the currently active database, or `ON DATABASE` for a + specific database +15. **Verify permissions in context**: Always check roles and privileges in the + specific database context where they will be used From 7681b3beb84106732d7078f449867eefc8a90191 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 17:51:27 +0200 Subject: [PATCH 12/17] cleanup --- pages/clustering/replication.mdx | 5 +--- .../authentication-and-authorization.mdx | 25 ++++++++----------- 2 files changed, 12 insertions(+), 18 deletions(-) diff --git a/pages/clustering/replication.mdx b/pages/clustering/replication.mdx index 00018b55c..d70de2326 100644 --- a/pages/clustering/replication.mdx +++ b/pages/clustering/replication.mdx @@ -165,7 +165,7 @@ The recommendation is to use the default "memgraph" database as an admin/system To execute replication queries, users must have: 1. The `REPLICATION` privilege -2. Access to the default "memgraph" database +2. **AND**ccess to the default "memgraph" database ### Impact on multi-tenant environments @@ -189,9 +189,6 @@ In this setup, `repl_admin` can: - Access the "memgraph" database for administrative operations - Manage the replication cluster configuration -### Best practice - -For replication management, ensure that users who need to perform replication operations have both the `REPLICATION` privilege and access to the "memgraph" database. This aligns with the overall recommendation to treat the "memgraph" database as an administrative database in multi-tenant environments. ## Running multiple instances diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 26d725f47..93d128e07 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -15,7 +15,7 @@ As of Memgraph v3.5 there are new requirements for authentication and authorizat ### AUTH privilege requirement -Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be explicitly granted this privilege to perform user and role management operations. +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. @@ -23,17 +23,14 @@ The recommendation is to use the default "memgraph" database as an admin/system -### Default database access requirement - -In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. - -### System queries and multi-database queries +### System queries in multi-tenant/multi-database 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 query syntax changes + +## Multi-tenant/multi-database environment query syntax changes ### SHOW ROLE syntax in multi-tenant environments @@ -64,13 +61,6 @@ SHOW ROLE FOR user_name ON DATABASE database_name; ### SHOW PRIVILEGES syntax in multi-tenant environments -**SHOW PRIVILEGES FOR ROLE**: This command does not require database specification and will show all privileges for the role. - -```cypher --- Show all privileges for a role (works in all environments) -SHOW PRIVILEGES FOR role_name; -``` - **SHOW PRIVILEGES FOR USER**: In multi-tenant environments, you must specify the database context: 1. **Show privileges for the user's main database:** @@ -90,6 +80,13 @@ 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. + +```cypher +-- Show all privileges for a role (works in all environments) +SHOW PRIVILEGES FOR role_name; +``` + ### Multi-tenant recommendations For multi-tenant environments, we recommend: From 2903d8725107c3e7c58ba6a284387cd0397b8f98 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 18:13:32 +0200 Subject: [PATCH 13/17] cleanup --- .../auth-system-integrations.mdx | 4 +- .../role-based-access-control.mdx | 39 ++---- pages/help-center/errors/auth.mdx | 125 +----------------- 3 files changed, 21 insertions(+), 147 deletions(-) diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index 832a5eb5d..9125aa75e 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -27,7 +27,7 @@ privileges will still apply but you won't be able to manage them. ### Roles User roles must be defined in Memgraph before using auth modules because these -modules return the role(s) associated with the user. Memgraph now supports multiple roles per user, allowing auth modules to return either a single role or multiple roles. +modules return the role(s) associated with the user. As of v3.5 Memgraph supports multiple roles per user, allowing auth modules to return either a single role or multiple roles. ### Flags @@ -98,7 +98,7 @@ in Memgraph's output (typically in `systemd` logs using `journalctl`). ### Multiple roles support -Memgraph now supports multiple roles per user in auth module responses. Auth modules can return either a single role (backward compatible) or multiple roles (new format). +As of v3.5 Memgraph supports multiple roles per user in auth module responses. Auth modules can return either a single role (backward compatible) or multiple roles (new format). #### Single role response (backward compatible) diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 97750fc60..8e67a2cdf 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -150,26 +150,12 @@ The recommendation is to use the default "memgraph" database as an admin/system -### AUTH privilege requirement +### System queries in multi-tenant/multi-database environments -Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be explicitly granted this privilege to perform user and role management operations. - -### Default database access requirement - -In addition to the `AUTH` privilege, users must also have access to the default "memgraph" database to execute authentication and authorization queries. This requirement applies even when the user is working in other databases within a multi-tenant environment. - -### Replication and multi-database queries - -Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and require access to it. - -To execute these queries, users must have: -- The appropriate privileges (`REPLICATION`, `MULTI_DATABASE_USE`, `MULTI_DATABASE_EDIT`) +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 - -**Multi-tenant environments**: These requirements are only a concern in multi-tenant environments where users have access to databases other than the default "memgraph" database. In single-database deployments, these requirements are automatically satisfied. - - ### 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: @@ -320,7 +306,7 @@ To check privilege for a certain user or role, run the following query: SHOW PRIVILEGES FOR user_or_role; ``` -In multi-tenant environments, you must specify which database context to use when showing privileges. There are three options: +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:** ```cypher @@ -339,6 +325,11 @@ 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 @@ -440,13 +431,7 @@ To check which privileges an existing user or role has in Memgraph, it is enough SHOW PRIVILEGES FOR user_or_role; ``` -**Note**: -- For **roles**: This command does not require database specification, even in multi-tenant environments. It will show all privileges for the role. -- For **users**: In multi-tenant environments, you must specify the database context. - -and all the values of clause privileges, as well as label-based permissions will be displayed. - -In multi-tenant environments, you must specify which database context to use when showing privileges for users. There are three options: +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:** ```cypher @@ -465,6 +450,10 @@ 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): diff --git a/pages/help-center/errors/auth.mdx b/pages/help-center/errors/auth.mdx index 1ec7da225..106c38f0c 100644 --- a/pages/help-center/errors/auth.mdx +++ b/pages/help-center/errors/auth.mdx @@ -19,7 +19,8 @@ import {CommunityLinks} from '/components/social-card/CommunityLinks' details, visit: memgr.ph/auth.](#error-2) 6. [Couldn't authenticate user '{}'. For more details, visit: memgr.ph/auth.](#error-1) -7. ["No user nor role '{}' found."](#error-1) +7. [You are not authorized to execute this query on database "memgraph"!](#error-3) +8. [In a multi-tenant environment, SHOW PRIVILEGES query requires database specification. Use ON MAIN, ON CURRENT or ON DATABASE db_name.](#error-4) ## Couldn't authenticate user [#error-1] @@ -28,32 +29,12 @@ A user authentication can fail for many reasons. The user could be missing, the wrong password might be entered, the role defined by the auth module might be missing. -## Operation not permitted when using auth module [#error-4] +## Operation not permitted when using auth module [#error-2] Queries that modify a user's authentication data are forbidden while using an auth module. Users are handled by the module and local users are disabled. -## User doesn't have AUTH privilege - -This error occurs when a user attempts to execute authentication or authorization queries (such as `CREATE USER`, `CREATE ROLE`, `GRANT`, `DENY`, `REVOKE`, etc.) without the required `AUTH` privilege. - -{

Solution

} - -Grant the `AUTH` privilege to the user or their role: - -```cypher --- Grant AUTH privilege to a user -GRANT AUTH TO username; - --- Grant AUTH privilege to a role -GRANT AUTH TO role_name; -``` - -{

Multi-tenant environments

} - -In multi-tenant environments, users must also have access to the default "memgraph" database to execute authentication and authorization queries. See the [authentication requirements documentation](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements) for more details. - -## User doesn't have access to the memgraph database [#error-4] +## User doesn't have access to the memgraph database [#error-3] This error occurs in multi-tenant environments when a user attempts to execute authentication or authorization queries but doesn't have access to the default "memgraph" database. @@ -73,42 +54,7 @@ GRANT DATABASE memgraph TO role_name; In multi-tenant environments, we recommend treating the "memgraph" database as an administrative/system database and restricting access to privileged users only. See the [multi-tenancy documentation](/database-management/multi-tenancy#default-database-best-practices) for recommended setup patterns. -## Database context must be specified for SHOW ROLE in multi-tenant environment - -This error occurs when attempting to use `SHOW ROLE` or `SHOW ROLES` in a multi-tenant environment without specifying the database context. - -**Note**: This error should no longer occur for `SHOW ROLE FOR USER` commands, as they no longer require database specification. The `SHOW ROLE FOR USER` command will show all roles assigned to the user across all databases. - -{

Solution

} - -For `SHOW ROLE FOR USER` commands, you can use them without database specification: - -```cypher --- 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: - -```cypher --- 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; -``` - -{

When this occurs

} - -This error typically occurs when: -- The system detects multiple databases and requires explicit context specification -- The user is connected to a multi-tenant Memgraph instance - -## Database context must be specified for SHOW PRIVILEGES in multi-tenant environment [#error-9] +## Database context must be specified for SHOW PRIVILEGES in multi-tenant environment [#error-4] This error occurs when attempting to use `SHOW PRIVILEGES` in a multi-tenant environment without specifying the database context. @@ -148,65 +94,4 @@ This error typically occurs when: - For roles: Use `SHOW PRIVILEGES FOR role_name` without database specification - For users: Always specify the database context when working in multi-tenant environments to ensure you're viewing the correct privileges for the intended database -## User doesn't have REPLICATION privilege - -This error occurs when a user attempts to execute replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) without the required `REPLICATION` privilege. - -{

Solution

} - -Grant the `REPLICATION` privilege to the user or their role: - -```cypher --- Grant REPLICATION privilege to a user -GRANT REPLICATION TO username; - --- Grant REPLICATION privilege to a role -GRANT REPLICATION TO role_name; -``` - -{

Multi-tenant environments

} - -In multi-tenant environments, users must also have access to the default "memgraph" database to execute replication queries. See the [replication documentation](/clustering/replication#replication-queries-and-the-memgraph-database) for more details. - -## User doesn't have MULTI_DATABASE_USE privilege [#error-6] - -This error occurs when a user attempts to execute multi-database queries (such as `SHOW DATABASES`, `USE DATABASE`) without the required `MULTI_DATABASE_USE` privilege. - -{

Solution

} - -Grant the `MULTI_DATABASE_USE` privilege to the user or their role: - -```cypher --- Grant MULTI_DATABASE_USE privilege to a user -GRANT MULTI_DATABASE_USE TO username; - --- Grant MULTI_DATABASE_USE privilege to a role -GRANT MULTI_DATABASE_USE TO role_name; -``` - -{

Multi-tenant environments

} - -In multi-tenant environments, users must also have access to the default "memgraph" database to execute multi-database queries. See the [multi-tenancy documentation](/database-management/multi-tenancy#multi-database-queries-and-the-memgraph-database) for more details. - -## User doesn't have MULTI_DATABASE_EDIT privilege [#error-7] - -This error occurs when a user attempts to execute multi-database management queries (such as `CREATE DATABASE`, `DROP DATABASE`) without the required `MULTI_DATABASE_EDIT` privilege. - -{

Solution

} - -Grant the `MULTI_DATABASE_EDIT` privilege to the user or their role: - -```cypher --- Grant MULTI_DATABASE_EDIT privilege to a user -GRANT MULTI_DATABASE_EDIT TO username; - --- Grant MULTI_DATABASE_EDIT privilege to a role -GRANT MULTI_DATABASE_EDIT TO role_name; -``` - -{

Multi-tenant environments

} - -In multi-tenant environments, users must also have access to the default "memgraph" database to execute multi-database management queries. See the [multi-tenancy documentation](/database-management/multi-tenancy#multi-database-queries-and-the-memgraph-database) for more details. - - \ No newline at end of file From 01ba3ac871888f46a8d5949434869968054aed5c Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 18:28:04 +0200 Subject: [PATCH 14/17] cleanup multi-role --- .../authentication-and-authorization.mdx | 6 +- .../multiple-roles.mdx | 129 +++--------------- .../role-based-access-control.mdx | 2 +- 3 files changed, 23 insertions(+), 114 deletions(-) diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 93d128e07..94a50b905 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -23,14 +23,14 @@ The recommendation is to use the default "memgraph" database as an admin/system -### System queries in multi-tenant/multi-database environment +### 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/multi-database environment query syntax changes +## multi-tenant environment query syntax changes ### SHOW ROLE syntax in multi-tenant environments @@ -87,7 +87,7 @@ These commands return the aggregated roles and privileges for the user in the sp SHOW PRIVILEGES FOR role_name; ``` -### Multi-tenant recommendations +### multi-tenant recommendations For multi-tenant environments, we recommend: - Treating the default "memgraph" database as an administrative/system database diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index 8610698f3..ea9b39562 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -1,105 +1,34 @@ --- -title: Multiple roles per user and multi-tenant roles -description: Learn how to assign database-specific roles to users in multi-tenant environments with special permission filtering logic. +title: Multi-role users and multi-tenant roles +description: Learn how users can have multiple roles and how to assign database-specific roles in multi-tenant environments with special permission filtering logic. --- import { Callout } from 'nextra/components' -# Multi-tenant roles (Enterprise) +# Multi-role users and multi-tenant roles (Enterprise) +As of v3.5 Memgraph allows users to have multiple roles assigned to them +simultaneously. Memgraph Enterprise supports multi-tenant roles, which allow users to have different roles assigned to them for specific databases. This feature enables proper tenant isolation and fine-grained access control in multi-tenant environments. -## Overview - -Multi-tenant roles are a specialized form of multiple roles that include special -logic for database-specific permission filtering. When a user has multi-tenant -roles, their permissions are dynamically filtered based on which database -they're accessing, ensuring proper tenant isolation. - -Key benefits: -- **Tenant Isolation**: Users can have different permissions for different - databases -- **SSO Integration**: Support for external identity providers that return - multiple roles - - -## Authentication and authorization requirements - -Recent changes to Memgraph have introduced new requirements for authentication -and authorization operations in multi-tenant environments. These changes affect -how users can perform user and role management operations. - - -### AUTH privilege requirement - -Authentication and authorization queries (such as `CREATE USER`, `CREATE ROLE`, -`GRANT`, `DENY`, `REVOKE`, etc.) now require the `AUTH` privilege. Users must be -explicitly granted this privilege to perform user and role management -operations. - -### Default database access requirement - -In addition to the `AUTH` privilege, users must also have access to the default -"memgraph" database to execute authentication and authorization queries. This -requirement applies even when the user is working in other databases within a -multi-tenant environment. - -### Replication and multi-database queries - -Replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP -REPLICA`, etc.) and multi-database queries (such as `SHOW DATABASES`, `CREATE -DATABASE`, `DROP DATABASE`, etc.) also now target the "memgraph" database and -require access to it. - - **Multi-tenant environments**: These requirements are -only a concern in multi-tenant environments where users have access to databases -other than the default "memgraph" database. In single-database deployments, -these requirements are automatically satisfied. - -### Impact on multi-tenant role management - -When using multi-tenant roles, ensure that users who need to perform -authentication, authorization, replication, or multi-database operations have: -1. The appropriate privileges (`AUTH`, `REPLICATION`, `MULTI_DATABASE_USE`, - `MULTI_DATABASE_EDIT`) -2. Access to the default "memgraph" database -3. Appropriate role assignments for the "memgraph" database +## Privileges with multiple roles -{

Example: Admin user with multi-tenant roles

} +When a user has multiple roles, their privileges are combined according to the +following rules: -```cypher - -- Create admin role with full privileges - CREATE ROLE system_admin; - GRANT ALL PRIVILEGES TO system_admin; - GRANT DATABASE memgraph TO system_admin; - - -- Create tenant-specific admin roles - CREATE ROLE tenant1_admin; - CREATE ROLE tenant2_admin; - GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant1_admin; - GRANT MATCH, CREATE, MERGE, SET, DELETE, INDEX TO tenant2_admin; - GRANT DATABASE tenant1_db TO tenant1_admin; - GRANT DATABASE tenant2_db TO tenant2_admin; - - -- Create admin user - CREATE USER admin_user IDENTIFIED BY 'admin_password'; - - -- Assign roles with database-specific assignments - SET ROLE FOR admin_user TO system_admin ON memgraph; - SET ROLE FOR admin_user TO tenant1_admin ON tenant1_db; - SET ROLE FOR admin_user TO tenant2_admin ON tenant2_db; -``` +- **Grant**: If any assigned role with access to the database grants a + privilege, the user is granted that privilege. +- **Deny**: If any assigned role with access to the database denies a privilege, + the user is denied that privilege—even if another role grants it. +- **Effective privilege**: The user's effective privileges are the union of all + granted privileges, minus any that are denied by any role. -In this setup, `admin_user` can: -- Perform authentication/authorization operations when connected to the - "memgraph" database -- Execute replication and multi-database queries when connected to the - "memgraph" database -- Manage tenant1_db data when connected to tenant1_db -- Manage tenant2_db data when connected to tenant2_db +This means that **deny always takes precedence over grant** when there is a +conflict. **Note:** The resulting user privileges contain user's privileges only +if the user also has access to the database. ## Database access with users and roles @@ -128,7 +57,6 @@ Database access follows these rules: denied - **Access**: User or role has database access if it is granted and not denied -## Database access with multiple roles ### Combining database access @@ -168,22 +96,6 @@ SET ROLE FOR user TO role1, role2; -- Result: User is denied access to db1 (deny takes precedence) ``` -## Privileges with multiple roles - -When a user has multiple roles, their privileges are combined according to the -following rules: - -- **Grant**: If any assigned role with access to the database grants a - privilege, the user is granted that privilege. -- **Deny**: If any assigned role with access to the database denies a privilege, - the user is denied that privilege—even if another role grants it. -- **Effective privilege**: The user's effective privileges are the union of all - granted privileges, minus any that are denied by any role. - -This means that **deny always takes precedence over grant** when there is a -conflict. **Note:** The resulting user privileges contain user's privileges only -if the user also has access to the database. - ## Creating database-specific roles ### Using database access for tenant isolation @@ -465,11 +377,8 @@ SET ROLE multi_db_role FOR user1 ON db2; 12. **Plan for administrative operations**: Design your role structure to ensure that users who need to manage users, roles, replication, or multi-database operations have appropriate access to the "memgraph" database -13. **Use explicit database context**: Always specify the database context when - using `SHOW ROLE` and `SHOW PRIVILEGES` commands in multi-tenant - environments -14. **Choose appropriate context**: Use `ON MAIN` for the user's main database, +13. **Use explicit database context**: Use `ON MAIN` for the user's main database, `ON CURRENT` for the currently active database, or `ON DATABASE` for a specific database -15. **Verify permissions in context**: Always check roles and privileges in the +14. **Verify permissions in context**: Always check roles and privileges in the specific database context where they will be used diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 8e67a2cdf..72d09dcff 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -150,7 +150,7 @@ The recommendation is to use the default "memgraph" database as an admin/system -### System queries in multi-tenant/multi-database environments +### 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`) From b5fb1ad44e1350456e7c72a4e2a4d87ad0cb709e Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 18:37:03 +0200 Subject: [PATCH 15/17] cleanup --- .../authentication-and-authorization.mdx | 6 +++--- .../auth-system-integrations.mdx | 2 +- .../role-based-access-control.mdx | 8 +++++++- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 94a50b905..6eaf9d915 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -30,7 +30,7 @@ To execute system (auth, replication and multi-database) queries, users must hav - **AND** access to the default "memgraph" database -## multi-tenant environment query syntax changes +## Multi-tenant environment query syntax changes ### SHOW ROLE syntax in multi-tenant environments @@ -87,7 +87,7 @@ These commands return the aggregated roles and privileges for the user in the sp SHOW PRIVILEGES FOR role_name; ``` -### multi-tenant recommendations +### Multi-tenant recommendations For multi-tenant environments, we recommend: - Treating the default "memgraph" database as an administrative/system database @@ -105,7 +105,7 @@ Learn how to manage users in Memgraph. Learn how to manage roles, set up their privileges and fine-grained access control. -## [Multiple roles per user and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) (Enterprise) +## [Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) (Enterprise) Learn how to assign multiple roles to users simultaneously and understand how permissions are combined from all roles. diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index 9125aa75e..b84a79801 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -210,7 +210,7 @@ by a semicolon `;`. Each mapping is structured as follows: One identity service role can be mapped to one or more Memgraph roles. When a user logs in and is assigned an identity service role that is mapped to an array of Memgraph roles, the user is assigned all of the mapped Memgraph roles. -For more information regarding how multi-role users are handled by Mmegraph, please visit [Multiple roles per user and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles). +For more information regarding how multi-role users are handled by Memgraph, please visit [Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles). For example, the `entra.admin:memadmin; entra.user:memuser` mapping defines that the identity service roles `entra.admin` and `entra.user` respectively map diff --git a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx index 72d09dcff..2970a1816 100644 --- a/pages/database-management/authentication-and-authorization/role-based-access-control.mdx +++ b/pages/database-management/authentication-and-authorization/role-based-access-control.mdx @@ -21,7 +21,7 @@ data, Memgraph Enterprise offers [fine-grained access control](#fine-grained-access-control). -[Multiple roles per user and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) for more information regarding assigning multiple roles to users or assigning roles for a specific database. +[Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) for more information regarding assigning multiple roles to users or assigning roles for a specific database. ## User roles @@ -81,6 +81,12 @@ 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: + +```cypher +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:** From eaf6a4ed862e46ebf051dfff5f7420a0c0836565 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 21 Aug 2025 18:39:16 +0200 Subject: [PATCH 16/17] enterprise page --- .../enabling-memgraph-enterprise.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/pages/database-management/enabling-memgraph-enterprise.mdx b/pages/database-management/enabling-memgraph-enterprise.mdx index 438a9776b..c28c37d83 100644 --- a/pages/database-management/enabling-memgraph-enterprise.mdx +++ b/pages/database-management/enabling-memgraph-enterprise.mdx @@ -9,7 +9,7 @@ The following Memgraph features are only available in Enterprise Edition: | **Category** | **Features** | |---------------|-------------| -| **Security** | [Role-based access control (RBAC)](#role-based-access-control)
[Label-based access control (LBAC)](#role-based-access-control)
[Auth system integrations](#authentication-system-integrations) (LDAP, SAML, OIDC)
[Impersonate user](#impersonate-user)
[Hiding sensitive information](#hiding-sensitive-information) | +| **Security** | [Role-based access control (RBAC)](#role-based-access-control)
[Label-based access control (LBAC)](#role-based-access-control)
[Multi-role users and multi-tenant roles](#multi-role-users-and-multi-tenant-roles)
[Auth system integrations](#authentication-system-integrations) (LDAP, SAML, OIDC)
[Impersonate user](#impersonate-user)
[Hiding sensitive information](#hiding-sensitive-information) | | **Logging & monitoring** | [Audit log](#audit-log)
[Metrics tracking via HTTP server](#metrics-tracking-via-http-server) (Prometheus integration) | | **Database management** | [High availability](#high-availability) with automatic failover
[Multi-tenancy](#multi-tenancy)
[CRON snapshot scheduling](#cron-snapshot-scheduling) | | **Querying** | [Dynamic graph algorithms](#dynamic-graph-algorithms)
[Time-to-live (TTL)](#time-to-live-ttl) for data expiration | @@ -99,6 +99,19 @@ 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. +### Multi-role users and multi-tenant roles + +[Multi-role users and multi-tenant roles](/database-management/authentication-and-authorization/multiple-roles) enable advanced user management and tenant isolation in Memgraph Enterprise. This feature allows users to have multiple roles assigned simultaneously, with permissions combined from all roles according to specific rules. + +**Key capabilities:** +- **Multiple roles per user**: Users can have multiple roles with combined permissions +- **Database-specific role assignment**: Roles can be assigned to specific databases using `SET ROLE ... ON database` syntax +- **Tenant isolation**: Users can have different roles for different databases, ensuring proper data isolation +- **SSO integration**: Support for external identity providers that return multiple roles +- **Permission filtering**: Automatic filtering of permissions based on the current database context + +This feature is particularly valuable for multi-tenant environments where organizations need to manage users with different access levels across multiple isolated databases while maintaining strict security boundaries. + ### Authentication system integrations Memgraph supports authentication and authorization using external auth modules. From a07070b377634dc8caa7b60f200ed15ebad65742 Mon Sep 17 00:00:00 2001 From: matea16 Date: Fri, 22 Aug 2025 14:29:53 +0200 Subject: [PATCH 17/17] apply review changes --- next-env.d.ts | 1 + pages/clustering/replication.mdx | 159 ++++++++++-------- .../authentication-and-authorization.mdx | 49 ++++-- .../auth-system-integrations.mdx | 16 +- .../multiple-roles.mdx | 16 +- 5 files changed, 144 insertions(+), 97 deletions(-) diff --git a/next-env.d.ts b/next-env.d.ts index 52e831b43..254b73c16 100644 --- a/next-env.d.ts +++ b/next-env.d.ts @@ -1,5 +1,6 @@ /// /// +/// // NOTE: This file should not be edited // see https://nextjs.org/docs/pages/api-reference/config/typescript for more information. diff --git a/pages/clustering/replication.mdx b/pages/clustering/replication.mdx index d70de2326..04332be02 100644 --- a/pages/clustering/replication.mdx +++ b/pages/clustering/replication.mdx @@ -10,15 +10,16 @@ import { Callout } from 'nextra/components' Instances need to remember their role and configuration details in a replication -cluster upon restart, and the `--replication-restore-state-on-startup` needs to be -set to `true` when first initializing the instances and remain `true` throughout -the instances' lifetime for replication to work correctly. If the flag is set to `false`, -MAIN can't communicate with instance, because each REPLICA has a UUID of MAIN which can communicate -with it, and it is set up only on instance registration. In case the flag is set to `false`, -the way to go forward is first to unregister the instance on MAIN and register it again. +cluster upon restart, and the `--replication-restore-state-on-startup` needs to +be set to `true` when first initializing the instances and remain `true` +throughout the instances' lifetime for replication to work correctly. If the +flag is set to `false`, MAIN can't communicate with instance, because each +REPLICA has a UUID of MAIN which can communicate with it, and it is set up only +on instance registration. In case the flag is set to `false`, the way to go +forward is first to unregister the instance on MAIN and register it again. -When reinstating a cluster, it is advised first to initialize the MAIN -instance, then the REPLICA instances. +When reinstating a cluster, it is advised first to initialize the MAIN instance, +then the REPLICA instances. Data replication currently **works only in the in-memory transactional [storage mode](/fundamentals/storage-memory-usage)**. @@ -26,14 +27,15 @@ mode](/fundamentals/storage-memory-usage)**. When distributing data across several instances, Memgraph uses replication to -provide a satisfying ratio of the following properties, known from the CAP theorem: +provide a satisfying ratio of the following properties, known from the CAP +theorem: -1. **Consistency** (C) - every node has the same view of data at a given point in - time -2. **Availability** (A) - all clients can find a replica of the data, even in the - case of a partial node failure -3. **Partition tolerance** (P) - the system continues to work as expected despite a - partial network failure +1. **Consistency** (C) - every node has the same view of data at a given point + in time +2. **Availability** (A) - all clients can find a replica of the data, even in + the case of a partial node failure +3. **Partition tolerance** (P) - the system continues to work as expected + despite a partial network failure In the replication process, the data is replicated from one storage (MAIN instance) to another (REPLICA instances). @@ -71,43 +73,44 @@ cluster. Once demoted to REPLICA instances, they will no longer accept write queries. In order to start the replication, each REPLICA instance needs to be registered -from the MAIN instance by setting a replication mode (SYNC, ASYNC or STRICT_SYNC) and -specifying the REPLICA instance's socket address. +from the MAIN instance by setting a replication mode (SYNC, ASYNC or +STRICT_SYNC) and specifying the REPLICA instance's socket address. The replication mode defines the terms by which the MAIN instance can commit the changes to the database, thus modifying the system to prioritize either consistency or availability: -- **STRICT_SYNC** - After committing a transaction, the MAIN instance will communicate -the changes to all REPLICA instances and wait until it -receives a response or information that a timeout is reached. The STRICT_SYNC mode ensures +- **STRICT_SYNC** - After committing a transaction, the MAIN instance will +communicate the changes to all REPLICA instances and wait until it receives a +response or information that a timeout is reached. The STRICT_SYNC mode ensures consistency and partition tolerance (CP), but not availability for writes. If the primary database has multiple replicas, the system is highly available for reads. But, when a replica fails, the MAIN instance can't process the write due -to the nature of synchronous replication. It is implemented as two-phase commit protocol. +to the nature of synchronous replication. It is implemented as two-phase commit +protocol. - **SYNC** - After committing a transaction, the MAIN instance will communicate -the changes to all REPLICA instances and wait until it -receives a response or information that a timeout is reached. It is different from -**STRICT_SYNC** mode because it the MAIN can continue committing even in situations -when **SYNC** replica is down. +the changes to all REPLICA instances and wait until it receives a response or +information that a timeout is reached. It is different from **STRICT_SYNC** mode +because it the MAIN can continue committing even in situations when **SYNC** +replica is down. - **ASYNC** - The MAIN instance will commit a transaction without receiving confirmation from REPLICA instances that they have received the same - transaction. ASYNC mode ensures system availability and partition tolerance (AP), - while data can only be eventually consistent. + transaction. ASYNC mode ensures system availability and partition tolerance + (AP), while data can only be eventually consistent. -Users are advised to use the same value for configuration -flag `--storage-wal-file-flush-every-n-txn` on MAIN and SYNC REPLICAs. Otherwise, -the situation could occur in which there is a data which is fsynced on REPLICA and not on MAIN. -In the case MAIN crashes, this could leave to conflicts in system that would need to be -manually resolved by users. +Users are advised to use the same value for configuration flag +`--storage-wal-file-flush-every-n-txn` on MAIN and SYNC REPLICAs. Otherwise, the +situation could occur in which there is a data which is fsynced on REPLICA and +not on MAIN. In the case MAIN crashes, this could leave to conflicts in system +that would need to be manually resolved by users. @@ -127,37 +130,44 @@ If the REPLICA is so far behind the MAIN instance that the synchronization using WAL files and deltas within it is impossible, Memgraph will use snapshots to synchronize the REPLICA to the state of the MAIN instance. -From Memgraph version 2.15, a REPLICA instance has integrated support to only listen to one MAIN. -This part is introduced to support the high availability but also reflects on the replication. -The mechanism that is used is a unique identifier that which MAIN instance sends to all REPLICAs -when REPLICA is first registered on a MAIN. A REPLICA stores the UUID of the MAIN instance it listens to. -The MAIN's UUID is also stored on a disk, in case of restart of an instance to continue listening to the correct -MAIN instance. When REPLICA restarts, `--replication-restore-state-on-startup` must be set to -`true` to continue getting updates from the MAIN. +From Memgraph version 2.15, a REPLICA instance has integrated support to only +listen to one MAIN. This part is introduced to support the high availability but +also reflects on the replication. The mechanism that is used is a unique +identifier that which MAIN instance sends to all REPLICAs when REPLICA is first +registered on a MAIN. A REPLICA stores the UUID of the MAIN instance it listens +to. The MAIN's UUID is also stored on a disk, in case of restart of an instance +to continue listening to the correct MAIN instance. When REPLICA restarts, +`--replication-restore-state-on-startup` must be set to `true` to continue +getting updates from the MAIN. ## Auth data replication (Enterprise) -If you are using a Memgraph Enterprise license, all authentication/authorization data, including users, roles, -and associated permissions, will be replicated. +If you are using a Memgraph Enterprise license, all authentication/authorization +data, including users, roles, and associated permissions, will be replicated. ## Auth modules replication (Enterprise) -Authentication modules are not replicated and must be configured manually by the administrator. +Authentication modules are not replicated and must be configured manually by the +administrator. ## Multi-tenant data replication (Enterprise) -When you are using a Memgraph Enterprise license, multi-tenant commands are replicated as any other data command. -Database manipulation is allowed only on MAIN. However, REPLICAs have the -ability to use databases and read data contained in them. +When you are using a Memgraph Enterprise license, multi-tenant commands are +replicated as any other data command. Database manipulation is allowed only on +MAIN. However, REPLICAs have the ability to use databases and read data +contained in them. When dropping a database used on a REPLICA, the REPLICA will receive the command -and will partially drop the database. It will hide the database and prevent any new -usage. Once all clients have released the database, it will be deleted entirely. +and will partially drop the database. It will hide the database and prevent any +new usage. Once all clients have released the database, it will be deleted +entirely. -As of Memgraph v3.5 replication queries (such as `REGISTER REPLICA`, `SHOW REPLICAS`, `DROP REPLICA`, etc.) target the default "memgraph" database and require access to it. -The recommendation is to use the default "memgraph" database as an admin/system database and store graphs under other databases. +As of Memgraph v3.5 replication queries (such as `REGISTER REPLICA`, `SHOW +REPLICAS`, `DROP REPLICA`, etc.) target the default "memgraph" database and +require access to it. The recommendation is to use the default "memgraph" +database as an admin/system database and store graphs under other databases. @@ -165,11 +175,14 @@ The recommendation is to use the default "memgraph" database as an admin/system To execute replication queries, users must have: 1. The `REPLICATION` privilege -2. **AND**ccess to the default "memgraph" database +2. **AND** access to the default "memgraph" database ### Impact on multi-tenant environments -In multi-tenant environments where users might not have access to the "memgraph" database, replication management operations will fail. This reinforces the recommendation to treat the "memgraph" database as an administrative/system database. +In multi-tenant environments where users might not have access to the "memgraph" +database, replication management operations will fail. This reinforces the +recommendation to treat the "memgraph" database as an administrative/system +database. {

Example: Admin user with replication privileges

} @@ -207,9 +220,10 @@ cluster](#set-up-a-replication-cluster). Each Memgraph instance has the role of the MAIN instance when it is first started. -Also, by default, each crashed instance restarts with its previous role (MAIN as MAIN, REPLICA as REPLICA). -To change this behavior, set the `--replication-restore-state-on-startup` to `false` when -first initializing the instance. In this way, all instances will get restarted as MAIN. +Also, by default, each crashed instance restarts with its previous role (MAIN as +MAIN, REPLICA as REPLICA). To change this behavior, set the +`--replication-restore-state-on-startup` to `false` when first initializing the +instance. In this way, all instances will get restarted as MAIN. ### Assigning the REPLICA role @@ -222,8 +236,8 @@ SET REPLICATION ROLE TO REPLICA WITH PORT ; ``` If you set the port of each REPLICA instance to `10000`, it will be easier to -register replicas later on because the query for registering replicas uses a port -10000 as the default one. +register replicas later on because the query for registering replicas uses a +port 10000 as the default one. Otherwise, you can use any unassigned port between 1000 and 10000. @@ -246,8 +260,8 @@ retrieve its original function. You need to [drop it](#dropping-a-replica-instance) from the MAIN and register it again. If the crashed MAIN instance goes back online once a new MAIN is already -assigned, it cannot reclaim its previous role. It can be cleaned and -demoted to become a REPLICA instance of the new MAIN instance. +assigned, it cannot reclaim its previous role. It can be cleaned and demoted to +become a REPLICA instance of the new MAIN instance. ### Checking the assigned role @@ -261,12 +275,12 @@ SHOW REPLICATION ROLE; Once all the nodes in the cluster are assigned with appropriate roles, you can enable replication in the MAIN instance by registering REPLICA instances, -setting a replication mode (SYNC and ASYNC), and specifying -the REPLICA instance's socket address. Memgraph doesn't support chaining REPLICA -instances, that is, a REPLICA instance cannot be replicated on another REPLICA -instance. +setting a replication mode (SYNC and ASYNC), and specifying the REPLICA +instance's socket address. Memgraph doesn't support chaining REPLICA instances, +that is, a REPLICA instance cannot be replicated on another REPLICA instance. -If you want to register a REPLICA instance with a SYNC replication mode, run the following query: +If you want to register a REPLICA instance with a SYNC replication mode, run the +following query: ```plaintext REGISTER REPLICA name SYNC TO ; @@ -280,8 +294,8 @@ REGISTER REPLICA name ASYNC TO ; ``` -If you want to register a REPLICA instance with an STRICT_SYNC replication mode, run -the following query: +If you want to register a REPLICA instance with an STRICT_SYNC replication mode, +run the following query: ```plaintext REGISTER REPLICA name STRICT_SYNC TO ; @@ -314,7 +328,8 @@ Example of a `` using only `IP_ADDRESS`: "172.17.0.5" ``` -Also, you can register REPLICA instances using DNS names. In that case, the socket address must be a string value as follows: +Also, you can register REPLICA instances using DNS names. In that case, the +socket address must be a string value as follows: ```plaintext "DOMAIN_NAME:PORT_NUMBER" @@ -327,7 +342,8 @@ number, for example: "memgraph-replica.memgraph.net:10050" ``` -If you set REPLICA roles using port `10000`, you can define the socket address specifying only the valid domain name, for example: +If you set REPLICA roles using port `10000`, you can define the socket address +specifying only the valid domain name, for example: ```plaintext "memgraph-replica.memgraph.net" @@ -335,7 +351,8 @@ If you set REPLICA roles using port `10000`, you can define the socket address s When a REPLICA instance is registered, it will start replication in ASYNC mode until it synchronizes to the current state of the database. Upon -synchronization, REPLICA instances will either continue working in the ASYNC, STRICT_SYNC or SYNC mode. +synchronization, REPLICA instances will either continue working in the ASYNC, +STRICT_SYNC or SYNC mode. ### Listing all registered REPLICA instances @@ -364,9 +381,9 @@ with the MAIN instance#synchronizing-instances. The missing data changes can be sent as snapshots or WAL files. Snapshot files represent an image of the current state of the database and are much larger than the WAL files, which only contain the changes, deltas. Because of the difference -in file size, Memgraph favors the WAL files. It is important to note that replicas -receive only changes which are made durable on the MAIN instance, in other words changes which -are already fsynced. +in file size, Memgraph favors the WAL files. It is important to note that +replicas receive only changes which are made durable on the MAIN instance, in +other words changes which are already fsynced. While the REPLICA instance is in the RECOVERY state, the MAIN instance calculates the optimal synchronization path based on the REPLICA instance's diff --git a/pages/database-management/authentication-and-authorization.mdx b/pages/database-management/authentication-and-authorization.mdx index 6eaf9d915..ad43b083f 100644 --- a/pages/database-management/authentication-and-authorization.mdx +++ b/pages/database-management/authentication-and-authorization.mdx @@ -3,29 +3,37 @@ title: Authentication and authorization description: Manage users and roles, implement role-based and fine-grained access control and learn how to integrate with other authentication systems. --- +import { Callout } from 'nextra/components' + # 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 (active from Memgraph v3.5) +## Changes to authentication requirements -As of Memgraph v3.5 there are new requirements for authentication and authorization operations, particularly affecting multi-tenant environments: +**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. +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. +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: +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 @@ -34,7 +42,8 @@ To execute system (auth, replication and multi-database) queries, users must hav ### 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 ROLE FOR `: This command does not require database specification and +will show all roles assigned to the user across all databases. ```cypher -- Show all roles for a user (works in all environments) @@ -42,7 +51,8 @@ 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: +If you need to see roles in a specific database context, you can optionally +specify: 1. **Show roles for the user's main database:** ```cypher @@ -61,7 +71,8 @@ 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 `: In multi-tenant environments, you must specify the +database context: 1. **Show privileges for the user's main database:** ```cypher @@ -78,9 +89,14 @@ SHOW PRIVILEGES FOR user_name ON CURRENT; 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. +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 PRIVILEGES FOR `: This command does not require database +specification and will show all privileges for the role. ```cypher -- Show all privileges for a role (works in all environments) @@ -93,9 +109,16 @@ 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](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements), [Multi-tenancy](/database-management/multi-tenancy#default-database-best-practices), and [Replication](/clustering/replication#replication-queries-and-the-memgraph-database) documentation. +- 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](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements), +[Multi-tenancy](/database-management/multi-tenancy#default-database-best-practices), +and +[Replication](/clustering/replication#replication-queries-and-the-memgraph-database) +documentation. ## [Users](/database-management/authentication-and-authorization/users) diff --git a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx index b84a79801..bf0d32c4e 100644 --- a/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx +++ b/pages/database-management/authentication-and-authorization/auth-system-integrations.mdx @@ -98,7 +98,9 @@ in Memgraph's output (typically in `systemd` logs using `journalctl`). ### Multiple roles support -As of v3.5 Memgraph supports multiple roles per user in auth module responses. Auth modules can return either a single role (backward compatible) or multiple roles (new format). +**As of v3.5** Memgraph supports multiple roles per user in auth module +responses. Auth modules can return either a single role (backward compatible) or +multiple roles (new format). #### Single role response (backward compatible) @@ -134,13 +136,17 @@ The system will: 1. First check for a `roles` field in the response 2. If `roles` is an array, use all roles in the array 3. If `roles` is a string, use it as a single role -4. If no `roles` field is found, fall back to the `role` field for backward compatibility +4. If no `roles` field is found, fall back to the `role` field for backward + compatibility 5. If no valid roles are found, authentication fails -When a user has multiple roles, their permissions are combined using the following rules: +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 and no role denies access to a database, the user has access +- **Denies**: If any role denies a permission, the user is denied that + permission +- **Database Access**: If any role grants and no role denies access to a + database, the user has access - **Fine-grained Permissions**: Combined using the same grant/deny logic ### Module example diff --git a/pages/database-management/authentication-and-authorization/multiple-roles.mdx b/pages/database-management/authentication-and-authorization/multiple-roles.mdx index ea9b39562..648331be5 100644 --- a/pages/database-management/authentication-and-authorization/multiple-roles.mdx +++ b/pages/database-management/authentication-and-authorization/multiple-roles.mdx @@ -7,12 +7,11 @@ import { Callout } from 'nextra/components' # Multi-role users and multi-tenant roles (Enterprise) -As of v3.5 Memgraph allows users to have multiple roles assigned to them -simultaneously. -Memgraph Enterprise supports multi-tenant roles, which allow users to have -different roles assigned to them for specific databases. This feature enables -proper tenant isolation and fine-grained access control in multi-tenant -environments. +**As of v3.5** Memgraph allows users to have multiple roles assigned to them +simultaneously. Memgraph Enterprise supports multi-tenant roles, which allow +users to have different roles assigned to them for specific databases. This +feature enables proper tenant isolation and fine-grained access control in +multi-tenant environments. ## Privileges with multiple roles @@ -22,12 +21,13 @@ following rules: - **Grant**: If any assigned role with access to the database grants a privilege, the user is granted that privilege. - **Deny**: If any assigned role with access to the database denies a privilege, - the user is denied that privilege—even if another role grants it. + the user is denied that privilege, even if another role grants it. - **Effective privilege**: The user's effective privileges are the union of all granted privileges, minus any that are denied by any role. This means that **deny always takes precedence over grant** when there is a -conflict. **Note:** The resulting user privileges contain user's privileges only +conflict.
+**Note:** The resulting user privileges contain user's privileges only if the user also has access to the database. ## Database access with users and roles