From 5970baa20112921217ae4f2c2a9f175df25922db Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 10 Sep 2013 21:00:13 +0100 Subject: Tweaks and docs to object-level model permissions. --- docs/api-guide/filtering.md | 46 +++++++++++++++++++++++++++++++++++++++++++ docs/api-guide/permissions.md | 18 ++++++++++++++++- 2 files changed, 63 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 649462da..859e8d52 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -257,6 +257,49 @@ The `ordering` attribute may be either a string or a list/tuple of strings. --- +## DjangoObjectPermissionsFilter + +The `DjangoObjectPermissionsFilter` is intended to be used together with the [`django-guardian`][guardian] package, with custom `'view'` permissions added. The filter will ensure that querysets only returns objects for which the user has the appropriate view permission. + +This filter class must be used with views that provide either a `queryset` or a `model` attribute. + +If you're using `DjangoObjectPermissionsFilter`, you'll probably also want to add an appropriate object permissions class, to ensure that users can only operate on instances if they have the appropriate object permissions. The easiest way to do this is to subclass `DjangoObjectPermissions` and add `'view'` permissions to the `perms_map` attribute. + +A complete example using both `DjangoObjectPermissionsFilter` and `DjangoObjectPermissions` might look something like this. + +**permissions.py**: + + class CustomObjectPermissions(permissions.DjangoObjectPermissions): + """ + Similar to `DjangoObjectPermissions`, but adding 'view' permissions. + """ + perms_map = { + 'GET': ['%(app_label)s.view_%(model_name)s'], + 'OPTIONS': ['%(app_label)s.view_%(model_name)s'], + 'HEAD': ['%(app_label)s.view_%(model_name)s'], + 'POST': ['%(app_label)s.add_%(model_name)s'], + 'PUT': ['%(app_label)s.change_%(model_name)s'], + 'PATCH': ['%(app_label)s.change_%(model_name)s'], + 'DELETE': ['%(app_label)s.delete_%(model_name)s'], + } + +**views.py**: + + class EventViewSet(viewsets.ModelViewSet): + """ + Viewset that only lists events if user has 'view' permissions, and only + allows operations on individual events if user has appropriate 'view', 'add', + 'change' or 'delete' permissions. + """ + queryset = Event.objects.all() + serializer = EventSerializer + filter_backends = (filters.DjangoObjectPermissionsFilter,) + permission_classes = (myapp.permissions.CustomObjectPermissions,) + +For more information on adding `'view'` permissions for models, see the [relevant section][view-permissions] of the `django-guardian` documentation, and [this blogpost][view-permissions-blogpost]. + +--- + # Custom generic filtering You can also provide your own generic filtering backend, or write an installable app for other developers to use. @@ -281,5 +324,8 @@ We could achieve the same behavior by overriding `get_queryset()` on the views, [cite]: https://docs.djangoproject.com/en/dev/topics/db/queries/#retrieving-specific-objects-with-filters [django-filter]: https://github.com/alex/django-filter [django-filter-docs]: https://django-filter.readthedocs.org/en/latest/index.html +[guardian]: http://pythonhosted.org/django-guardian/ +[view-permissions]: http://pythonhosted.org/django-guardian/userguide/assign.html +[view-permissions-blogpost]: http://blog.nyaruka.com/adding-a-view-permission-to-django-models [nullbooleanselect]: https://github.com/django/django/blob/master/django/forms/widgets.py [search-django-admin]: https://docs.djangoproject.com/en/dev/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index a7bf1555..871de84e 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -120,7 +120,21 @@ To use custom model permissions, override `DjangoModelPermissions` and set the ` ## DjangoModelPermissionsOrAnonReadOnly -Similar to `DjangoModelPermissions`, but also allows unauthenticated users to have read-only access to the API. +Similar to `DjangoModelPermissions`, but also allows unauthenticated users to have read-only access to the API. + +## DjangoObjectPermissions + +This permission class ties into Django's standard [object permissions framework][objectpermissions] that allows per-object permissions on models. In order to use this permission class, you'll also need to add a permission backend that supports object-level permissions, such as [django-guardian][guardian]. + +When applied to a view that has a `.model` property, authorization will only be granted if the user *is authenticated* and has the *relevant per-object permissions* and *relevant model permissions* assigned. + +* `POST` requests require the user to have the `add` permission on the model instance. +* `PUT` and `PATCH` requests require the user to have the `change` permission on the model instance. +* `DELETE` requests require the user to have the `delete` permission on the model instance. + +Note that `DjangoObjectPermissions` **does not** require the `django-guardian` package, and should support other object-level backends equally well. + +As with `DjangoModelPermissions` you can use custom model permissions by overriding `DjangoModelPermissions` and setting the `.perms_map` property. Refer to the source code for details. Note that if you add a custom `view` permission for `GET`, `HEAD` and `OPTIONS` requests, you'll probably also want to consider adding the `DjangoObjectPermissionsFilter` class to ensure that list endpoints only return results including objects for which the user has appropriate view permissions. ## TokenHasReadWriteScope @@ -220,7 +234,9 @@ The [Composed Permissions][composed-permissions] package provides a simple way t [authentication]: authentication.md [throttling]: throttling.md [contribauth]: https://docs.djangoproject.com/en/1.0/topics/auth/#permissions +[objectpermissions]: https://docs.djangoproject.com/en/dev/topics/auth/customizing/#handling-object-permissions [guardian]: https://github.com/lukaszb/django-guardian +[get_objects_for_user]: http://pythonhosted.org/django-guardian/api/guardian.shortcuts.html#get-objects-for-user [django-oauth-plus]: http://code.larlet.fr/django-oauth-plus [django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider [2.2-announcement]: ../topics/2.2-announcement.md -- cgit v1.2.3 From 2a6a2013df4fcb8e09425e9fa758b91b3a23b751 Mon Sep 17 00:00:00 2001 From: Diego Ponciano Date: Wed, 11 Sep 2013 17:25:57 -0300 Subject: small typo correction on ViewSet example code --- docs/api-guide/viewsets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 2e65b7a4..1062cb32 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -23,7 +23,7 @@ Let's define a simple viewset that can be used to list or retrieve all the users from django.shortcuts import get_object_or_404 from myapps.serializers import UserSerializer from rest_framework import viewsets - from rest_framewor.responses import Response + from rest_framework.response import Response class UserViewSet(viewsets.ViewSet): """ -- cgit v1.2.3 From 895beb89c60cea534f85b8a7749615755c4d43b5 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 12 Sep 2013 21:41:21 +0100 Subject: Note on '.model' as default only, with 'serializer_class', and 'queryset' attributes prefered. Closes #1100 --- docs/api-guide/generic-views.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 7185b6b6..dc0076df 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -69,7 +69,7 @@ The following attributes control the basic view behavior. **Shortcuts**: -* `model` - This shortcut may be used instead of setting either (or both) of the `queryset`/`serializer_class` attributes, although using the explicit style is generally preferred. If used instead of `serializer_class`, then then `DEFAULT_MODEL_SERIALIZER_CLASS` setting will determine the base serializer class. +* `model` - This shortcut may be used instead of setting either (or both) of the `queryset`/`serializer_class` attributes, although using the explicit style is generally preferred. If used instead of `serializer_class`, then then `DEFAULT_MODEL_SERIALIZER_CLASS` setting will determine the base serializer class. Note that `model` is only ever used for generating a default queryset or serializer class - the `queryset` and `serializer_class` attributes are always preferred if provided. **Pagination**: -- cgit v1.2.3