.. image:: logo/horizontal.svg
:width: 400px
:alt: django-sesame
django-sesame provides frictionless authentication with "Magic Links" for
your Django project.
It generates URLs containing authentication tokens such as:
https://example.com/?sesame=zxST9d0XT9xgfYLvoa9e2myN
Then it authenticates users based on tokens found in URLs.
More broadly, it supports a wide range of `use cases`_ for
stateless, token-based authentication.
Please review `(in)security`_ considerations before using django-sesame.
----
`Documentation is available on ReadTheDocs.`__
----
__ https://django-sesame.readthedocs.io/en/stable/
Requirements
------------
django-sesame is tested with:
- Django 3.2 (LTS), 4.0, 4.1, 4.2 (LTS), and 5.0;
- Python ≥ 3.8.
It requires ``django.contrib.auth``.
Getting started
---------------
Install django-sesame:
.. code-block:: console
$ pip install django-sesame
Open your project settings and add ``"sesame.backends.ModelBackend"`` to the
``AUTHENTICATION_BACKENDS`` setting. Extending the default value, this
looks like:
.. code-block:: python
AUTHENTICATION_BACKENDS = [
"django.contrib.auth.backends.ModelBackend",
"sesame.backends.ModelBackend",
]
Now, your project can authenticate users based on django-sesame tokens.
Quick example
-------------
Configure ``LoginView`` in your URLconf:
.. code-block:: python
from django.urls import path
from sesame.views import LoginView
urlpatterns = [
...,
path("sesame/login/", LoginView.as_view(), name="sesame-login"),
...,
]
Load a user from the database:
.. code-block:: pycon
>>> from django.contrib.auth import get_user_model
>>> User = get_user_model()
>>> user = User.objects.first()
Generate a login URL for this user:
.. code-block:: pycon
>>> from sesame.utils import get_query_string
>>> LOGIN_URL = "https://127.0.0.1:8000/sesame/login/"
>>> LOGIN_URL + get_query_string(user)
'https://127.0.0.1:8000/sesame/login/?sesame=zxST9d0XT9xgfYLvoa9e2myN'
(Your token will be different from this example.)
Make sure that you're logged out. Open the login URL. You are logged in!
Use cases
---------
Known use cases for django-sesame include:
1. Login by email, an attractive option on mobile where typing passwords
is uncomfortable. This technique is prominently deployed by Slack.
If you're doing this, you should define a small ``SESAME_MAX_AGE``, perhaps
10 minutes.
2. Authenticated links. For example, you can generate a report offline
and, when it's ready, email a link to access it. Authenticated links work
even if the user isn't logged in on the device where they're opening it.
Likewise, you should configure an appropriate ``SESAME_MAX_AGE``,
probably a few days.
Since emails may be forwarded, authenticated links shouldn't log the user
in. They should only allow access to specific views.
3. Sharing links, which are a variant of authenticated links. When a user shares
content with a guest, you may create a phantom account for the guest and
generate an authenticated link tied to that account or you may reuse the
user's account.
Email forwarding is also likely in this context. Make sure that sharing links
don't log the user in.
4. Authentication of WebSocket connections. The web application gets a token
generated by the Django server and sends it over the WebSocket connection.
The WebSocket server authenticate the connection with the token.
Here's an `example with the websockets library`__.
__ https://websockets.readthedocs.io/en/stable/howto/django.html
5. Non-critical private websites, for example for a family or club site,
where users don't expect to manage a personal account with a password.
Authorized users can bookmark personalized authenticated URLs.
Here you can rely on the default settings because that's the original —
admittedly, niche — use case for which django-sesame was built.
(In)security
------------
The major security weakness in django-sesame is a direct consequence of the
feature it implements: **whoever obtains an authentication token is able to
authenticate to your website.**
URLs end up in countless insecure places: emails, referer headers, proxy logs,
browser history, etc. You can't avoid that. At best you can mitigate it by
creating short-lived or single-use tokens.
Otherwise, a reasonable attempt was made to provide a secure solution. Tokens
are secured with modern cryptography. There are configurable options for token
invalidation.
Raw data
{
"_id": null,
"home_page": "https://github.com/aaugustin/django-sesame",
"name": "django-sesame",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "authentication,token-based-authentication",
"author": "Aymeric Augustin",
"author_email": "aymeric.augustin@m4x.org",
"download_url": "https://files.pythonhosted.org/packages/eb/88/584aa0c56b0788ef506ca178ba647fc4403b35f4660064dffd43014c3133/django_sesame-3.2.2.tar.gz",
"platform": null,
"description": ".. image:: logo/horizontal.svg\n :width: 400px\n :alt: django-sesame\n\ndjango-sesame provides frictionless authentication with \"Magic Links\" for\nyour Django project.\n\nIt generates URLs containing authentication tokens such as:\nhttps://example.com/?sesame=zxST9d0XT9xgfYLvoa9e2myN\n\nThen it authenticates users based on tokens found in URLs.\n\nMore broadly, it supports a wide range of `use cases`_ for\nstateless, token-based authentication.\n\nPlease review `(in)security`_ considerations before using django-sesame.\n\n----\n\n`Documentation is available on ReadTheDocs.`__\n\n----\n\n__ https://django-sesame.readthedocs.io/en/stable/\n\nRequirements\n------------\n\ndjango-sesame is tested with:\n\n- Django 3.2 (LTS), 4.0, 4.1, 4.2 (LTS), and 5.0;\n- Python \u2265 3.8.\n\nIt requires ``django.contrib.auth``.\n\nGetting started\n---------------\n\nInstall django-sesame:\n\n.. code-block:: console\n\n $ pip install django-sesame\n\nOpen your project settings and add ``\"sesame.backends.ModelBackend\"`` to the\n``AUTHENTICATION_BACKENDS`` setting. Extending the default value, this\nlooks like:\n\n.. code-block:: python\n\n AUTHENTICATION_BACKENDS = [\n \"django.contrib.auth.backends.ModelBackend\",\n \"sesame.backends.ModelBackend\",\n ]\n\nNow, your project can authenticate users based on django-sesame tokens.\n\nQuick example\n-------------\n\nConfigure ``LoginView`` in your URLconf:\n\n.. code-block:: python\n\n from django.urls import path\n from sesame.views import LoginView\n\n urlpatterns = [\n ...,\n path(\"sesame/login/\", LoginView.as_view(), name=\"sesame-login\"),\n ...,\n ]\n\nLoad a user from the database:\n\n.. code-block:: pycon\n\n >>> from django.contrib.auth import get_user_model\n >>> User = get_user_model()\n >>> user = User.objects.first()\n\nGenerate a login URL for this user:\n\n.. code-block:: pycon\n\n >>> from sesame.utils import get_query_string\n >>> LOGIN_URL = \"https://127.0.0.1:8000/sesame/login/\"\n >>> LOGIN_URL + get_query_string(user)\n 'https://127.0.0.1:8000/sesame/login/?sesame=zxST9d0XT9xgfYLvoa9e2myN'\n\n(Your token will be different from this example.)\n\nMake sure that you're logged out. Open the login URL. You are logged in!\n\nUse cases\n---------\n\nKnown use cases for django-sesame include:\n\n1. Login by email, an attractive option on mobile where typing passwords\n is uncomfortable. This technique is prominently deployed by Slack.\n\n If you're doing this, you should define a small ``SESAME_MAX_AGE``, perhaps\n 10 minutes.\n\n2. Authenticated links. For example, you can generate a report offline\n and, when it's ready, email a link to access it. Authenticated links work\n even if the user isn't logged in on the device where they're opening it.\n\n Likewise, you should configure an appropriate ``SESAME_MAX_AGE``,\n probably a few days.\n\n Since emails may be forwarded, authenticated links shouldn't log the user\n in. They should only allow access to specific views.\n\n3. Sharing links, which are a variant of authenticated links. When a user shares\n content with a guest, you may create a phantom account for the guest and\n generate an authenticated link tied to that account or you may reuse the\n user's account.\n\n Email forwarding is also likely in this context. Make sure that sharing links\n don't log the user in.\n\n4. Authentication of WebSocket connections. The web application gets a token\n generated by the Django server and sends it over the WebSocket connection.\n The WebSocket server authenticate the connection with the token.\n\n Here's an `example with the websockets library`__.\n\n __ https://websockets.readthedocs.io/en/stable/howto/django.html\n\n5. Non-critical private websites, for example for a family or club site,\n where users don't expect to manage a personal account with a password.\n Authorized users can bookmark personalized authenticated URLs.\n\n Here you can rely on the default settings because that's the original \u2014\n admittedly, niche \u2014 use case for which django-sesame was built.\n\n(In)security\n------------\n\nThe major security weakness in django-sesame is a direct consequence of the\nfeature it implements: **whoever obtains an authentication token is able to\nauthenticate to your website.**\n\nURLs end up in countless insecure places: emails, referer headers, proxy logs,\nbrowser history, etc. You can't avoid that. At best you can mitigate it by\ncreating short-lived or single-use tokens.\n\nOtherwise, a reasonable attempt was made to provide a secure solution. Tokens\nare secured with modern cryptography. There are configurable options for token\ninvalidation.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Frictionless authentication with \"Magic Links\" for your Django project.",
"version": "3.2.2",
"project_urls": {
"Documentation": "https://django-sesame.readthedocs.io/",
"Homepage": "https://github.com/aaugustin/django-sesame",
"Repository": "https://github.com/aaugustin/django-sesame"
},
"split_keywords": [
"authentication",
"token-based-authentication"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dde7951f35106972668b61e79635c93933c51c2d58f49a9c8ebf0a8ff7262331",
"md5": "9e39f13307b70e070bc9f28e4d993db8",
"sha256": "523ebd4d04e28c897c262f25b78b6fd8f37e11cdca6e277fdc8bf496bd686cf5"
},
"downloads": -1,
"filename": "django_sesame-3.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e39f13307b70e070bc9f28e4d993db8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20289,
"upload_time": "2023-12-16T20:25:32",
"upload_time_iso_8601": "2023-12-16T20:25:32.288296Z",
"url": "https://files.pythonhosted.org/packages/dd/e7/951f35106972668b61e79635c93933c51c2d58f49a9c8ebf0a8ff7262331/django_sesame-3.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eb88584aa0c56b0788ef506ca178ba647fc4403b35f4660064dffd43014c3133",
"md5": "ecf3f262b3bfa740479e0edc987e2297",
"sha256": "5d753a309166356b6a0d7fc047690943b9e80b4aa7952f1a6400fe6ce60d573c"
},
"downloads": -1,
"filename": "django_sesame-3.2.2.tar.gz",
"has_sig": false,
"md5_digest": "ecf3f262b3bfa740479e0edc987e2297",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17615,
"upload_time": "2023-12-16T20:25:34",
"upload_time_iso_8601": "2023-12-16T20:25:34.256453Z",
"url": "https://files.pythonhosted.org/packages/eb/88/584aa0c56b0788ef506ca178ba647fc4403b35f4660064dffd43014c3133/django_sesame-3.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-16 20:25:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aaugustin",
"github_project": "django-sesame",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "django-sesame"
}
JSON
