Customizing

Custom login message (like SMS)

Django Mail Auth can be easily extended. Besides template adaptations it is possible to send different messages like SMS. To make those changes, you will need to write a custom login form.

Custom login form

Custom login forms need to inherit from BaseLoginForm and override the save method.

The following example is for a login SMS. This will require a custom user model with a unique phone_number field:

from django import forms
from django.contrib.auth import get_user_model
from django.template import loader
from mailauth.forms import BaseLoginForm


class SmsLoginForm(BaseLoginForm):
    phone_number = forms.CharField()

    template_name = 'registration/login_sms.txt
    from_number = None

    def __init__(self, *args, **kwargs):
        self.twilio_client = TwilioRestClient(
            settings.TWILIO_SID,
            settings.TWILIO_AUTH_TOKEN
        )
        super().__init__(*args, **kwargs)

    def save(self):
        phone_number = self.cleaned_data['phone_number']
        user = get_user_model().objects.get(
            phone_number=phone_number
        )
        context = self.get_context(self.request, user)

        from_number = self.from_number or getattr(
            settings, 'DEFAULT_FROM_NUMBER'
        )
        sms_content = loader.render_to_string(
            self.template_name, context
        )

        self.twilio_client.messages.create(
            to=user.phone_number,
            from_=from_number,
            body=sms_content
        )

To add the new login form, simply add a new login view to your URL configuration with the custom form:

from django.urls import path
from mailauth.views import LoginView

from .forms import SmsLoginForm

urlpatterns = [
    path(
        'login/sms/',
        LoginView.as_view(form_class=SmsLoginForm),
        name='login-sms'
    ),
]

API documentation

class mailauth.forms.BaseLoginForm(data=None, files=None, auto_id='id_%s', prefix=None, initial=None, error_class=<class 'django.forms.utils.ErrorList'>, label_suffix=None, empty_permitted=False, field_order=None, use_required_attribute=None, renderer=None, bound_field_class=None)

Bases: Form

get_login_url(request, token, next=None)

Return user login URL including the access token.

Parameters:

• request (django.http.request.HttpRequest) – Current request.

• token (str) – The user specific authentication token.

• next (str) – The path the user should be forwarded to after login.

Returns:

User login URL including the access token.

Return type:

str

get_mail_context(request, user)

Return the context for a message template render.

Parameters:

• request (django.http.request.HttpRequest) – Current request.

• user – The user requesting a login message.

Returns:

A context dictionary including: - site - site_name - token - login_url - user

Return type:

dict

get_token(user)

Return the access token.

property media

Return all media required to render the widgets on this form.

save()

Send login URL to users.

Called from the login view, if the form is valid.

This method must be implemented by subclasses. This method should trigger the login URL to be sent to the user.

Custom User Model

For convenience, Django Mail Auth provides a EmailUser which is almost identical to Django’s built in User but without the password and username field. The email field serves as a username and is – different to Django’s User – unique and case insensitive.

Implementing a custom User model

from mailauth.contrib.user.models import AbstractEmailUser
from phonenumber_field.modelfields import PhoneNumberField


class SMSUser(AbstractEmailUser):
    phone_number = phone = PhoneNumberField(_("phone number"), unique=True, db_index=True)

class Meta(AbstractEmailUser.Meta):
    verbose_name = _("user")
    verbose_name_plural = _("users")
    swappable = "AUTH_USER_MODEL"

Note

Do not forget to adjust your AUTH_USER_MODEL to correct app_label.ModelName.

API documentation

class mailauth.contrib.user.models.AbstractEmailUser(*args, **kwargs)

Bases: AbstractUser

email

Unique and case insensitive to serve as a better username.

session_salt

Salt for the session hash replacing the password in this function.

anonymize(commit=True)

Anonymize the user data for privacy purposes.

This method will erase the email address, first and last name. You may overwrite this method to add additional fields to anonymize:

class MyUser(AbstractEmailUser):
    def anonymize(self, commit=True):
        super().anonymize(commit=False) # do not commit yet
        self.phone_number = None
        if commit:
            self.save()

email

Unique and case insensitive to serve as a better username.

get_session_auth_hash()

Return an HMAC of the session_salt field.

has_usable_password()

Return False if set_unusable_password() has been called for this user.

session_salt

Salt for the session hash replacing the password in this function.

username = None

class mailauth.contrib.user.models.EmailUser(id, last_login, is_superuser, first_name, last_name, is_staff, is_active, date_joined, email, session_salt)

Bases: AbstractEmailUser

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

email

Unique and case insensitive to serve as a better username.

session_salt

Salt for the session hash replacing the password in this function.