django-basic-auth-ip-whitelist
==============================
.. image:: https://github.com/torchbox/django-basic-auth-ip-whitelist/actions/workflows/ci.yml/badge.svg
:alt: GitHub actions CI status
:target: https://github.com/torchbox/django-basic-auth-ip-whitelist/actions/
.. image:: https://img.shields.io/pypi/v/django-basic-auth-ip-whitelist.svg
:target: https://pypi.org/project/django-basic-auth-ip-whitelist/
.. image:: https://img.shields.io/pypi/dm/django-basic-auth-ip-whitelist.svg
:target: https://pypi.org/project/django-basic-auth-ip-whitelist/
This simple package ships middleware that lets you to set basic authentication
and IP whitelisting via Django settings.
Use case
--------
This package has been created for staging and demo sites that need to be
completely hidden from the Internet behind a password or accessible only to
certain IP networks.
Do not depend on this package to protect highly valuable information. This
package is at a good way to disable staging sites being discovered by
search engines and Internet users trying to access staging sites. It is
advised that any sensitive information is protected using `Django authentication
system <https://docs.djangoproject.com/en/stable/topics/auth/>`_.
Requirements
------------
- Django 1.8, 1.9, 1.10, 1.11, 2.0, 2.1, 2.2 or 3.0.
- Python 3.4, 3.5, 3.6, 3.7 or 3.8.
Installation
------------
The package is on
`PyPI <https://pypi.org/project/django-basic-auth-ip-whitelist/>`__ so you can
just install it with pip.
.. code:: sh
pip install django-basic-auth-ip-whitelist
Configuration
-------------
In your Django settings you can configure the following settings:
``BASIC_AUTH_LOGIN`` and ``BASIC_AUTH_PASSWORD``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Credentials that you want to use with your basic authentication.
``BASIC_AUTH_WHITELISTED_IP_NETWORKS``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set a list of network ranges (strings) compatible with Python’s
`ipaddress.ip_network <https://docs.python.org/3.6/library/ipaddress.html#ipaddress.ip_network>`__
that you want to be able to access the website without authentication
from. It must be either a string with networks separated by comma or
Python iterable.
**Warning**: See [Getting IP Address](#getting-ip-address) below for caveats around IP address detection.
``BASIC_AUTH_REALM``
~~~~~~~~~~~~~~~~~~~~
String specifying the realm of the default response.
Example settings
~~~~~~~~~~~~~~~~
.. code:: python
MIDDLEWARE += [
'baipw.middleware.BasicAuthIPWhitelistMiddleware'
]
BASIC_AUTH_LOGIN = 'somelogin'
BASIC_AUTH_PASSWORD = 'greatpassword'
BASIC_AUTH_WHITELISTED_IP_NETWORKS = [
'192.168.0.0/28',
'2001:db00::0/24',
]
Advanced customisation
----------------------
Getting IP Address
~~~~~~~~~~~~~~~~~~
By default, ``BasicAuthIPWhitelistMiddleware`` uses ``request.META["REMOTE_ADDR"]``
as the client's IP, which corresponds to the IP address connecting to Django.
If you have a reverse proxy (eg ``nginx`` in front), this will result in the IP address of
``nginx``, not the client.
Correctly determining the IP address can vary between deployments. Guessing incorrectly can
result in security issues. Instead, this library requires you configure this yourselves.
In most deployments, the ``X-Forwarded-For`` header can be used to correctly determine the
client's IP. We recommend `django-xff <https://github.com/ferrix/xff>`__ to help parse this
header correctly. Because ``django-xff`` overrides ``REMOTE_ADDR`` by default, it is natively
supported by ``BasicAuthIPWhitelistMiddleware``.
`django-ipware <https://github.com/un33k/django-ipware>`__ is another popular
library, however may take more customization to implement.
To fully customize IP address detection, you can set ``BASIC_AUTH_GET_CLIENT_IP_FUNCTION`` to
a function which takes a request and returns a valid IP address:
.. code:: python
BASIC_AUTH_GET_CLIENT_IP_FUNCTION = 'utils.ip.get_client_ip'
``BASIC_AUTH_WHITELISTED_HTTP_HOSTS``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set a list of hosts that your website will be open to without basic
authentication. This is useful if your website is hosted under multiple domains
and you want only one of them to be publicly visible, e.g. by search engines.
**This is by no means a security feature. Please do not use to secure your
site.**
.. code:: python
BASIC_AUTH_WHITELISTED_HTTP_HOSTS = [
'your-public-domain.com',
]
``BASIC_AUTH_WHITELISTED_PATHS``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set a list of paths that your website will serve without basic authentication.
This can be used to support API integrations for example with third-party
services which don't support basic authentication.
Paths listed in the setting ``BASIC_AUTH_WHITELISTED_PATHS`` are treated as roots, and any subpath will be whitelisted too. For example:
.. code:: python
BASIC_AUTH_WHITELISTED_PATHS = [
'/api',
]
This will open up the path https://mydomain.com/api/, as well as anything
below it, e.g. https://mydomain.com/api/document/1/.
``BASIC_AUTH_RESPONSE_TEMPLATE``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to display a different template on the 401 page, please use this
setting to point at the template.
.. code:: python
BASIC_AUTH_RESPONSE_TEMPLATE = '401.html'
``BASIC_AUTH_RESPONSE_CLASS``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to specify custom response class, you can do so with this setting.
Provide the path as a string.
.. code:: python
BASIC_AUTH_RESPONSE_CLASS = 'yourmodule.response.CustomUnathorisedResponse'
``BASIC_AUTH_DISABLE_CONSUMING_AUTHORIZATION_HEADER``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set this setting to True if you want the Authorization HTTP header to not be deleted from the request object after it has been used by this package's middleware.
.. code:: python
BASIC_AUTH_DISABLE_CONSUMING_AUTHORIZATION_HEADER = True
Skip middleware
~~~~~~~~~~~~~~~
You can skip the middleware by setting
`_skip_basic_auth_ip_whitelist_middleware_check` attribute on the request to
`True`.
.. code:: python
setattr(request, '_skip_basic_auth_ip_whitelist_middleware_check', True)
This may be handy if you have other middleware that you want to have
co-existing different middleware that restrict access to the website.
Raw data
{
"_id": null,
"home_page": "https://github.com/torchbox/django-basic-auth-ip-whitelist",
"name": "django-basic-auth-ip-whitelist",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": null,
"keywords": "django, basic, authentication, auth, ip, whitelist, whitelisting, http",
"author": "Torchbox",
"author_email": "hello@torchbox.com",
"download_url": "https://files.pythonhosted.org/packages/e0/00/ca5e42ef76363ae9925e0e14a6e0a45885ff2232bb012f8c757584442061/django_basic_auth_ip_whitelist-0.6.0.tar.gz",
"platform": null,
"description": "django-basic-auth-ip-whitelist\n==============================\n\n.. image:: https://github.com/torchbox/django-basic-auth-ip-whitelist/actions/workflows/ci.yml/badge.svg\n :alt: GitHub actions CI status\n :target: https://github.com/torchbox/django-basic-auth-ip-whitelist/actions/\n.. image:: https://img.shields.io/pypi/v/django-basic-auth-ip-whitelist.svg\n :target: https://pypi.org/project/django-basic-auth-ip-whitelist/\n.. image:: https://img.shields.io/pypi/dm/django-basic-auth-ip-whitelist.svg\n :target: https://pypi.org/project/django-basic-auth-ip-whitelist/\n\nThis simple package ships middleware that lets you to set basic authentication\nand IP whitelisting via Django settings.\n\nUse case\n--------\n\nThis package has been created for staging and demo sites that need to be\ncompletely hidden from the Internet behind a password or accessible only to\ncertain IP networks.\n\nDo not depend on this package to protect highly valuable information. This\npackage is at a good way to disable staging sites being discovered by\nsearch engines and Internet users trying to access staging sites. It is\nadvised that any sensitive information is protected using `Django authentication\nsystem <https://docs.djangoproject.com/en/stable/topics/auth/>`_.\n\nRequirements\n------------\n\n- Django 1.8, 1.9, 1.10, 1.11, 2.0, 2.1, 2.2 or 3.0.\n- Python 3.4, 3.5, 3.6, 3.7 or 3.8.\n\nInstallation\n------------\n\nThe package is on\n`PyPI <https://pypi.org/project/django-basic-auth-ip-whitelist/>`__ so you can\njust install it with pip.\n\n.. code:: sh\n\n pip install django-basic-auth-ip-whitelist\n\nConfiguration\n-------------\n\nIn your Django settings you can configure the following settings:\n\n``BASIC_AUTH_LOGIN`` and ``BASIC_AUTH_PASSWORD``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nCredentials that you want to use with your basic authentication.\n\n``BASIC_AUTH_WHITELISTED_IP_NETWORKS``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSet a list of network ranges (strings) compatible with Python\u2019s\n`ipaddress.ip_network <https://docs.python.org/3.6/library/ipaddress.html#ipaddress.ip_network>`__\nthat you want to be able to access the website without authentication\nfrom. It must be either a string with networks separated by comma or\nPython iterable.\n\n**Warning**: See [Getting IP Address](#getting-ip-address) below for caveats around IP address detection.\n\n``BASIC_AUTH_REALM``\n~~~~~~~~~~~~~~~~~~~~\n\nString specifying the realm of the default response.\n\nExample settings\n~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n MIDDLEWARE += [\n 'baipw.middleware.BasicAuthIPWhitelistMiddleware'\n ]\n BASIC_AUTH_LOGIN = 'somelogin'\n BASIC_AUTH_PASSWORD = 'greatpassword'\n BASIC_AUTH_WHITELISTED_IP_NETWORKS = [\n '192.168.0.0/28',\n '2001:db00::0/24',\n ]\n\nAdvanced customisation\n----------------------\n\nGetting IP Address\n~~~~~~~~~~~~~~~~~~\n\nBy default, ``BasicAuthIPWhitelistMiddleware`` uses ``request.META[\"REMOTE_ADDR\"]``\nas the client's IP, which corresponds to the IP address connecting to Django.\nIf you have a reverse proxy (eg ``nginx`` in front), this will result in the IP address of\n``nginx``, not the client.\n\nCorrectly determining the IP address can vary between deployments. Guessing incorrectly can\nresult in security issues. Instead, this library requires you configure this yourselves.\n\nIn most deployments, the ``X-Forwarded-For`` header can be used to correctly determine the\nclient's IP. We recommend `django-xff <https://github.com/ferrix/xff>`__ to help parse this\nheader correctly. Because ``django-xff`` overrides ``REMOTE_ADDR`` by default, it is natively\nsupported by ``BasicAuthIPWhitelistMiddleware``.\n\n`django-ipware <https://github.com/un33k/django-ipware>`__ is another popular\nlibrary, however may take more customization to implement.\n\nTo fully customize IP address detection, you can set ``BASIC_AUTH_GET_CLIENT_IP_FUNCTION`` to\na function which takes a request and returns a valid IP address:\n\n.. code:: python\n\n BASIC_AUTH_GET_CLIENT_IP_FUNCTION = 'utils.ip.get_client_ip'\n\n\n``BASIC_AUTH_WHITELISTED_HTTP_HOSTS``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSet a list of hosts that your website will be open to without basic\nauthentication. This is useful if your website is hosted under multiple domains\nand you want only one of them to be publicly visible, e.g. by search engines.\n\n**This is by no means a security feature. Please do not use to secure your\nsite.**\n\n.. code:: python\n\n BASIC_AUTH_WHITELISTED_HTTP_HOSTS = [\n 'your-public-domain.com',\n ]\n\n\n``BASIC_AUTH_WHITELISTED_PATHS``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSet a list of paths that your website will serve without basic authentication.\nThis can be used to support API integrations for example with third-party\nservices which don't support basic authentication.\n\nPaths listed in the setting ``BASIC_AUTH_WHITELISTED_PATHS`` are treated as roots, and any subpath will be whitelisted too. For example:\n\n.. code:: python\n\n BASIC_AUTH_WHITELISTED_PATHS = [\n '/api',\n ]\n\nThis will open up the path https://mydomain.com/api/, as well as anything\nbelow it, e.g. https://mydomain.com/api/document/1/.\n\n\n``BASIC_AUTH_RESPONSE_TEMPLATE``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you want to display a different template on the 401 page, please use this\nsetting to point at the template.\n\n.. code:: python\n\n BASIC_AUTH_RESPONSE_TEMPLATE = '401.html'\n\n\n``BASIC_AUTH_RESPONSE_CLASS``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIf you want to specify custom response class, you can do so with this setting.\nProvide the path as a string.\n\n.. code:: python\n\n BASIC_AUTH_RESPONSE_CLASS = 'yourmodule.response.CustomUnathorisedResponse'\n\n\n``BASIC_AUTH_DISABLE_CONSUMING_AUTHORIZATION_HEADER``\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nSet this setting to True if you want the Authorization HTTP header to not be deleted from the request object after it has been used by this package's middleware.\n\n.. code:: python\n\n BASIC_AUTH_DISABLE_CONSUMING_AUTHORIZATION_HEADER = True\n\n\nSkip middleware\n~~~~~~~~~~~~~~~\n\nYou can skip the middleware by setting\n`_skip_basic_auth_ip_whitelist_middleware_check` attribute on the request to\n`True`.\n\n.. code:: python\n\n setattr(request, '_skip_basic_auth_ip_whitelist_middleware_check', True)\n\n\nThis may be handy if you have other middleware that you want to have\nco-existing different middleware that restrict access to the website.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Hide your Django site behind basic authentication mechanism with IP whitelisting support.",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/torchbox/django-basic-auth-ip-whitelist"
},
"split_keywords": [
"django",
" basic",
" authentication",
" auth",
" ip",
" whitelist",
" whitelisting",
" http"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15961905aa2ae964a2df058215f44eef6850142ecd41b09b26bff74d4faeb1b5",
"md5": "9d572ad625e001bfce085c3dacf72f8e",
"sha256": "f866c1822861ab6612efb9adec03b12279a82314783aa721c843acfbea04b0b7"
},
"downloads": -1,
"filename": "django_basic_auth_ip_whitelist-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d572ad625e001bfce085c3dacf72f8e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 8525,
"upload_time": "2024-06-18T10:45:57",
"upload_time_iso_8601": "2024-06-18T10:45:57.755748Z",
"url": "https://files.pythonhosted.org/packages/15/96/1905aa2ae964a2df058215f44eef6850142ecd41b09b26bff74d4faeb1b5/django_basic_auth_ip_whitelist-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e000ca5e42ef76363ae9925e0e14a6e0a45885ff2232bb012f8c757584442061",
"md5": "82e7a9b278bd9edca8a95f7d3246fd5d",
"sha256": "51fbef4d483cfccb15d0c38605fd149fd307314ad8a9308580a6b693b94b3329"
},
"downloads": -1,
"filename": "django_basic_auth_ip_whitelist-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "82e7a9b278bd9edca8a95f7d3246fd5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 8611,
"upload_time": "2024-06-18T10:45:59",
"upload_time_iso_8601": "2024-06-18T10:45:59.454253Z",
"url": "https://files.pythonhosted.org/packages/e0/00/ca5e42ef76363ae9925e0e14a6e0a45885ff2232bb012f8c757584442061/django_basic_auth_ip_whitelist-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-18 10:45:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "torchbox",
"github_project": "django-basic-auth-ip-whitelist",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-basic-auth-ip-whitelist"
}
JSON
