Multi-role user with ability to link roles to specific databases

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

pages/database-management/authentication-and-authorization.mdx

@@ -9,6 +9,80 @@ 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.
+
+### 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_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:
+- Treating the default "memgraph" database as an administrative/system database
+- Restricting access to the "memgraph" database to privileged users only
+- Storing application data in tenant-specific databases
+- Ensuring users who need to perform authentication, replication, or multi-database operations have appropriate access
+
+For detailed information about these requirements and best practices, see the [Role-based access control](/database-management/authentication-and-authorization/role-based-access-control#authentication-and-authorization-requirements), [Multi-tenancy](/database-management/multi-tenancy#default-database-best-practices), and [Replication](/clustering/replication#replication-queries-and-the-memgraph-database) documentation.
+
 ## [Users](/database-management/authentication-and-authorization/users)
 
 Learn how to manage users in Memgraph.
@@ -17,6 +91,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 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.
+
 ## [Auth system integrations](/database-management/authentication-and-authorization/auth-system-integrations) (Enterprise)
 
 Learn how to integrate with third-party auth systems and manage user

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 and multi-tenant roles",
     "auth-system-integrations": "Auth system integrations",
     "impersonate-user": "Impersonate user"
 }

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)
     - `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 and no role denies 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
@@ -150,19 +206,32 @@ 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.
+
 <Callout type="info">
 
 For correct operation, the Memgraph roles defined in the mapping need to be
 created in the Memgraph DB beforehand. Additionally, you have to grant [label-based permissions](/database-management/authentication-and-authorization/role-based-access-control#label-based-access-control) to the roles used in SSO.
 
 </Callout>
 
+<Callout type="info">
+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.
+</Callout>
+
 ### SAML
 
 Memgraph has built-in support for single sign-on (SSO) over the SAML protocol