|
| 1 | +# Media Permissions in MediaCMS |
| 2 | + |
| 3 | +This document explains the permission system in MediaCMS, which controls who can view, edit, and manage media files. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +MediaCMS provides a flexible permission system that allows fine-grained control over media access. The system supports: |
| 8 | + |
| 9 | +1. **Basic permissions** - Public, private, and unlisted media |
| 10 | +2. **User-specific permissions** - Direct permissions granted to specific users |
| 11 | +3. **Role-Based Access Control (RBAC)** - Category-based permissions through group membership |
| 12 | + |
| 13 | +## Media States |
| 14 | + |
| 15 | +Every media file has a state that determines its basic visibility: |
| 16 | + |
| 17 | +- **Public** - Visible to everyone |
| 18 | +- **Private** - Only visible to the owner and users with explicit permissions |
| 19 | +- **Unlisted** - Not listed in public listings but accessible via direct link |
| 20 | + |
| 21 | + |
| 22 | +## User Roles |
| 23 | + |
| 24 | +MediaCMS has several user roles that affect permissions: |
| 25 | + |
| 26 | +- **Regular User** - Can upload and manage their own media |
| 27 | +- **Advanced User** - Additional capabilities (configurable) |
| 28 | +- **MediaCMS Editor** - Can edit and review content across the platform |
| 29 | +- **MediaCMS Manager** - Full management capabilities |
| 30 | +- **Admin** - Complete system access |
| 31 | + |
| 32 | +## Direct Media Permissions |
| 33 | + |
| 34 | +The `MediaPermission` model allows granting specific permissions to individual users: |
| 35 | + |
| 36 | +### Permission Levels |
| 37 | + |
| 38 | +- **Viewer** - Can view the media even if it's private |
| 39 | +- **Editor** - Can view and edit the media's metadata |
| 40 | +- **Owner** - Full control, including deletion |
| 41 | + |
| 42 | +## Role-Based Access Control (RBAC) |
| 43 | + |
| 44 | +When RBAC is enabled (`USE_RBAC` setting), permissions can be managed through categories and groups: |
| 45 | + |
| 46 | +1. Categories can be marked as RBAC-controlled |
| 47 | +2. Users are assigned to RBAC groups with specific roles |
| 48 | +3. RBAC groups are associated with categories |
| 49 | +4. Users inherit permissions to media in those categories based on their role |
| 50 | + |
| 51 | +### RBAC Roles |
| 52 | + |
| 53 | +- **Member** - Can view media in the category |
| 54 | +- **Contributor** - Can view and edit media in the category |
| 55 | +- **Manager** - Full control over media in the category |
| 56 | + |
| 57 | +## Permission Checking Methods |
| 58 | + |
| 59 | +The User model provides several methods to check permissions: |
| 60 | + |
| 61 | +```python |
| 62 | +# From users/models.py |
| 63 | +def has_member_access_to_media(self, media): |
| 64 | + # Check if user can view the media |
| 65 | + # ... |
| 66 | + |
| 67 | +def has_contributor_access_to_media(self, media): |
| 68 | + # Check if user can edit the media |
| 69 | + # ... |
| 70 | + |
| 71 | +def has_owner_access_to_media(self, media): |
| 72 | + # Check if user has full control over the media |
| 73 | + # ... |
| 74 | +``` |
| 75 | + |
| 76 | +## How Permissions Are Applied |
| 77 | + |
| 78 | +When a user attempts to access media, the system checks permissions in this order: |
| 79 | + |
| 80 | +1. Is the media public? If yes, allow access. |
| 81 | +2. Is the user the owner of the media? If yes, allow full access. |
| 82 | +3. Does the user have direct permissions through MediaPermission? If yes, grant the corresponding access level. |
| 83 | +4. If RBAC is enabled, does the user have access through category membership? If yes, grant the corresponding access level. |
| 84 | +5. If none of the above, deny access. |
| 85 | + |
| 86 | +## Media Sharing |
| 87 | + |
| 88 | +Users can share media with others by: |
| 89 | + |
| 90 | +1. Making it public or unlisted |
| 91 | +2. Granting direct permissions to specific users |
| 92 | +3. Adding it to a category that's accessible to an RBAC group |
| 93 | + |
| 94 | +## Implementation Details |
| 95 | + |
| 96 | +### Media Listing |
| 97 | + |
| 98 | +When listing media, the system filters based on permissions: |
| 99 | + |
| 100 | +```python |
| 101 | +# Simplified example from files/views/media.py |
| 102 | +def _get_media_queryset(self, request, user=None): |
| 103 | + # 1. Public media |
| 104 | + listable_media = Media.objects.filter(listable=True) |
| 105 | + |
| 106 | + if not request.user.is_authenticated: |
| 107 | + return listable_media |
| 108 | + |
| 109 | + # 2. User permissions for authenticated users |
| 110 | + user_media = Media.objects.filter(permissions__user=request.user) |
| 111 | + |
| 112 | + # 3. RBAC for authenticated users |
| 113 | + if getattr(settings, 'USE_RBAC', False): |
| 114 | + rbac_categories = request.user.get_rbac_categories_as_member() |
| 115 | + rbac_media = Media.objects.filter(category__in=rbac_categories) |
| 116 | + |
| 117 | + # Combine all accessible media |
| 118 | + return listable_media.union(user_media, rbac_media) |
| 119 | +``` |
| 120 | + |
| 121 | +### Permission Checking |
| 122 | + |
| 123 | +The system uses helper methods to check permissions: |
| 124 | + |
| 125 | +```python |
| 126 | +# From users/models.py |
| 127 | +def has_member_access_to_media(self, media): |
| 128 | + # First check if user is the owner |
| 129 | + if media.user == self: |
| 130 | + return True |
| 131 | + |
| 132 | + # Then check RBAC permissions |
| 133 | + if getattr(settings, 'USE_RBAC', False): |
| 134 | + rbac_groups = RBACGroup.objects.filter( |
| 135 | + memberships__user=self, |
| 136 | + memberships__role__in=["member", "contributor", "manager"], |
| 137 | + categories__in=media.category.all() |
| 138 | + ).distinct() |
| 139 | + if rbac_groups.exists(): |
| 140 | + return True |
| 141 | + |
| 142 | + # Then check MediaShare permissions for any access |
| 143 | + media_permission_exists = MediaPermission.objects.filter( |
| 144 | + user=self, |
| 145 | + media=media, |
| 146 | + ).exists() |
| 147 | + |
| 148 | + return media_permission_exists |
| 149 | +``` |
| 150 | + |
| 151 | +## Best Practices |
| 152 | + |
| 153 | +1. **Default to Private** - Consider setting new uploads to private by default |
| 154 | +2. **Use Categories** - Organize media into categories for easier permission management |
| 155 | +3. **RBAC for Teams** - Use RBAC for team collaboration scenarios |
| 156 | +4. **Direct Permissions for Exceptions** - Use direct permissions for one-off sharing |
| 157 | + |
| 158 | +## Configuration |
| 159 | + |
| 160 | +The permission system can be configured through several settings: |
| 161 | + |
| 162 | +- `USE_RBAC` - Enable/disable Role-Based Access Control |
| 163 | + |
| 164 | +## Conclusion |
| 165 | + |
| 166 | +MediaCMS provides a flexible and powerful permission system that can accommodate various use cases, from simple personal media libraries to complex team collaboration scenarios with fine-grained access control. |
0 commit comments