Configuration¶
After 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',
)
As django-guardian
supports anonymous user’s object permissions we also
need to add following to our settings module:
ANONYMOUS_USER_ID = -1
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
).
If ANONYMOUS_USER_ID
is set to None
, anonymous user object permissions
are disabled. You may need to choose this option if creating a User
object
to represent anonymous users would be problematic in your environment.
We can change id to whatever we like. Project should be now ready to use object permissions.
Optional settings¶
In addition to required ANONYMOUS_USER_ID
setting, guardian has following,
optional configuration variables:
GUARDIAN_RAISE_403¶
New in version 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¶
New in version 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¶
New in version 1.0.4.
Tells parts of guardian what template to use for responses with status code
403
(i.e. permission_required). Defaults to
403.html
.
ANONYMOUS_DEFAULT_USERNAME_VALUE¶
New in version 1.1.
Due to changes introduced by Django 1.5 user model can have differently named
username
field (it can be removed too, but guardian
currently depends
on it). After syncdb
command we create anonymous user for convenience,
however it might be necessary to set this configuration in order to set proper
value at username
field.
GUARDIAN_GET_INIT_ANONYMOUS_USER¶
New in version 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"
.
See also