After installation <installation>
we can prepare our project for object permissions handling. In a settings module we need to add guardian to INSTALLED_APPS
:
INSTALLED_APPS = (
# ...
'guardian',
)
and hook guardian's authentication backend:
AUTHENTICATION_BACKENDS = (
'django.contrib.auth.backends.ModelBackend', # this is default
'guardian.backends.ObjectPermissionBackend',
)
Note
Once project is configured to work with django-guardian
, calling syncdb
management command would create User
instance for anonymous user support (with name of AnonymousUser
).
Note
The Guardian anonymous user is different to the Django Anonymous user. The Django Anonymous user does not have an entry in the database, however the Guardian anonymous user does. This means that the following code will return an unexpected result:
from guardian.compat import get_user_model
User = get_user_model()
anon = User.get_anonymous()
anon.is_anonymous() # returns False
We can change id to whatever we like. Project should be now ready to use object permissions.
Guardian has following, optional configuration variables:
GUARDIAN_RAISE_403
1.0.4
If set to True
, guardian would raise django.core.exceptions.PermissionDenied
error instead of returning empty django.http.HttpResponseForbidden
.
Warning
Remember that you cannot use both GUARDIAN_RENDER_403
AND GUARDIAN_RAISE_403
- if both are set to True
, django.core.exceptions.ImproperlyConfigured
would be raised.
GUARDIAN_RENDER_403
1.0.4
If set to True
, guardian would try to render 403 response rather than return contentless django.http.HttpResponseForbidden
. Would use template pointed by GUARDIAN_TEMPLATE_403
to do that. Default is False
.
Warning
Remember that you cannot use both GUARDIAN_RENDER_403
AND GUARDIAN_RAISE_403
- if both are set to True
, django.core.exceptions.ImproperlyConfigured
would be raised.
GUARDIAN_TEMPLATE_403
1.0.4
Tells parts of guardian what template to use for responses with status code 403
(i.e. api-decorators-permission_required
). Defaults to 403.html
.
ANONYMOUS_USER_NAME
1.4.2
This is the username of the anonymous user. Used to create the anonymous user and subsequently fetch the anonymous user as required.
If ANONYMOUS_USER_NAME
is set to None
, anonymous user object permissions-are disabled. You may need to choose this option if creating an User
object-to represent anonymous users would be problematic in your environment.
Defaults to "AnonymousUser"
.
GUARDIAN_GET_INIT_ANONYMOUS_USER
1.2
Guardian supports object level permissions for anonymous users, however when in our project we use custom User model, default function might fail. This can lead to issues as guardian
tries to create anonymous user after each syncdb
call. Object that is going to be created is retrieved using function pointed by this setting. Once retrieved, save
method would be called on that instance.
Defaults to "guardian.management.get_init_anonymous_user"
.
custom-user-model-anonymous