django-lockdown 4.0.0

Lock down a Django site or individual views, with configurable preview authorization

django-lockdown is a reusable Django application for locking down an entire site (or particular views), with customizable date ranges and preview authorization.

Installation

Install from PyPI with easy_install or pip:

pip install django-lockdown

To use django-lockdown in your Django project:

1. Add 'lockdown' to your INSTALLED_APPS. If you want to use one of django-lockdowns default lock down forms, you’ll additionally have to ensure that you have enabled django.contrib.auth as part of to your INSTALLED_APPS.

2. 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.

3. 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.

Dependencies

django-lockdown requires Python 3.6 or later and Django 2.2 or later.

As an alternative to CPython PyPy 3.5 and 3.6 are supported as well.

Usage

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:

form

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.

until_date

The date to use rather than the date provided by LOCKDOWN_UNTIL.

after_date

The date to use rather than the date provided by LOCKDOWN_AFTER.

logout_key

A preview logout key to use, rather than the one provided by LOCKDOWN_LOGOUT_KEY.

session_key

The session key to use, rather than the one provided by LOCKDOWN_SESSION_KEY.

url_exceptions

A list of regular expressions for which matching urls can bypass the lockdown (rather than using those defined in LOCKDOWN_URL_EXCEPTIONS).

remote_addr_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).

extra_context

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:

passwords

A tuple of passwords to use, rather than the ones provided by LOCKDOWN_PASSWORDS.

Settings

LOCKDOWN_ENABLED

An optional boolean value that, if set to False, disables django-lockdown globally. Defaults to True (lock down enabled).

LOCKDOWN_PASSWORDS

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.

LOCKDOWN_URL_EXCEPTIONS

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
)

LOCKDOWN_VIEW_EXCEPTIONS

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.

For example:

from yourapp import one_view_to_unlock, another_view_to_unlock

LOCKDOWN_VIEW_EXCEPTIONS = [
    one_view_to_unlock,
    another_view_to_unlock
]

LOCKDOWN_REMOTE_ADDR_EXCEPTIONS

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',
]

LOCKDOWN_TRUSTED_PROXIES

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.

For example:

LOCKDOWN_TRUSTED_PROXIES = [
    '172.17.0.1',
]

LOCKDOWN_REMOTE_ADDR_EXCEPTIONS = [
    '172.17.0.5',
]

LOCKDOWN_UNTIL

Used to lock the site down up until a certain date. Set to a datetime.datetime object.

If neither LOCKDOWN_UNTIL nor LOCKDOWN_AFTER is provided (the default), the site or views will always be locked.

LOCKDOWN_AFTER

Used to lock the site down after a certain date. Set to a datetime.datetime object.

See also: LOCKDOWN_UNTIL.

LOCKDOWN_LOGOUT_KEY

A key which, if provided in the query string of a locked URL, will log out the user from the preview.

LOCKDOWN_FORM

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 lockdown decorator):

staff_only

Only allow staff members to preview. Defaults to True (but the default can be provided as a LOCKDOWN_AUTHFORM_STAFF_ONLY setting).

superusers_only

Only allow superusers to preview. Defaults to False (but the default can be provided as a LOCKDOWN_AUTHFORM_SUPERUSERS_ONLY setting).

LOCKDOWN_AUTHFORM_STAFF_ONLY

If using 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.

LOCKDOWN_AUTHFORM_SUPERUSERS_ONLY

If using lockdown.forms.AuthForm and this setting is True, only superusers will be allowed to preview (False by default). Has no effect if not using lockdown.forms.AuthForm.

LOCKDOWN_SESSION_KEY

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). LOCKDOWN_SESSION_KEY defines the session key used; the default is 'lockdown-allow'.

Templates

django-lockdown uses a single template, lockdown/form.html. The 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 django-lockdown.

In your overwritten template the lockdown preview form is available in the template context as form.

CHANGES

4.0.0 (2021-02-14)

• Remove support for end-of-life Django versions (1.11, 2.0 and 2.1).

• Add support for Python 3.9 and remove support for Python 3.5.

• Add support for Django 3.1.

3.0.0. (2020-01-01)

• Added support for Python 3.8.

• Added support for Django 3.0.

• Removed support for Python 2.7 and 3.4.

2.0.0 (2019-05-26)

• Added support for proxies when using IP-address based lockdown exceptions.

• This introduces a breaking change: Installations running behind a proxy will need to set the newly introduced LOCKDOWN_TRUSTED_PROXIES, otherwise access won’t be granted anymore, when accessing the site through a proxy.

• Added the ability to whitelist views when locking down a whole site using the middleware.

• Added support for Django 2.2.

• Only require mock as separate third-party test dependency for Python <3.3.

• Fix detection of compacted IP-addresses.

• This introduces a breaking change for users which make use of the REMOTE_ADDR_EXCEPTIONS feature and passed the IP-addresses to except as byte strings in the configuration. While it’s unlikely somebody did that with Python 3, it’s the default for Python 2. With this version, byte strings don’t work anymore, but using unicode strings is required.

• Add the ability to specify IP-subnets for remote addresses exception.

1.6.0 (2018-11-25)

• Drops support for Django <=1.10.

• Drops support for Python 3.3.

• Add the ability to bypass the lockdown for configured IP-addresses.

• Integrate pre-commit for code style checks during commit and CI.

• Added support for Django 2.1.

• Add support for Python 3.7.

• Add support for PyPy.

1.5.0 (2017-12-05)

• Add support for Django 2.0

• Improve the code style in some areas

1.4.2 (2017-04-07)

• Fix formatting for PyPi

1.4.1 (2017-04-07)

• Fix problem with upload for PyPi

1.4.0 (2017-04-06)

• Refactor tests to use Mocks

• Add support for Python 3.6

• Add support for Django 1.11

1.3 (2016-08-07)

• Adds support for Django 1.10.

• Adds support for providing additional context data to the lockdown template.

1.2 (2015-12-03)

• Adds support for Python 3.5.

• Adds support for Django 1.9.

• Drops support for Django <=1.7.

• Fixes not working URL exceptions when specifying them in the decorator arguments.

• Improves tests.

1.1 (2015-04-06)

• Proper new version after 0.1.2 and 0.1.3 have been tagged after the release of 1.0. Contains all new features of 0.1.2 and 0.1.3, most notably support for Python 3.

• Last version of django-lockdown with support for Django 1.3, 1.5 and 1.6. Upcoming versions will only support Django versions with official security support. For the time being these are Django 1.4 LTS, 1.7 and 1.8 LTS.

• Fixes testing for Django >=1.7

0.1.3 (2014-03-15) (never released)

• Added LOCKDOWN_ENABLED setting.

• Removed Django 1.1 backport of decorator_from_middleware_with_args.

0.1.2 (2014-03-15) (never released)

• Require at least Django 1.3.

• Fixed the test runner script to work with recent Django versions.

• Added the csrf_token template tag to the included form template.

• Minor syntax adjustments for Python 3 compatibility.

1.0 (2013-07-10)

• BACKWARDS INCOMPATIBLE: Allow multiple passwords (the passwords setting has changed from LOCKDOWN_PASSWORD to LOCKDOWN_PASSWORDS).

• Decorator changed to a callable decorator (so settings can be overridden for an individual decorator).

• Add AuthForm which can be used to allow previewing from authenticated users (via django.contrib.auth).

• Allow locking up until or only after certain dates.

0.1.1 (2009-11-24)

• Fix setup.py so tests package is not installed.

0.1 (2009-11-16)

• Initial release.