Package: drf-triad-permissions
Django Rest Framework permissions are a powerful tool for limiting user access to views and viewsets.
However, it’s not always easy or clean to set up a comprehensive permission system that can depend on multiple factors,
such as the user coming in the request, the parameters of the matched URL, or the specificities of the object being
requested by the client.drf-triad-permissionsis one of the many approaches for configuring permissions in medium to large scale projects,
with elegance and reusability in mind. It bases the permission system on string triads that can be used both as
permission statements as well as permission expectations.TriadsTriads are strings that can be split in three parts, usuallyresource::object::action. The substring::acts
as separator of the parts. Each level can be attached any meaning, but the original intention is to consider that
the first level represents a resource, the second an object, and the third level an action.For instance, the triadpolls::all::readcan be read as “user has access to read all polls”. Another example:payment::owner:4368::reversecan be read as “user has access to reverse payments that match ‘owner:4368’”. The
‘owner:4368’ part can have any meaning, in this context, it could signify that 4368 is a user ID, whereas owner means
that the payment is owned by that specific user.Triads as statementsTriads can be used as statements for specifying which permissions a user has. For instance, a user can have this set of
triads attached to their permissions:payments::all::read
payments::from:john@doe.com::all
payments::year:2020::reviewThis means that the user can read all payments, do anything with payments from john at doe.com (hopefully himself) and
review all payments from year 2020.Triads as expectationsThe true power of triads come when they are used to define expectations. Suppose we have a DRFModelViewSetthat
controls the payments. In a model viewset, it’s expected that users can “list”, “create”, “update” and “delete” items.
Additional actions can be defined, such as “review”. In this case, this set of triads could be used as expectation:payments::all::{action}
payments::from:{obj.author.email}::{action}
payments::year:{url.year}::{action}Expectation triads are assumed to be disjunctive. That is, a user would only need to match ONE of those to be allowed
to perform the action they are intending.Notice the use of placeholders. Here, triads are relying on certain elements to be interpolated at the actual time of
checking. Placeholders will depend on the payment object being requested (obj) and on the year parameter of the URL
that matched the current viewset (url). Theactionplaceholder will be converted to the action provided by DRF
viewsets, such aslist,update,partial-updateordelete.Let’s suppose a user with the triad statements we saw before attempts to do a PUT request against the (fake) URLhttps://my.domain.com/api/payments-from/2019/10802/. This URL is handled byPaymentsViewSetwhose expectations are
defined in the set of triads we just saw. Since this is a PUT request against a detail endpoint, it’s going to get
handled as an “update” action. Let’s just assume that the payment 10802 of year 2019 hasauthor.emailequal to
john at doe.com. When DRF’s permission machinery checks the permissions of the requesting user against the expected
statements, these are the concrete checks that will be used to test against the user:payments::all::update
payments::from:john@doe.com::update
payments::year:2019::updateAnd let’s say that the expectationpayments::from:john@doe.com::updatewill match with the permissionpayments::from:john@doe.com::all.Triad matchingTriad matching is done by level, with some simplistic rules.Two identical strings always match.The stringsalland*will match with anything.The stringreadwill match withhead,options,get,listandretrieve.The stringwritewill match withpost,put,patch,delete,create,update,partial-updateanddestroy.It’s important to note that matching does not occurr in both directions. If the viewset is expectinglistand the
user hasallthe matching succeeds, but the opposite will not.So, in the example:user permission     -> payments::from:john@doe.com::all
viewset expectation -> payments::from:john@doe.com::updateThe first and second level will match by rule 1, and the third level will match by rule 2.PoliciesTriads can be grouped in policies for easy reutilization. This package comes with a pre-defined basic policy:classBasicPolicy(Policy):default=["{resource}::all::{action}","{resource}::new::create","{resource}::id:{obj.id}::{action}",]This policy has the following meaning:User must have permission to perform the action on all objects.User must have permission to create a new resource (newacts as syntactic sugar here, remember that there is no
implicit meaning attached to each level).User must have permission to perform the action on the specific object, matching by id.Policies can be used as DRF viewset permissions like this:classPaymentsViewSet(ModelViewSet):queryset=Payment.objects.all()serializer=PaymentSerializerpermission_classes=BasicPolicy.expand()Policies are the recommended way of using triad permissions. However, if you need to create a permission class on the
fly, you can usedrf_triad_permissions.permissions.get_triad_permission. This function has the same parameters than
the policy class variables, which will be explained in the next section.ParametersPolicies can be created with the following class variables:default,read,write, plus all HTTP verbs in
lower case (e.g.post,get), plus all viewset actions in lower case (e.g.retrieve,partial_update,review). Each class variable accepts a list of triads that will be evaluated disjunctively, that is, with OR.
For instance, a read-only policy can be created with:fromdrf_triad_permissionsimportPolicyclassReadOnlyPolicy(Policy):read=["{resource}::all::{action}","{resource}::id:{obj.id}::{action}",]write=[]Notice how thewriteparameter needs to be explicitly stated as an empty list.In the absence of any specific parameter,defaultwill be always used, which defaults to an empty list.This example of read-only policy can also be created on the fly by calling:fromdrf_triad_permissionsimportget_triad_permissionget_triad_permission(read=["{resource}::all::{action}","{resource}::id:{obj.id}::{action}",],write=[],)As final example, if you wanted to limit the basic policy to exclude deletions, you would do this:fromdrf_triad_permissionsimportBasicPolicyclassBasicPolicyWithNoDeletions(BasicPolicy):destroy=[]ContributingJoin the discussion athttps://gitter.im/drf-triad-permissions/community.PRs are welcome! If you have questions or comments, please use the link above.To run the test suite runmakeormake coverage. The tests for this project live inside a small django
project calledtriads_sandbox.