drf- prbac permissions checking

[aryaniyaps]

Relevant S.O. post is here.
So I am building an api with architecture inspired by discord. I have objects called Boxes and these boxes have their own set of Roles.
The role object looks like this.

class Role(CoreModel):
    class Meta:
        ordering = ('position', 'box')

    permission_flags = (
        'ADD_STARS',
        'DOWNLOAD_FILES',
        'SEND_UPLOADS',
        'MANAGE_UPLOADS',
        'MANAGE_ROLES',
        'MANAGE_BOX',
        'MANAGE_INVITES',
        'KICK_MEMBERS',
        'BAN_MEMBERS'
    )
    default_flags = (
        'ADD_STARS',
        'DOWNLOAD_FILES',
        'SEND_UPLOADS',
    )

    color = ColorField(
        verbose_name=_('color'),
        help_text=_("role's hex color code"),
        default='#969696'
    )
    hoist = models.BooleanField(
        verbose_name=_('hoist'),
        help_text=_("whether the role can be pinned"),
        default=False
    )
    is_default = models.BooleanField(
        verbose_name=_('default'),
        help_text=_("whether the role is default"),
        default=False
    )
    position = PositionField(
        verbose_name=_('position'),
        help_text=_("position for the role"),
        collection=('box', 'is_default')
    )
    box = models.ForeignKey(
        to='uploads.Box',
        verbose_name=_('box'),
        on_delete=models.CASCADE
    )
    name = models.CharField(
        verbose_name=_('name'),
        help_text=_("role name"),
        default='new role',
        max_length=100,
        validators=[
            MinLengthValidator(2)
        ]
    )
    permissions = BitField(
        verbose_name=_('permissions'),
        help_text=_("permission bit set"),
        flags=permission_flags,
        default=default_flags
    )

    REQUIRED_FIELDS = (name, box)

I am using the bitfield extension provided by disqus here.
Roles have a set of predefined permissions which can be allowed or denied for a specific role, like

MANAGE_ROLES # allows to manage box roles
MANAGE_BOX # allows to manage and edit the box 

---

Now, users can be a part of the box, through a model called member, and they are assigned roles. The final set of permissions the user has is determined by a method.

class Member(CoreModel):
    class Meta:
        constraints = [
            models.UniqueConstraint(
                fields=('user', 'box'),
                name='unique_box_member_check'
            ),
        ]

    @cached_property
    def permissions(self):
        """
        returns permissions for the
        member in the global context.
        """
        if self.is_owner:
            return self.roles.model.permission_flags
        default_role = self.box.role_set.get(is_default=True)
        permissions = set(default_role.permissions)
        for role in self.roles.all():
            permissions |= set(role.permissions)
        # make sure that permissions are json
        # serializable to enable permission-caching
        return list(permissions)

    @cached_property
    def is_owner(self):
        # whether the member owns
        # the associated box-object
        return self.box.owner == self.user

    @cached_property
    def is_banned(self):
        # whether a ban has been
        # placed on the member already
        return self.user.ban_set.filter(box=self.box).exists()

    @cached_property
    def highest_role(self):
        # roles with the highest sorting position are
        # considered the highest roles. return the member's
        # highest role via position-wise filtering.
        # A member's highest-role might also return None
        return self.roles.order_by('-position').first()

    def has_perm(self, permission):
        # Returns whether the member has
        # the given permission succinctly
        return permission in self.permissions

    def save(self, *args, **kwargs):
        if self._state.adding:
            if self.is_banned:
                # restrict the user from creating a member account
                # in the box if a ban has been placed on them already
                raise exceptions.ValidationError(_('you are banned'))
            if self.invite is not None:
                # increase the invite's use count
                # if the field has been set already
                self.invite.increment_use_count()
        super(Member, self).save(*args, **kwargs)

    def delete(self, *args, **kwargs):
        if self.box.owner == self.user:
            # we restrict the box owner's member
            # account from being deleted. The member
            # account will however be deleted due to
            # cascades from box deletion
            raise exceptions.ValidationError(_('cannot delete member'))
        super(Member, self).delete(*args, **kwargs)

    box = models.ForeignKey(
        to='uploads.Box',
        verbose_name=_('box'),
        on_delete=models.CASCADE,
        editable=False
    )
    user = models.ForeignKey(
        to='users.User',
        verbose_name=_('user'),
        on_delete=models.CASCADE,
        editable=False
    )
    roles = models.ManyToManyField(
        to='roles.Role',
        verbose_name=_('roles'),
        help_text=_("assigned roles"),
        through='roles.MemberRole'
    )
    invite = models.ForeignKey(
        to='users.Invite',
        verbose_name=_('invite'),
        help_text=_("join invite"),
        null=True,
        on_delete=models.SET_NULL
    )

    REQUIRED_FIELDS = (box, user)

Now let's say that I have a view.

class CreateRoleView(generics.CreateAPIView):
    serializer_class = RoleSerializer

I want to make sure that only users who have the MANAGE_ROLES permission (determined by the get_permissions method) can use this view.

I know that I have to make a custom permission, but have found integrating the api for my use case very hard.
Furthermore, I want to only check for the permission if the request's method is POST, because the user is creating something here.

Can someone please help get me started?

---

Here is what I've come up with so far.
First, we need to get the associated box object for every view.

For example, in this view here,
we can get the box object by referencing the box id. But the way we get the box
differs for each view. Some views may not have the box_id in the url itself.

['boxes/<int:box_id>/roles/', views.CreateRoleView.as_view()]

So each view has a property called box as follows.

class CreateRoleView(generics.CreateAPIView):
    queryset = Role.objects.all()
    serializer_class =RoleSerializer

    @cached_property
    def box(self):
        return Box.objects.get(id=self.kwargs['box_id'])

---

Then here is the abstract base permission class which checks if the member has the required permission.

class FlagBasedPermission(permissions.BasePermission):
    """
    The Base Permission class that every flag-based-permission
    must inherit from. Provides reusable functions to validate
    the existence of permissions, as well as facilitates
    additional context validation.
    To check permissions, we need to get the member object first.
    However, as the approach to do the same differs per view, the
    `get_member` method must be suitably overwritten by subclasses.
    subclasses may also override the `override_permissions`
    method to implement permission-override logic
    """
    RELATED_METHODS = []
    PERMISSION_FLAG = None

    def override_permissions(self, member, obj=None):
        # called before checking if the permission-label exists
        # within the member's set of permissions to check for
        # potential override logic. Returns False by default
        return False

    def validate_additional_context(self, view, member, obj=None):
        # check for implementation of additional permission-logic
        # subclasses must raise permission errors to denote denial
        # when overriding the `validate_additional_context` method
        pass

    def validate_permissions(self, view, obj=None):
        # get the member-object associated
        # with the request's user account from
        # the view directly
        member = view.member
        if self.override_permissions(member, obj):
            # we can override permission-label
            # checking. Quit immediately to ensure
            # that we allow permissions for the user
            return
        if not member.has_perm(self.PERMISSION_FLAG):
            # we don't have the required permission within
            # the member's based permissions or channel
            # specific overwrites. Quit the ongoing validation
            # and raise a PermissionError to denote the same
            raise PermissionError(f'{self.PERMISSION_FLAG} required')
        self.validate_additional_context(view, member, obj)

    def has_object_permission(self, request, view, obj):
        if request.method not in self.RELATED_METHODS:
            # the permission at hand does not apply
            # for the current http method. Ignore validation
            # and allow user immediately
            return True
        try:
            self.validate_permissions(view, obj)
        except PermissionError as err:
            # the current user doesn't have the required
            # label or failed to pass additional context
            # validation. Deny permissions
            self.message = _(err)
            return False
        else:
            return True

    def has_permission(self, request, view):
        if request.method not in self.RELATED_METHODS:
            # the permission at hand does not apply
            # for the current http method. Ignore validation
            # and allow user immediately
            return True
        try:
            self.validate_permissions(view)
        except PermissionError as err:
            # the current user doesn't have the required
            # label or failed to pass additional context
            # validation. Deny permissions
            self.message = _(err)
            return False
        else:
            return True

Now I can subclass this BasePermissionClass as follows.

class ManageRoles(FlagBasedPermission):
    PERMISSION_FLAG = 'MANAGE_ROLES'
    RELATED_METHODS = ['POST', 'PATCH', 'DELETE']

And also, in cases where additional checking is required (members cannot give or take away roles from owners of the box)
we can do this.

class AddRemoveRoles(ManageRoles):
    RELATED_METHODS = ['PUT', 'DELETE']

    def validate_additional_context(self, view, member, obj=None):
        receiver = Member.objects.get(
            box_id=view.kwargs['box_id'],
            user_id=view.kwargs['user_id'],
        )
        if not member > receiver:
            raise PermissionError("member's highest role has a lower sorting position")

---

Finally, adding to the class the required permissions,

class CreateRoleView(generics.CreateAPIView):
    queryset = Role.objects.all()
    serializer_class =RoleSerializer
    permission_classes = [ManageRoles]

    @cached_property
    def box(self):
        return Box.objects.get(id=self.kwargs['box_id'])

What I wanted to ask was, Is this best practice, or can the way I am checking permissions be improved?
I came up with this on my own, so I don't know if I am right or wrong. Should the box attribute be present on every view,
or is there any alternative to it?

Please let me know!
Thanks a lot!

[aryaniyaps]

@tomchristie can prbac permissions-checking be documented?
Or any tips on what we can do to implement the same? I think that this has to be done
because the prbac access system is popular indeed. Many applications would be using it.

Thanks in advance!

[tomchristie]

Hiya,

I don't personally have the time to respond in depth one-to-one on every discussion. If you think it'd be popular, then a good way to find out for sure is to build it out as a third party package, and then submit a pull request adding a link to it from the docs, alongside these other third party permissions packages... https://www.django-rest-framework.org/api-guide/permissions/#third-party-packages