# Django Perimeter
Perimeter is a Django app that provides middleware that allows you to
'secure the perimeter' of your django site outside of any existing auth
process that you have.
## Compatibility
**This package now requires Python 3.8+ and Django 3.2+.**
For previous versions please refer to the relevant branch.
## Why?
Most django sites have some kind of user registration and security model -
a login process, decorators to secure certain URLs, user accounts -
everything that comes with `django.contrib.auth` and associated apps.
Sometimes, however, you want to simply secure the entire site to prevent
prying eyes - the classic example being before a site goes live. You
want to erect a secure perimeter fence around the entire thing. If you
have control over your front-end web server (e.g. Apache, Nginx) then
this can be used to do this using their in-built access control
features. However, if you are running your app on a hosting platform you
may not have admin access to these parts. Even if you do have control
over your webserver, you may not want to be re-configuring it every time
you want to grant someone access.
That's when you need Perimeter.
Perimeter provides simple tokenised access control over your entire
Django site (everything, including the admin site and login pages).
## How does it work?
Once you have installed and enabled Perimeter, everyone requiring access
will need an authorisation token (not authentication - there is nothing
inherent in Perimeter to prevent people swapping / sharing tokens - that
is an accepted use case).
Perimeter runs as middleware that will inspect the user's `session`
for a token. If they have a valid token, then they continue to use the
site uninterrupted. If they do not have a token, or the token is invalid
(expired or set to inactive), then they are redirected to the Perimeter
'Gateway', where they must enter a valid token, along with their name
and email (for auditing purposes - this is stored in the database).
To create a new token you need to head to the admin site, and create a
new token under the Perimeter app. If you have `PERIMETER_ENABLED` set
to True already you won't be able to access the admin site (as Perimeter
covers everything except for the perimeter 'gateway' form), and so there
is a management command (`create_access_token`) that you can use to
create your first token. (This is analagous to the Django setup process
where it prompts you to create a superuser.)
Setup
-----
1. Add `"perimeter"` to your installed apps.
2. Add `"perimeter.middleware.PerimeterAccessMiddleware"` to the list of MIDDLEWARE_CLASSES
3. Add the perimeter urls, including the `"perimeter"` namespace.
4. Add `PERIMETER_ENABLED = True` to your settings file. This setting can be used to enable or disable Perimeter in different environments.
Settings:
.. code:: python
PERIMETER_ENABLED = True
INSTALLED_APPS = (
...
"perimeter",
...
)
# Perimeter's middleware must be after SessionMiddleware as it relies on
# request.session
MIDDLEWARE_CLASSES = [
...
"django.contrib.sessions.middleware.SessionMiddleware",
"perimeter.middleware.PerimeterAccessMiddleware",
...
]
Site urls:
.. code:: python
# in site urls
urlpatterns = [
...
# NB you must include the namespace, as it is referenced in the app
path("perimeter/", include("perimeter.urls", namespace="perimeter")),
...
]
## Tests
The app has a suite of tests, and a ``tox.ini`` file configured to run
them when using ``tox`` (recommended).
Raw data
{
"_id": null,
"home_page": "https://github.com/yunojuno/django-perimeter",
"name": "django-perimeter",
"maintainer": "YunoJuno",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "code@yunojuno.com",
"keywords": "",
"author": "YunoJuno",
"author_email": "code@yunojuno.com",
"download_url": "https://files.pythonhosted.org/packages/c2/13/3b6ea79af484ad12630cd39125514965206c06fee20c71fd0303b5c7168c/django_perimeter-0.16.0.tar.gz",
"platform": null,
"description": "# Django Perimeter\n\nPerimeter is a Django app that provides middleware that allows you to\n'secure the perimeter' of your django site outside of any existing auth\nprocess that you have.\n\n## Compatibility\n\n**This package now requires Python 3.8+ and Django 3.2+.**\n\nFor previous versions please refer to the relevant branch.\n\n## Why?\n\nMost django sites have some kind of user registration and security model -\na login process, decorators to secure certain URLs, user accounts -\neverything that comes with `django.contrib.auth` and associated apps.\n\nSometimes, however, you want to simply secure the entire site to prevent\nprying eyes - the classic example being before a site goes live. You\nwant to erect a secure perimeter fence around the entire thing. If you\nhave control over your front-end web server (e.g. Apache, Nginx) then\nthis can be used to do this using their in-built access control\nfeatures. However, if you are running your app on a hosting platform you\nmay not have admin access to these parts. Even if you do have control\nover your webserver, you may not want to be re-configuring it every time\nyou want to grant someone access.\n\nThat's when you need Perimeter.\n\nPerimeter provides simple tokenised access control over your entire\nDjango site (everything, including the admin site and login pages).\n\n## How does it work?\n\nOnce you have installed and enabled Perimeter, everyone requiring access\nwill need an authorisation token (not authentication - there is nothing\ninherent in Perimeter to prevent people swapping / sharing tokens - that\nis an accepted use case).\n\nPerimeter runs as middleware that will inspect the user's `session`\nfor a token. If they have a valid token, then they continue to use the\nsite uninterrupted. If they do not have a token, or the token is invalid\n(expired or set to inactive), then they are redirected to the Perimeter\n'Gateway', where they must enter a valid token, along with their name\nand email (for auditing purposes - this is stored in the database).\n\nTo create a new token you need to head to the admin site, and create a\nnew token under the Perimeter app. If you have `PERIMETER_ENABLED` set\nto True already you won't be able to access the admin site (as Perimeter\ncovers everything except for the perimeter 'gateway' form), and so there\nis a management command (`create_access_token`) that you can use to\ncreate your first token. (This is analagous to the Django setup process\nwhere it prompts you to create a superuser.)\n\nSetup\n-----\n\n1. Add `\"perimeter\"` to your installed apps.\n2. Add `\"perimeter.middleware.PerimeterAccessMiddleware\"` to the list of MIDDLEWARE_CLASSES\n3. Add the perimeter urls, including the `\"perimeter\"` namespace.\n4. Add `PERIMETER_ENABLED = True` to your settings file. This setting can be used to enable or disable Perimeter in different environments.\n\n\nSettings:\n\n.. code:: python\n\n PERIMETER_ENABLED = True\n\n INSTALLED_APPS = (\n ...\n \"perimeter\",\n ...\n )\n\n # Perimeter's middleware must be after SessionMiddleware as it relies on\n # request.session\n MIDDLEWARE_CLASSES = [\n ...\n \"django.contrib.sessions.middleware.SessionMiddleware\",\n \"perimeter.middleware.PerimeterAccessMiddleware\",\n ...\n ]\n\nSite urls:\n\n.. code:: python\n\n # in site urls\n urlpatterns = [\n ...\n # NB you must include the namespace, as it is referenced in the app\n path(\"perimeter/\", include(\"perimeter.urls\", namespace=\"perimeter\")),\n ...\n ]\n\n## Tests\n\nThe app has a suite of tests, and a ``tox.ini`` file configured to run\nthem when using ``tox`` (recommended).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Site-wide perimeter access control for Django projects.",
"version": "0.16.0",
"project_urls": {
"Homepage": "https://github.com/yunojuno/django-perimeter",
"Repository": "https://github.com/yunojuno/django-perimeter"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "090171a8f99f887224b0262062f27ceaa65d5b9fe301ce0ec2105b6792b90a04",
"md5": "a115728b1b107afcf58439822de7dd70",
"sha256": "873e42a442f5577824367af580775478736089db9f6c9389d59c2532cbd29baf"
},
"downloads": -1,
"filename": "django_perimeter-0.16.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a115728b1b107afcf58439822de7dd70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 17103,
"upload_time": "2023-11-14T14:20:11",
"upload_time_iso_8601": "2023-11-14T14:20:11.429017Z",
"url": "https://files.pythonhosted.org/packages/09/01/71a8f99f887224b0262062f27ceaa65d5b9fe301ce0ec2105b6792b90a04/django_perimeter-0.16.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2133b6ea79af484ad12630cd39125514965206c06fee20c71fd0303b5c7168c",
"md5": "22b071dba74ee92628552b5823641816",
"sha256": "18e4e82d0905a5432454cd10efd9c5ccca36914e186245fa2bbf1ac0cdbf0e2d"
},
"downloads": -1,
"filename": "django_perimeter-0.16.0.tar.gz",
"has_sig": false,
"md5_digest": "22b071dba74ee92628552b5823641816",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 12842,
"upload_time": "2023-11-14T14:20:14",
"upload_time_iso_8601": "2023-11-14T14:20:14.297787Z",
"url": "https://files.pythonhosted.org/packages/c2/13/3b6ea79af484ad12630cd39125514965206c06fee20c71fd0303b5c7168c/django_perimeter-0.16.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-14 14:20:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yunojuno",
"github_project": "django-perimeter",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "django-perimeter"
}
JSON
