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 configuration file.

In each of these methods (form_authenticate, request_authenticate or your custom view) you are supposed to either get an existing 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.

BaseAuthBackend.identifier

A short and unique identifier for this authentication backend. This should only contain lowercase letters and in most cases will be the same as your package name.

This is an abstract attribute, you must override this!

BaseAuthBackend.verbose_name

A human-readable name of this authentication backend.

This is an abstract attribute, you must override this!

BaseAuthBackend.login_form_fields

This property may return form fields that the user needs to fill in to log in.

BaseAuthBackend.visible

Whether or not this backend can be selected by users actively. Set this to False if you only implement request_authenticate.

BaseAuthBackend.form_authenticate(request, form_data)

This method will be called after the user filled in the login form. request will contain the current request and form_data the input for the form fields defined in login_form_fields. You are expected to either return a User object (if login was successful) or None.

BaseAuthBackend.request_authenticate(request)

This method will be called when the user opens the login form. If the user already has a valid session according to your login mechanism, for example a cookie set by a different system or HTTP header set by a reverse proxy, you can directly return a User object that will be logged in.

request will contain the current request. You are expected to either return a User object (if login was successful) or None.

BaseAuthBackend.authentication_url(request)

This method will be called to populate the URL for your authentication method’s tab on the login page. For example, if your method works through OAuth, you could return the URL of the OAuth authorization URL the user needs to visit.

If you return None (the default), the link will point to a page that shows the form defined by login_form_fields.

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

pretix.control.views.auth.process_login(request, user, keep_logged_in)

This method allows you to return a response to a successful log-in. This will set all session values correctly and redirect to either the URL specified in the next parameter, or the 2FA login screen, or the dashboard.

Returns:This method returns a HttpResponse.