edx-rbac 3.1.0__py3-none-any.whl

edx_rbac/__init__.py

@@ -0,0 +1,6 @@
+"""
+Library to help managing role based access controls for django apps.
+"""
+from importlib.metadata import version
+
+__version__ = version("edx-rbac")

edx_rbac/admin/__init__.py

@@ -0,0 +1,28 @@
+"""
+Django admin integration for djangoapps using edx-rbac.
+"""
+
+from django.contrib import admin
+
+from edx_rbac.admin.forms import UserRoleAssignmentAdminForm
+
+
+class UserRoleAssignmentAdmin(admin.ModelAdmin):
+    """
+    Django admin for UserRoleAssignment.
+    """
+
+    class Meta:
+        """
+        Meta class for UserRoleAssignmentAdmin.
+        """
+        abstract = True
+
+    list_display = (
+        'user', 'role'
+    )
+
+    list_filter = ('role',)
+    search_fields = ('user__email', 'role__name')
+    fields = ('user', 'role',)
+    form = UserRoleAssignmentAdminForm

edx_rbac/admin/forms.py

@@ -0,0 +1,29 @@
+"""
+Forms to be used for djangoapps extending edx_rbac.
+"""
+
+from django import forms
+from django.utils.translation import gettext as _
+
+from edx_rbac.fields import UserFromEmailField
+
+
+class UserRoleAssignmentAdminForm(forms.ModelForm):
+    """
+    Custom Form for CRUD operations on models extending UserRoleAssignment.
+    """
+    user = UserFromEmailField(
+        label=_('User Email'),
+        required=True
+    )
+
+    class Meta:
+        abstract = True
+
+    def __init__(self, *args, **kwargs):
+        instance = kwargs.get('instance')
+        initial = kwargs.get('initial', {})
+        if instance:
+            initial['user'] = instance.user.email
+            kwargs['initial'] = initial
+        super().__init__(*args, **kwargs)

edx_rbac/apps.py

@@ -0,0 +1,13 @@
+"""
+edx_rbac Django application initialization.
+"""
+
+from django.apps import AppConfig
+
+
+class EdxRbacConfig(AppConfig):
+    """
+    Configuration for the edx_rbac Django application.
+    """
+
+    name = 'edx_rbac'

edx_rbac/constants.py

@@ -0,0 +1,16 @@
+"""
+All constants pertaining to the edx_rbac module.
+"""
+# The string denoting that a given role is applicable across all contexts
+ALL_ACCESS_CONTEXT = '*'
+
+# .. toggle_name: RBAC_IGNORE_INVALID_JWT_COOKIE
+# .. toggle_implementation: DjangoSetting
+# .. toggle_default: False
+# .. toggle_description: When true, causes instances of `jwt.exceptions.InvalidTokenError`
+#   to be ignored instead of raised in the `get_decoded_jwt()` utility function.
+#   Defaults to False for backward-compatibility purposes, but it's recommended
+#   to be set to True in dependent applications.
+# .. toggle_use_cases: opt_in
+# .. toggle_creation_date: 2024-08-19
+IGNORE_INVALID_JWT_COOKIE_SETTING = 'RBAC_IGNORE_INVALID_JWT_COOKIE'

edx_rbac/decorators.py

@@ -0,0 +1,43 @@
+"""
+Taken from https://github.com/escodebar/django-rest-framework-rules/blob/master/rest_framework_rules/decorators.py.
+"""
+
+import functools
+
+import crum
+
+
+def permission_required(*permissions, **decorator_kwargs):
+    """
+    Verify permissions for access to the api.
+
+    :param permissions: Permissions added via django_rules add_perm
+    :param decorator_kwargs: Arguments for permission checks
+    :return: decorator
+    """
+    def decorator(view):
+        """Verify permissions decorator."""
+        @functools.wraps(view)
+        def wrapped_view(self, request, *args, **kwargs):
+            """Wrap for the view function."""
+            fn = decorator_kwargs.get('fn', None)
+            if callable(fn):
+                obj = fn(request, *args, **kwargs)
+            else:
+                obj = fn
+
+            crum.set_current_request(request)
+
+            missing_permissions = [perm for perm in permissions
+                                   if not request.user.has_perm(perm, obj)]
+            if any(missing_permissions):
+                # raises a permission denied exception causing a 403 response
+                self.permission_denied(
+                    request,
+                    message=f"Missing: {', '.join(missing_permissions)}"
+                )
+
+            return view(self, request, *args, **kwargs)
+        return wrapped_view
+
+    return decorator

edx_rbac/fields.py

@@ -0,0 +1,29 @@
+"""
+Fields to be used for djangoapps extending edx_rbac.
+"""
+
+from django import forms
+from django.apps import apps
+from django.conf import settings
+from django.core.exceptions import ValidationError
+
+USER_MODEL = apps.get_model(settings.AUTH_USER_MODEL)
+
+
+class UserFromEmailField(forms.EmailField):
+    """
+    Custom Form Field class for selecting users by entering an email.
+
+    Meant to be used for models with foreign keys to the user table.
+    """
+
+    def clean(self, value):
+        """
+        Override for UserFromEmailField clean method.
+        """
+        try:
+            user = USER_MODEL.objects.get(email=value)
+        except USER_MODEL.DoesNotExist as error:
+            raise ValidationError(f'User with email {value} does not exist') from error
+
+        return user

edx_rbac/mixins.py

@@ -0,0 +1,183 @@
+"""
+Mixin adapted from https://github.com/escodebar/django-rest-framework-rules/blob/master/rest_framework_rules/mixins.py.
+
+Keeps py2 backward compatibility and only holds on to the necessary bits of the mixin needed.
+"""
+
+import crum
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.functional import cached_property
+
+from edx_rbac import utils
+
+
+class PermissionRequiredMixin:
+    """
+    Mixin for checking permissions with django rules.
+    """
+
+    object_permission_required = None
+    permission_required = None
+
+    def get_permission_required(self):
+        """
+        Return permissions required for the view it is mixed into.
+        """
+        if self.permission_required is None:
+            # This prevents a misconfiguration of the view into which the mixin
+            # is mixed. If the mixin is used, at least one permission should be
+            # required.
+            raise ImproperlyConfigured(
+                f'{self.__class__.__name__} is missing the permission_required attribute. Define '
+                f'{self.__class__.__name__}.permission_required, or override '
+                f'{self.__class__.__name__}.get_permission_required().'
+            )
+        if isinstance(self.permission_required, str):
+            perms = (self.permission_required, )
+        else:
+            perms = self.permission_required
+        return perms
+
+    def check_permissions(self, request):
+        """
+        Check through permissions required and throws a permission_denied if missing any.
+
+        If `get_permission_object` is implemented, it will be called and should return the object
+        for which the @rules predicate checks against.
+        """
+        crum.set_current_request(request)
+        user = request.user
+
+        if hasattr(self, 'get_permission_object') and callable(self.get_permission_object):
+            obj = self.get_permission_object()
+        else:
+            obj = None
+
+        missing_permissions = [perm for perm in self.get_permission_required()
+                               if not user.has_perm(perm, obj)]
+
+        if any(missing_permissions):
+            self.permission_denied(
+                request,
+                message=f"MISSING: {', '.join(missing_permissions)}"
+            )
+
+
+class PermissionRequiredForListingMixin(PermissionRequiredMixin):
+    """
+    Mixin for checking role-based access against multiple objects, specifically
+    using the "list" action of a DRF ViewSet.  The brunt of the work is done in
+    the `accessible_contexts` cached property - this property determines the set
+    of "contexts" (probably identifiers of some model) to which the requesting
+    user has access under any of the `allowed_roles`.  It's pretty opinionated and
+    you _must_ define the following fields:
+
+    `list_lookup_field` (string) - The field of the model you want to list instances of
+    that holds values defined by `accessible_contexts`.
+
+    `allowed_roles` (list) - A list of one or more roles against which access is checked.  It's disjunctive,
+    which means that if "role_1" grants access to resources "A" and "B", and
+    "role_2" grants access to resource "C", defining `allowed_roles = ['role_1', 'role_2']`
+    will cause resources "A", "B", and "C" to be returned by a listing operation
+    for a user who is granted both "role_1" and "role_2".
+
+    `role_assignment_class` (class) - The RoleAssignmentClass against which DB-defined access is checked.
+
+    `base_queryset` (property) - A queryset which acts as the "base case".  It should generally return
+    all accessible instances for a user who has access to anything within this viewset (like a superuser
+    or admin).
+    """
+    # This flag indicates whether requesting users with `is_staff = True`
+    # should ever encounter a PermissionDenied exception.
+    staff_are_never_forbidden = True
+
+    # This flag indicates whether requesting users with `is_superuser = True`
+    # should always have the `ALL_ACCESS_CONTEXT` included in their set of accessible contexts.
+    superusers_can_access_anything = True
+
+    # The field (as a string) of the model you want to list instances of.
+    list_lookup_field = None
+
+    # A list of one or more roles against which access is checked.
+    allowed_roles = []
+
+    # The RoleAssignmentClass against which DB-defined access is checked
+    role_assignment_class = None
+
+    @property
+    def base_queryset(self):
+        """
+        Should return a queryset that acts as the "base case".
+        It should generally return all accessible instances for a user who has access
+        to everything within this viewset (like a superuser or admin).
+        """
+        raise NotImplementedError
+
+    @cached_property
+    def request_action(self):
+        """
+        Returns `self.action` if it exists, None otherwise.
+        """
+        return getattr(self, 'action', None)
+
+    @cached_property
+    def accessible_contexts(self):
+        """
+        Cached set of contexts (usually model identifiers) the requesting user has access to.
+        Returns a set that contains the `ALL_ACCESS_CONTEXT` identifier
+        if the requesting user is a superuser.
+        """
+        contexts_via_jwt = utils.contexts_accessible_from_request(self.request, self.allowed_roles)
+        contexts_via_db = set()
+
+        if self.role_assignment_class:
+            contexts_via_db = utils.contexts_accessible_from_database(
+                self.request.user, self.allowed_roles, self.role_assignment_class
+            )
+
+        if self.request.user.is_superuser and self.superusers_can_access_anything:
+            contexts_via_db.add(utils.ALL_ACCESS_CONTEXT)
+
+        return contexts_via_jwt | contexts_via_db
+
+    def check_permissions(self, request):
+        """
+        If dealing with a "list" action, goes through some customized
+        logic to check which contexts are accessible by the requesting
+        user.  If none are, and the user is not staff/super, raise
+        a `PermissionDenied` exception.  Uses the parent class's `check_permissions()`
+        method if the request action is not "list".
+        """
+        if self.request_action == 'list':
+            # Super-users and staff won't get Forbidden responses,
+            # but depending on their assigned roles, staff may
+            # get an empty result set.
+            if request.user.is_superuser:
+                return
+            if request.user.is_staff and self.staff_are_never_forbidden:
+                return
+            if not self.accessible_contexts:
+                self.permission_denied(request)
+        else:
+            super().check_permissions(request)
+
+    def get_queryset(self):
+        """
+        Expects `self.base_queryset` to be explicitly defined as the "base case"
+        and `self.list_lookup_field` to be defined.
+        You'll most likely want it to be `MyModel.objects.all().order_by('some_field')`.
+        """
+        if getattr(self, 'base_queryset', None) is None:
+            raise Exception(f'{self.__class__} must have a non-null "base_queryset" field.')
+        if not getattr(self, 'list_lookup_field', None):
+            raise Exception(f'{self.__class__} must have a truthy "list_lookup_field" field.')
+
+        if self.request_action == 'list':
+            if not self.accessible_contexts:
+                return self.base_queryset.none()
+            if utils.has_access_to_all(self.accessible_contexts):
+                return self.base_queryset
+            kwargs = {self.list_lookup_field + '__in': self.accessible_contexts}
+            return self.base_queryset.filter(**kwargs)
+
+        return self.base_queryset

edx_rbac/models.py

@@ -0,0 +1,113 @@
+"""
+Database models for edx_rbac.
+"""
+
+from django.conf import settings
+from django.core.exceptions import FieldDoesNotExist
+from django.db import models
+from django.db.models.base import ModelBase
+from django.utils.translation import gettext_lazy as _
+from model_utils.models import TimeStampedModel
+
+
+class UserRoleAssignmentCreator(ModelBase):
+    """
+    The model extending UserRoleAssignment should get a foreign key to a model that is a subclass of UserRole.
+    """
+
+    def __new__(mcs, name, bases, attrs):
+        """
+        Override to dynamically create foreign key for objects begotten from abstract class.
+        """
+        model = super().__new__(mcs, name, bases, attrs)
+        if model.__name__ != 'UserRoleAssignment' and 'UserRoleAssignment' in [b.__name__ for b in bases]:
+            try:
+                model._meta.get_field('role')
+            except FieldDoesNotExist as error:
+                if model.role_class and issubclass(model.role_class, UserRole):
+                    model.add_to_class(
+                        'role',
+                        models.ForeignKey(model.role_class, db_index=True, on_delete=models.CASCADE),
+                    )
+                else:
+                    raise Exception('role_class must be defined for any subclass of UserRole!') from error
+        return model
+
+
+class UserRole(TimeStampedModel):
+    """
+    Model defining a role a user can have.
+    """
+
+    name = models.CharField(unique=True, max_length=255, db_index=True)
+    description = models.TextField(null=True, blank=True)
+
+    class Meta:
+        """
+        Meta class for UserRole.
+        """
+
+        abstract = True
+
+    def __str__(self):
+        """
+        Return human-readable string representation.
+        """
+        return self.name
+
+
+class UserRoleAssignment(TimeStampedModel, metaclass=UserRoleAssignmentCreator):
+    """
+    Model for mapping users and their roles.
+    """
+    role_class = None
+
+    user = models.ForeignKey(settings.AUTH_USER_MODEL, db_index=True, on_delete=models.CASCADE)
+
+    applies_to_all_contexts = models.BooleanField(
+        default=False,
+        null=False,
+        help_text=_(
+            'If true, indicates that the user is effectively assigned their role for any and all contexts. '
+            'Defaults to False.'
+        ),
+    )
+
+    class Meta:
+        """
+        Meta class for UserRoleAssignment.
+        """
+
+        abstract = True
+
+    def get_context(self):
+        """
+        Return relevant context data related to this role assignment. Defaults to returning None.
+        """
+        return None
+
+    @classmethod
+    def get_assignments(cls, user, role_names=None):
+        """
+        Return iterator of (rolename, context).
+        """
+        if not user.is_anonymous:
+            kwargs = {'user': user}
+            if role_names:
+                kwargs['role__name__in'] = role_names
+
+            for assignment in cls.objects.filter(**kwargs).select_related('role'):
+                yield assignment.role.name, assignment.get_context()
+
+    def __str__(self):
+        """
+        Return human-readable string representation.
+        """
+        # pylint: disable=no-member
+        return f'{self.user.id}:{self.role.name}'
+
+    def __repr__(self):
+        """
+        Return uniquely identifying string representation.
+        """
+        return self.__str__()

edx_rbac/templates/edx_rbac/base.html

@@ -0,0 +1,22 @@
+
+{% comment %}
+As the developer of this package, don't place anything here if you can help it
+since this allows developers to have interoperability between your template
+structure and their own.
+
+Example: Developer melding the 2SoD pattern to fit inside with another pattern::
+
+    {% extends "base.html" %}
+    {% load static %}
+
+    <!-- Their site uses old school block layout -->
+    {% block extra_js %}
+
+        <!-- Your package using 2SoD block layout -->
+        {% block javascript %}
+            <script src="{% static 'js/ninja.js' %}" type="text/javascript"></script>
+        {% endblock javascript %}
+
+    {% endblock extra_js %}
+{% endcomment %}
+

edx_rbac/urls.py

@@ -0,0 +1,10 @@
+"""
+URLs for edx_rbac.
+"""
+
+from django.urls import re_path
+from django.views.generic import TemplateView
+
+urlpatterns = [
+    re_path(r'', TemplateView.as_view(template_name="edx_rbac/base.html")),
+]