django-lockdown is a reusable Django application for locking down an entire
site (or particular views), with customizable date ranges and preview
Install from PyPI with
pip install django-lockdown
django-lockdown in your Django project:
INSTALLED_APPS. If you want to use one of
django-lockdownsdefault lock down forms, you'll additionally have to ensure that you have enabled
django.contrib.authas part of to your
- To enable admin preview of locked-down sites or views with passwords, set the LOCKDOWN_PASSWORDS setting to a tuple of one or more plain-text passwords.
- Protect the entire site by using middleware, or protect individual views by applying a decorator to them.
For more advanced customization of admin preview authorization, see the LOCKDOWN_FORM setting.
As an alternative to CPython PyPy 3.5 and 3.6 are supported as well.
Using the middleware
To lock down the entire site, add the lockdown middleware to your middlewares:
MIDDLEWARE = [ # ... 'lockdown.middleware.LockdownMiddleware', ]
Optionally, you may also add URL regular expressions to a LOCKDOWN_URL_EXCEPTIONS setting.
Using the decorator
Import the decorator:
from lockdown.decorators import lockdown
Apply the decorator to individual views you want to protect. For example:
@lockdown() def secret_page(request): # ...
The decorator accepts seven arguments:
- The form to use for providing an admin preview, rather than the form referenced by LOCKDOWN_FORM. Note that this must be an actual form class, not a module reference like the setting.
- The date to use rather than the date provided by LOCKDOWN_UNTIL.
- The date to use rather than the date provided by LOCKDOWN_AFTER.
- A preview logout key to use, rather than the one provided by LOCKDOWN_LOGOUT_KEY.
- The session key to use, rather than the one provided by LOCKDOWN_SESSION_KEY.
- A list of regular expressions for which matching urls can bypass the lockdown (rather than using those defined in LOCKDOWN_URL_EXCEPTIONS).
- A list of IP-addresses or IP-subnets for which matching URLs can bypass the lockdown (rather than using those defined in LOCKDOWN_REMOTE_ADDR_EXCEPTIONS).
- A dictionary of context data that will be added to the default context data passed to the template.
Any further keyword arguments are passed to the admin preview form. The default form accepts one argument:
- A tuple of passwords to use, rather than the ones provided by LOCKDOWN_PASSWORDS.
An optional boolean value that, if set to False, disables
django-lockdown globally. Defaults to True (lock down enabled).
One or more plain-text passwords which allow the previewing of the site or views protected by django-lockdown:
LOCKDOWN_PASSWORDS = ('letmein', 'beta')
If this setting is not provided (and the default LOCKDOWN_FORM is being used), there will be no admin preview for locked-down pages.
If a LOCKDOWN_FORM other than the default is used, this setting has no effect.
An optional list/tuple of regular expressions to be matched against incoming URLs. If a URL matches a regular expression in this list, it will not be locked. For example:
LOCKDOWN_URL_EXCEPTIONS = ( r'^/about/$', # unlock /about/ r'\.json$', # unlock JSON API )
An optional list of regular expressions to be matched against the resolved views of incoming requests. If the URL of an incoming request resolves to one of the views in the list, it will not be locked. That's useful if you want to lock down a whole site using the middleware, but want to whitelist some localized URLs.
from yourapp import one_view_to_unlock, another_view_to_unlock LOCKDOWN_VIEW_EXCEPTIONS = [ one_view_to_unlock, another_view_to_unlock ]
An optional list of IP-addresses or IP-subnets to be matched against the requesting IP-address (from requests.META['REMOTE_ADDR']). If the requesting IP-address is in this list, it will not be locked. For example:
LOCKDOWN_REMOTE_ADDR_EXCEPTIONS = [ '127.0.0.1', '::1', ]
A list of trusted proxy IP-addresses to be used in conjunction with LOCKDOWN_REMOTE_ADDR_EXCEPTIONS when a reverse-proxy or load balancer is used. If the requesting IP address is from the trusted proxies list the last address from the X-Forwared-For header (from requests.META['HTTP_X_FORWARDED_FOR']) will be checked against LOCKDOWN_REMOTE_ADDR_EXCEPTIONS and locked or unlocked accordingly.
LOCKDOWN_TRUSTED_PROXIES = [ '172.17.0.1', ] LOCKDOWN_REMOTE_ADDR_EXCEPTIONS = [ '172.17.0.5', ]
Used to lock the site down up until a certain date. Set to a
LOCKDOWN_UNTIL nor LOCKDOWN_AFTER is provided (the default),
the site or views will always be locked.
Used to lock the site down after a certain date. Set to a
See also: LOCKDOWN_UNTIL.
A key which, if provided in the query string of a locked URL, will log out the user from the preview.
The default lockdown form allows admin preview by entering a preset
plain-text password (checked, by default, against the LOCKDOWN_PASSWORDS
setting). To set up more advanced methods of authenticating access to
locked-down pages, set
LOCKDOWN_FORM to the Python dotted path to a Django
Form subclass. This form will be displayed on the lockout page. If the form
validates when submitted, the user will be allowed access to locked pages:
LOCKDOWN_FORM = 'path.to.my.CustomLockdownForm'
A form for authenticating against
django.contrib.auth users is provided
with django-lockdown (use
LOCKDOWN_FORM = 'lockdown.forms.AuthForm'). It
accepts two keyword arguments (in the
- Only allow staff members to preview. Defaults to
True(but the default can be provided as a LOCKDOWN_AUTHFORM_STAFF_ONLY setting).
- Only allow superusers to preview. Defaults to
False(but the default can be provided as a LOCKDOWN_AUTHFORM_SUPERUSERS_ONLY setting).
lockdown.forms.AuthForm and this setting is
True, only staff
users will be allowed to preview (True by default).
Has no effect if not using
lockdown.forms.AuthForm and this setting is
superusers will be allowed to preview (False by default). Has no effect if not
Once a client is authorized for admin preview, they will continue to
be authorized for the remainder of their browsing session (using
Django's built-in session support).
the session key used; the default is
django-lockdown uses a single template,
default template displays a simple "coming soon" message and the
preview authorization form, if a password via LOCKDOWN_PASSWORDS is set.
If you want to use a different template, you can use Djangos template
loaders to specify a path inside your project to search for templates,
before searching for templates included in
In your overwritten template the lockdown preview form is available in the
template context as