WIP

Author: andrejtonev

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

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"
 }

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
 
 </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