From 563d8c57b37892416ed58d74b9cb1b19ddd1acc4 Mon Sep 17 00:00:00 2001 From: Matea Pesic <80577904+matea16@users.noreply.github.com> Date: Fri, 11 Jul 2025 11:48:05 +0200 Subject: [PATCH 1/7] update direct download links (#1335) --- .../direct-download-links.mdx | 31 +++++++++---------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/pages/getting-started/install-memgraph/direct-download-links.mdx b/pages/getting-started/install-memgraph/direct-download-links.mdx index 81f13463..931afa3c 100644 --- a/pages/getting-started/install-memgraph/direct-download-links.mdx +++ b/pages/getting-started/install-memgraph/direct-download-links.mdx @@ -11,33 +11,32 @@ Download Hub](https://memgraph.com/download/). If you need direct links for the latest version of Memgraph database, take a look at the list below. ## Docker -- [https://download.memgraph.com/memgraph/v3.3.0/docker/memgraph-3.3.0-docker.tar.gz](https://download.memgraph.com/memgraph/v3.3.0/docker/memgraph-3.3.0-docker.tar.gz) -- [https://download.memgraph.com/memgraph/v3.3.0/docker-aarch64/memgraph-3.3.0-docker.tar.gz](https://download.memgraph.com/memgraph/v3.3.0/docker-aarch64/memgraph-3.3.0-docker.tar.gz) -- [https://download.memgraph.com/memgraph/v3.3.0/docker-relwithdebinfo/memgraph-3.3.0-relwithdebinfo-docker.tar.gz](https://download.memgraph.com/memgraph/v3.3.0/docker-relwithdebinfo/memgraph-3.3.0-relwithdebinfo-docker.tar.gz) -- [https://download.memgraph.com/memgraph/v3.3.0/docker-aarch64-relwithdebinfo/memgraph-3.3.0-relwithdebinfo-docker.tar.gz](https://download.memgraph.com/memgraph/v3.3.0/docker-aarch64-relwithdebinfo/memgraph-3.3.0-relwithdebinfo-docker.tar.gz) +- [https://download.memgraph.com/memgraph/v3.4.0/docker/memgraph-3.4.0-docker.tar.gz](https://download.memgraph.com/memgraph/v3.4.0/docker/memgraph-3.4.0-docker.tar.gz) +- [https://download.memgraph.com/memgraph/v3.4.0/docker-aarch64/memgraph-3.4.0-docker.tar.gz](https://download.memgraph.com/memgraph/v3.4.0/docker-aarch64/memgraph-3.4.0-docker.tar.gz) +- [https://download.memgraph.com/memgraph/v3.4.0/docker-relwithdebinfo/memgraph-3.4.0-relwithdebinfo-docker.tar.gz](https://download.memgraph.com/memgraph/v3.4.0/docker-relwithdebinfo/memgraph-3.4.0-relwithdebinfo-docker.tar.gz) +- [https://download.memgraph.com/memgraph/v3.4.0/docker-aarch64-relwithdebinfo/memgraph-3.4.0-relwithdebinfo-docker.tar.gz](https://download.memgraph.com/memgraph/v3.4.0/docker-aarch64-relwithdebinfo/memgraph-3.4.0-relwithdebinfo-docker.tar.gz) ## Linux Memgraph can be run on the Linux distributions listed below. ### CentOS -- [https://download.memgraph.com/memgraph/v3.3.0/centos-9/memgraph-3.3.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.3.0/centos-9/memgraph-3.3.0_1-1.x86_64.rpm) -- [https://download.memgraph.com/memgraph/v3.3.0/centos-10/memgraph-3.3.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.3.0/centos-10/memgraph-3.3.0_1-1.x86_64.rpm) +- [https://download.memgraph.com/memgraph/v3.4.0/centos-9/memgraph-3.4.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.4.0/centos-9/memgraph-3.4.0_1-1.x86_64.rpm) +- [https://download.memgraph.com/memgraph/v3.4.0/centos-10/memgraph-3.4.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.4.0/centos-10/memgraph-3.4.0_1-1.x86_64.rpm) ### Debian -- [https://download.memgraph.com/memgraph/v3.3.0/debian-11/memgraph_3.3.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.3.0/debian-11/memgraph_3.3.0-1_amd64.deb) -- [https://download.memgraph.com/memgraph/v3.3.0/debian-12/memgraph_3.3.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.3.0/debian-12/memgraph_3.3.0-1_amd64.deb) +- [https://download.memgraph.com/memgraph/v3.4.0/debian-11/memgraph_3.4.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.4.0/debian-11/memgraph_3.4.0-1_amd64.deb) +- [https://download.memgraph.com/memgraph/v3.4.0/debian-12/memgraph_3.4.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.4.0/debian-12/memgraph_3.4.0-1_amd64.deb) ### Fedora -- [https://download.memgraph.com/memgraph/v3.3.0/fedora-41/memgraph-3.3.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.3.0/fedora-41/memgraph-3.3.0_1-1.x86_64.rpm) +- [https://download.memgraph.com/memgraph/v3.4.0/fedora-41/memgraph-3.4.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.4.0/fedora-41/memgraph-3.4.0_1-1.x86_64.rpm) ### Red Hat -- [https://download.memgraph.com/memgraph/v3.3.0/centos-9/memgraph-3.3.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.3.0/centos-9/memgraph-3.3.0_1-1.x86_64.rpm) +- [https://download.memgraph.com/memgraph/v3.4.0/centos-9/memgraph-3.4.0_1-1.x86_64.rpm](https://download.memgraph.com/memgraph/v3.4.0/centos-9/memgraph-3.4.0_1-1.x86_64.rpm) ### Ubuntu -- [https://download.memgraph.com/memgraph/v3.3.0/ubuntu-22.04/memgraph_3.3.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.3.0/ubuntu-22.04/memgraph_3.3.0-1_amd64.deb) -- [https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04/memgraph_3.3.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04/memgraph_3.3.0-1_amd64.deb) -- [https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04-relwithdebinfo/memgraph_3.3.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04-relwithdebinfo/memgraph_3.3.0-1_amd64.deb) -- [https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04-aarch64/memgraph_3.3.0-1_arm64.deb](https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04-aarch64/memgraph_3.3.0-1_arm64.deb) -- [https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04-aarch64-relwithdebinfo/memgraph_3.3.0-1_arm64.deb](https://download.memgraph.com/memgraph/v3.3.0/ubuntu-24.04-aarch64-relwithdebinfo/memgraph_3.3.0-1_arm64.deb) - +- [https://download.memgraph.com/memgraph/v3.4.0/ubuntu-22.04/memgraph_3.4.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.4.0/ubuntu-22.04/memgraph_3.4.0-1_amd64.deb) +- [https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04/memgraph_3.4.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04/memgraph_3.4.0-1_amd64.deb) +- [https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04-relwithdebinfo/memgraph_3.4.0-1_amd64.deb](https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04-relwithdebinfo/memgraph_3.4.0-1_amd64.deb) +- [https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04-aarch64/memgraph_3.4.0-1_arm64.deb](https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04-aarch64/memgraph_3.4.0-1_arm64.deb) +- [https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04-aarch64-relwithdebinfo/memgraph_3.4.0-1_arm64.deb](https://download.memgraph.com/memgraph/v3.4.0/ubuntu-24.04-aarch64-relwithdebinfo/memgraph_3.4.0-1_arm64.deb) From 3498617d9782a946077a841f546b46cbfdbdd94a Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Tue, 15 Jul 2025 16:03:33 +0200 Subject: [PATCH 2/7] 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 9fb2be18..f78cb5f5 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 52e2d13d..57ddebd2 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 f5cd5e6c..af64f594 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 00000000..8686ec08 --- /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 7f1f93b8..43d71208 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 41b8393e..60d4e218 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 ad9a9700dd5e18438b00313073d68049021d820e Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Thu, 17 Jul 2025 11:06:51 +0200 Subject: [PATCH 3/7] 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 f78cb5f5..8f16579b 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 57ddebd2..43eade6c 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 af64f594..73b19c25 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 8686ec08..f32e3a18 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 43d71208..71cc02cc 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 60d4e218..67576102 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 981dce1441e8082d96d80c4f4250db9ead4a7816 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 15:08:06 +0200 Subject: [PATCH 4/7] 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 73b19c25..832a5eb5 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 402080049efb0ef8fd14dcbdfd2c40e830dfb621 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 16:38:37 +0200 Subject: [PATCH 5/7] 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 8f16579b..2300c550 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 f32e3a18..faff8514 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 71cc02cc..8ea2fc26 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 f40366fe..31a5b821 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 267972e8..cb71bdb1 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 1cc31925cd9864aef98f0876b20640d96a3dac06 Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 16:43:22 +0200 Subject: [PATCH 6/7] 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 efd1817b..36a21ff7 100644 --- a/pages/clustering/replication.mdx +++ b/pages/clustering/replication.mdx @@ -145,6 +145,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 2300c550..ca93ce07 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 faff8514..2d5ee976 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 8ea2fc26..00af1ca1 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 31a5b821..b358e23b 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 cb71bdb1..97624378 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 d18ff45800da6dd9df1f09143abfcba3561aa64c Mon Sep 17 00:00:00 2001 From: Andreja Tonev Date: Fri, 18 Jul 2025 17:30:44 +0200 Subject: [PATCH 7/7] 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 ca93ce07..528d9f73 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 2d5ee976..ee4f8257 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 00af1ca1..f5c40edb 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 b358e23b..bed438b3 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 97624378..4da40200 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.