Authorization library for Django
Project description
django-cancan
django-cancan
is an authorization library for Django. It works on top of default Django permissions and allows to restrict the resources (models and objects) a given user can access.
This library is inspired by cancancan for Ruby on Rails.
Key features
-
All of your permissions logic is kept in one place. User permissions are defined in a single function and not scattered across views, querysets, etc.
-
Same permissions logic is used to check permissions on a single model instance and to generate queryset containing all instances that the user can access
-
Easy unit testing
-
Integration with built-in Django default permissions system and Django admin (coming soon)
-
Intergration with Django Rest Framework (coming soon)
How to install
Using pip
:
pip install django-cancan
Quick start
- Add
cancan
to yourINSTALLED_APPS
setting like this:
INSTALLED_APPS = [
...,
'cancan',
]
- Create a function that define the access rules for a given user. For example, create
abilities.py
inmyapp
module:
def define_access_rules(user, rules):
# Anybody can view published articles
rules.allow('view', Article, published=True)
if not user.is_authenticated:
return
# Allow logged in user to view his own articles, regardless of the `published` status
rules.allow('view', Article, author=user)
if user.has_perm('article.view_unpublished'):
# You can also check for custom model permissions (i.e. view_unpublished)
rules.allow('view', Article, published=False)
if user.is_superuser:
# Superuser gets unlimited access to all articles
rules.allow('add', Article)
rules.allow('view', Article)
rules.allow('change', Article)
rules.allow('delete', Article)
- In
settings.py
addCANCAN
section, so thatcancan
library will know where to search fordefine_access_rules
function from the previous step:
CANCAN = {
'ABILITIES': 'myapp.abilities.define_access_rules'
}
The define_access_rules
function will be executed automatically per each request by the cancan
middleware. The middleware will call the function to determine the abilities of a current user.
Let's add cancan
middleware, just after AuthenticationMiddleware
:
MIDDLEWARE = [
...
'django.contrib.auth.middleware.AuthenticationMiddleware',
'cancan.middleware.CanCanMiddleware',
...
]
By adding the middleware you will also get an access to request.ability
instance which you can use
to:
- check model permissions,
- check object permissions,
- generate model querysets (i.e. in case of
ListView
s
- Check for abilities in views:
class ArticleListView(ListView):
model = Article
def get_queryset():
# this is how you can retrieve all objects that current user can access
qs = self.request.ability.queryset_for('view', Article)
return qs
class ArticleDetailView(PermissionRequiredMixin, DetailView):
queryset = Article.objects.all()
def has_permission(self):
article = self.get_object()
# this is how you can check if user can access an object
return self.request.ability.can('view', article)
- Check for abilities in templates
You can also check for abilities in template files, i. e. to show/hide/disable buttons or links.
First you need to add cancan
processor to context_processors
in TEMPLATES
section of settings.py
:
TEMPLATES = [
{
...,
"OPTIONS": {
"context_processors": [
...,
"cancan.context_processors.abilities",
],
},
},
]
This will give you access to ability
object in a template. You also need add {% load cancan_tags %}
at the beginning
of the template file.
Next you can check for object permissions:
{% if ability|can:"change"|subject:article %}
<a href="{% url 'article_edit' pk=article.id %}">Edit article</a>
{% endif %}
or model permissions:
{% load cancan_tags %}
...
{% if ability|can:"add"|"myapp.Article" %}
<a href="{% url 'article_new' %}">Create new article</a>
{% endif %}
You can also use can
template tag to create a reusable variable:
{% can "add" "core.Project" as can_add_project %}
...
{% if can_add_project %}
...
{% endif %}
Checking for abilities in Django Rest Framework
Let's start by creating a pemission class:
from rest_framework import permissions
def set_aliases_for_drf_actions(ability):
"""
map DRF actions to default Django permissions
"""
ability.access_rules.set_alias("list", "view")
ability.access_rules.set_alias("retrieve", "view")
ability.access_rules.set_alias("create", "add")
ability.access_rules.set_alias("update", "change")
ability.access_rules.set_alias("partial_update", "change")
ability.access_rules.set_alias("destroy", "delete")
class AbilityPermission(permissions.BasePermission):
def has_permission(self, request, view=None):
ability = request.ability
set_aliases_for_drf_actions(ability)
return ability.can(view.action, view.get_queryset().model)
def has_object_permission(self, request, view, obj):
ability = request.ability
set_aliases_for_drf_actions(ability)
return ability.can(view.action, obj)
Next, secure the ViewSet with AbilityPermission
and override get_queryset
method to list objects based on the access rights.
class ArticleViewset(ModelViewSet):
permission_classes = [AbilityPermission]
def get_queryset(self):
return self.request.ability.queryset_for(self.action, Article).distinct()
Sponsors
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_cancan-0.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | aa64cc7652402ed22b5bd68d023209106e51a4426f651710d98f2f582d5da814 |
|
MD5 | 9993594d1a9d8077de1a6113c3959024 |
|
BLAKE2b-256 | 758f205ae7f5e873c19c72c2487a4a73aed7bab5cf71b0d60467c05ef3e67a79 |