Authorization

Authorization is the component needed to verify what someone can do with the resources within an API.

Authorization answers the question “Is permission granted for this user to take this action?” This usually involves checking permissions such as Create/Read/Update/Delete access, or putting limits on what data the user can access.

Usage

Using these classes is simple. Simply provide them (or your own class) as a Meta option to the Resource in question. For example:

from django.contrib.auth.models import User
from tastypie.authorization import DjangoAuthorization
from tastypie.resources import ModelResource


class UserResource(ModelResource):
    class Meta:
        queryset = User.objects.all()
        resource_name = 'auth/user'
        excludes = ['email', 'password', 'is_superuser']
        # Add it here.
        authorization = DjangoAuthorization()

Authorization Options

Tastypie ships with the following Authorization classes:

Authorization

The no-op authorization option, no permissions checks are performed.

Warning

This is a potentially dangerous option, as it means ANY recognized user can modify ANY data they encounter in the API. Be careful who you trust.

ReadOnlyAuthorization

This authorization class only permits reading data, regardless of what the Resource might think is allowed. This is the default Authorization class and the safe option.

DjangoAuthorization

The most advanced form of authorization, this checks the permission a user has granted to them (via django.contrib.auth.models.Permission). In conjunction with the admin, this is a very effective means of control.

The Authorization API

An Authorization-compatible class implements the following methods:

  • read_list
  • read_detail
  • create_list
  • create_detail
  • update_list
  • update_detail
  • delete_list
  • delete_detail

Each method takes two parameters, object_list & bundle.

object_list is the collection of objects being processed as part of the request. FILTERING & other restrictions to the set will have already been applied prior to this call.

bundle is the populated Bundle object for the request. You’ll likely frequently be accessing bundle.request.user, though raw access to the data can be helpful.

What you return from the method varies based on the type of method.

Return Values: The List Case

In the case of the *_list methods, you’ll want to filter the object_list & return only the objects the user has access to.

Returning an empty list simply won’t allow the action to be applied to any objects. However, they will not get a HTTP error status code.

If you’d rather they received an unauthorized status code, raising Unauthorized will return a HTTP 401.

Return Values: The Detail Case

In the case of the *_detail methods, you’ll have access to the object_list (so you know if a given object fits within the overall set), BUT you’ll want to be inspecting bundle.obj & either returning True if they should be allowed to continue or raising the Unauthorized exception if not.

Raising Unauthorized will cause a HTTP 401 error status code in the response.

Implementing Your Own Authorization

Implementing your own Authorization classes is a relatively simple process. Anything that is API-compatible is acceptable, only the method names matter to Tastypie.

An example implementation of a user only being able to “their” objects might look like:

from tastypie.authorization import Authorization
from tastypie.exceptions import Unauthorized


class UserObjectsOnlyAuthorization(Authorization):
    def read_list(self, object_list, bundle):
        # This assumes a ``QuerySet`` from ``ModelResource``.
        return object_list.filter(user=bundle.request.user)

    def read_detail(self, object_list, bundle):
        # Is the requested object owned by the user?
        return bundle.obj.user == bundle.request.user

    def create_list(self, object_list, bundle):
        # Assuming their auto-assigned to ``user``.
        return object_list

    def create_detail(self, object_list, bundle):
        return bundle.obj.user == bundle.request.user

    def update_list(self, object_list, bundle):
        allowed = []

        # Since they may not all be saved, iterate over them.
        for obj in object_list:
            if obj.user == bundle.request.user:
                allowed.append(obj)

        return allowed

    def update_detail(self, object_list, bundle):
        return bundle.obj.user == bundle.request.user

    def delete_list(self, object_list, bundle):
        # Sorry user, no deletes for you!
        raise Unauthorized("Sorry, no deletes.")

    def delete_detail(self, object_list, bundle):
        raise Unauthorized("Sorry, no deletes.")