forked from CGM_Public/pretix_original
71 lines
3.1 KiB
ReStructuredText
71 lines
3.1 KiB
ReStructuredText
.. highlight:: python
|
|
:linenothreshold: 5
|
|
|
|
Pluggable authentication backends
|
|
=================================
|
|
|
|
Plugins can supply additional authentication backends. This is mainly useful in self-hosted installations
|
|
and allows you to use company-wide login mechanisms such as LDAP or OAuth for accessing pretix' backend.
|
|
|
|
Every authentication backend contains an implementation of the interface defined in ``pretix.base.auth.BaseAuthBackend``
|
|
(see below). Note that pretix authentication backends work differently than plain Django authentication backends.
|
|
Basically, three pre-defined flows are supported:
|
|
|
|
* Authentication mechanisms that rely on a **set of input parameters**, e.g. a username and a password. These can be
|
|
implemented by supplying the ``login_form_fields`` property and a ``form_authenticate`` method.
|
|
|
|
* Authentication mechanisms that rely on **external sessions**, e.g. a cookie or a proxy HTTP header. These can be
|
|
implemented by supplying a ``request_authenticate`` method.
|
|
|
|
* Authentication mechanisms that rely on **redirection**, e.g. to an OAuth provider. These can be implemented by
|
|
supplying a ``authentication_url`` method and implementing a custom return view.
|
|
|
|
Authentication backends are *not* collected through a signal. Instead, they must explicitly be set through the
|
|
``auth_backends`` directive in the ``pretix.cfg`` :ref:`configuration file <config>`.
|
|
|
|
In each of these methods (``form_authenticate``, ``request_authenticate`` or your custom view) you are supposed to
|
|
either get an existing :py:class:`pretix.base.models.User` object from the database or create a new one. There are a
|
|
few rules you need to follow:
|
|
|
|
* You **MUST** only return users with the ``auth_backend`` attribute set to the ``identifier`` value of your backend.
|
|
|
|
* You **MUST** create new users with the ``auth_backend`` attribute set to the ``identifier`` value of your backend.
|
|
|
|
* Every user object **MUST** have an email address. Email addresses are globally unique. If the email address is
|
|
already registered to a user who signs in through a different backend, you **SHOULD** refuse the login.
|
|
|
|
The backend interface
|
|
---------------------
|
|
|
|
.. class:: pretix.base.auth.BaseAuthBackend
|
|
|
|
The central object of each backend is the subclass of ``BaseAuthBackend``.
|
|
|
|
.. autoattribute:: identifier
|
|
|
|
This is an abstract attribute, you **must** override this!
|
|
|
|
.. autoattribute:: verbose_name
|
|
|
|
This is an abstract attribute, you **must** override this!
|
|
|
|
.. autoattribute:: login_form_fields
|
|
|
|
.. autoattribute:: visible
|
|
|
|
.. automethod:: form_authenticate
|
|
|
|
.. automethod:: request_authenticate
|
|
|
|
.. automethod:: authentication_url
|
|
|
|
Logging users in
|
|
----------------
|
|
|
|
If you return a user from ``form_authenticate`` or ``request_authenticate``, the system will handle everything else
|
|
for you correctly. However, if you use a redirection method and build a custom view to verify the login, we strongly
|
|
recommend that you use the following utility method to correctly set session values and enforce two-factor
|
|
authentication (if activated):
|
|
|
|
.. autofunction:: pretix.control.views.auth.process_login
|