Group Permissions
A comprehensive guide to group permissioning in R2R
Introduction
R2R provides robust group management features, allowing developers to implement efficient access control and organization of users and documents. This cookbook will guide you through the group permissioning capabilities of R2R.
For user authentication and management, please refer to the User Auth Cookbook.
Group permissioning in R2R is still under development and as a result the API will likely evolve.
Setup
Ensure you have R2R installed and configured as described in the installation guide. For this guide, we’ll use the default configuration. Make sure r2r serve is running in your local environment or local Docker engine.
Basic Usage
Groups currently follow a flat hierarchy wherein superusers are responsible for management operations. This functionality will expand as development on R2R continues.
Creating a Group
Let’s start by creating a new group:
from r2r import R2RClient
client = R2RClient("http://localhost:7272") # Replace with your R2R deployment URL
# Assuming you're logged in as an admin or a user with appropriate permissions
# For testing, the default R2R implementation will grant superuser privileges to anon api calls
group_result = client.create_group("Marketing Team", "Group for marketing department")
print(f"Group creation result: {group_result}")
# {'results': {'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Marketing Team', 'description': 'Group for marketing department', 'created_at': '2024-07-16T22:53:47.524794Z', 'updated_at': '2024-07-16T22:53:47.524794Z'}}
Getting Group Details
To retrieve details about a specific group:
group_id = '123e4567-e89b-12d3-a456-426614174000' # Use the group_id from the creation result
group_details = client.get_group(group_id)
print(f"Group details: {group_details}")
# {'results': {'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Marketing Team', 'description': 'Group for marketing department', 'created_at': '2024-07-16T22:53:47.524794Z', 'updated_at': '2024-07-16T22:53:47.524794Z'}}
Updating a Group
You can update a group’s name or description:
update_result = client.update_group(group_id, name="Updated Marketing Team", description="New description for marketing team")
print(f"Group update result: {update_result}")
# {'results': {'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Updated Marketing Team', 'description': 'New description for marketing team', 'created_at': '2024-07-16T22:53:47.524794Z', 'updated_at': '2024-07-16T23:15:30.123456Z'}}
Listing Groups
To get a list of all groups:
groups_list = client.list_groups()
print(f"Groups list: {groups_list}")
# {'results': [{'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Updated Marketing Team', 'description': 'New description for marketing team', 'created_at': '2024-07-16T22:53:47.524794Z', 'updated_at': '2024-07-16T23:15:30.123456Z'}, ...]}
User Management in Groups
Adding a User to a Group
To add a user to a group, you need both the user’s ID and the group’s ID:
user_id = '456e789f-g01h-34i5-j678-901234567890' # This should be a valid user ID
add_user_result = client.add_user_to_group(user_id, group_id)
print(f"Add user to group result: {add_user_result}")
# {'results': {'message': 'User successfully added to the group'}}
Removing a User from a Group
Similarly, to remove a user from a group:
remove_user_result = client.remove_user_from_group(user_id, group_id)
print(f"Remove user from group result: {remove_user_result}")
# {'results': {'message': 'User successfully removed from the group'}}
Listing Users in a Group
To get a list of all users in a specific group:
users_in_group = client.get_users_in_group(group_id)
print(f"Users in group: {users_in_group}")
# {'results': [{'user_id': '456e789f-g01h-34i5-j678-901234567890', 'email': '[email protected]', 'name': 'John Doe', ...}, ...]}
Getting Groups for a User
To get all groups that a user is a member of:
user_groups = client.user_groups(user_id)
print(f"User's groups: {user_groups}")
# {'results': [{'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Updated Marketing Team', ...}, ...]}
Document Management in Groups
Assigning a Document to a Group
To assign a document to a group:
document_id = '789g012j-k34l-56m7-n890-123456789012' # This should be a valid document ID
assign_doc_result = client.assign_document_to_group(document_id, group_id)
print(f"Assign document to group result: {assign_doc_result}")
# {'results': {'message': 'Document successfully assigned to the group'}}
Removing a Document from a Group
To remove a document from a group:
remove_doc_result = client.remove_document_from_group(document_id, group_id)
print(f"Remove document from group result: {remove_doc_result}")
# {'results': {'message': 'Document successfully removed from the group'}}
Listing Documents in a Group
To get a list of all documents in a specific group:
docs_in_group = client.documents_in_group(group_id)
print(f"Documents in group: {docs_in_group}")
# {'results': [{'document_id': '789g012j-k34l-56m7-n890-123456789012', 'title': 'Marketing Strategy 2024', ...}, ...]}
Getting Groups for a Document
To get all groups that a document is assigned to:
document_groups = client.document_groups(document_id)
print(f"Document's groups: {document_groups}")
# {'results': [{'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Updated Marketing Team', ...}, ...]}
Advanced Group Management
Group Overview
To get an overview of groups, including user and document counts:
groups_overview = client.groups_overview()
print(f"Groups overview: {groups_overview}")
# {'results': [{'group_id': '123e4567-e89b-12d3-a456-426614174000', 'name': 'Updated Marketing Team', 'description': 'New description for marketing team', 'user_count': 5, 'document_count': 10, ...}, ...]}
Deleting a Group
To delete a group:
delete_result = client.delete_group(group_id)
print(f"Delete group result: {delete_result}")
# {'results': {'message': 'Group successfully deleted'}}
Pagination and Filtering
Many of the group-related methods support pagination and filtering. Here are some examples:
# List groups with pagination
paginated_groups = client.list_groups(offset=10, limit=20)
# Get users in a group with pagination
paginated_users = client.get_users_in_group(group_id, offset=5, limit=10)
# Get documents in a group with pagination
paginated_docs = client.documents_in_group(group_id, offset=0, limit=50)
# Get groups overview with specific group IDs
specific_groups_overview = client.groups_overview(group_ids=['id1', 'id2', 'id3'])
Security Considerations
When implementing group permissions, consider the following security best practices:
- Least Privilege Principle: Assign the minimum necessary permissions to users and groups.
- Regular Audits: Periodically review group memberships and document assignments.
- Access Control: Ensure that only authorized users (e.g., admins) can perform group management operations.
- Logging and Monitoring: Implement comprehensive logging for all group-related actions.
Customizing Group Permissions
While R2R’s current group system follows a flat hierarchy, you can build more complex permission structures on top of it:
- Custom Roles: Implement application-level roles within groups (e.g., group admin, editor, viewer).
- Hierarchical Groups: Create a hierarchy by establishing parent-child relationships between groups in your application logic.
- Permission Inheritance: Implement rules for permission inheritance based on group memberships.
Troubleshooting
Here are some common issues and their solutions:
- Unable to Create/Modify Groups: Ensure the user has superuser privileges.
- User Not Seeing Group Content: Verify that the user is correctly added to the group and that documents are properly assigned.
- Performance Issues with Large Groups: Use pagination when retrieving users or documents in large groups.
Conclusion
R2R’s group permissioning system provides a foundation for implementing sophisticated access control in your applications. As the feature set evolves, more advanced capabilities will become available. Stay tuned to the R2R documentation for updates and new features related to group permissions.
For user authentication and individual user management, refer to the User Auth Cookbook. For more advanced use cases or custom implementations, consult the R2R documentation or reach out to the community for support.
Was this page helpful?