django-moses 0.15.0

Advanced authentication with OTP and phone number verification

Moses

Moses is the Django app that provides OTP authentication and phone number email verification by 6-digit verification codes.

Quick start

1. Add "moses" to your INSTALLED_APPS setting like this::

    INSTALLED_APPS = [
        ...
        'moses',
        'django.contrib.admin',
        ...
        'social_django',
    ]

2. Set moses's CustomUser model as AUTH_USER_MODEL::

    AUTH_USER_MODEL = 'moses.CustomUser'

3. Allow OTP header in django-cors-headers config::

    CORS_ALLOW_HEADERS = (
        *default_headers,
        "otp",
   )

4. Add MFAModelBackend as Authentication backend to process OTP on authentication::

    AUTHENTICATION_BACKENDS = [
        'social_core.backends.google.GoogleOAuth2',
        'moses.authentication.MFAModelBackend',
        ...
    ]

5. Add JWTAuthentication to REST_FRAMEWORK's DEFAULT_AUTHENTICATION_CLASSES::

    REST_FRAMEWORK = {
        ...
        'DEFAULT_AUTHENTICATION_CLASSES': [
            'moses.authentication.JWTAuthentication',
        ]
    }

6. Specify Moses's serializers for Djoser::

    MOSES = {
        "DEFAULT_LANGUAGE": 'en',
        "SEND_SMS_HANDLER": "project.common.sms.send",
        "SENDER_EMAIL": "[e-mail]",
        "PHONE_NUMBER_VALIDATOR": "project.common.sms.validate_phone_number",
        "DOMAIN": DOMAIN,
        "URL_PREFIX": "http://localhost:8000", # without trailing slash
        "IP_HEADER": "HTTP_CF_CONNECTING_IP" if DEBUG else None,
        "LANGUAGE_CHOICES": (
            ('en', _("English")),
        ),
    }

7. Add to your root urls.py::

    from moses.admin import OTPAdminAuthenticationForm
    from moses import urls as moses_urls

    admin.site.site_header = _('Admin Panel')
    admin.site.index_title = 'Welcome'
    admin.site.login_form = OTPAdminAuthenticationForm
    urlpatterns = [
        ...
        path('moses/', include(moses_urls, namespace='moses')),
    ]

8. Run python manage.py migrate to create the accounts models.

9. Add middleware:

MIDDLEWARE = [
    ...
    'social_django.middleware.SocialAuthExceptionMiddleware',
]

10. Add context processors:

TEMPLATES[0]['OPTIONS']['context_processors'] += [
    'social_django.context_processors.backends',
    'social_django.context_processors.login_redirect',
]

Telegram Login Widget Authentication

Moses supports authentication via the Telegram Login Widget.

Settings

Add TELEGRAM_BOT_TOKEN to your MOSES configuration:

MOSES = {
    ...
    "TELEGRAM_BOT_TOKEN": "your-bot-token",
}

Endpoints

Step 1: POST /moses/token/telegram/

Send the Telegram Login Widget callback data:

{
    "id": 123456789,
    "first_name": "John",
    "last_name": "Doe",
    "username": "johndoe",
    "photo_url": "https://t.me/i/userpic/...",
    "auth_date": 1234567890,
    "hash": "abc123...",
    "domain": "example.com"
}

Response if user exists:

{"status": "authenticated", "refresh": "...", "access": "..."}

Response if new user:

{"status": "phone_required", "telegram_auth_token": "...", "telegram_id": 123456789, "first_name": "John", ...}

Step 2: POST /moses/token/telegram/complete/ (new users only)

{
    "telegram_auth_token": "temp-token-from-step-1",
    "phone_number": "[phone]",
    "domain": "example.com"
}

Response:

{"status": "authenticated", "refresh": "...", "access": "..."}

Frontend Widget Setup

Add the Telegram Login Widget to your frontend:

<script async src="https://telegram.org/js/telegram-widget.js?22"
        data-telegram-login="your_bot_username"
        data-size="large"
        data-onauth="onTelegramAuth(user)"
        data-request-access="write">
</script>
<script>
function onTelegramAuth(user) {
    fetch('/moses/token/telegram/', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({...user, domain: 'example.com'})
    })
    .then(r => r.json())
    .then(data => {
        if (data.status === 'authenticated') {
            // Store JWT tokens
        } else if (data.status === 'phone_required') {
            // Show phone number form, then POST to /moses/token/telegram/complete/
        }
    });
}
</script>

Signals

Moses emits Django signals during credential confirmation workflows. You can listen to these signals in your application to perform custom actions.

Available Signals

phone_number_confirmed

Emitted when a user successfully confirms their phone number.

Parameters:

• sender: The User model class
• user: The user instance whose phone was confirmed
• phone_number: The confirmed phone number (str)
• is_initial_confirmation: True if this is the first confirmation, False if updating phone number

Example usage:

from django.dispatch import receiver
from moses.signals import phone_number_confirmed
from moses.models import CustomUser

@receiver(phone_number_confirmed, sender=CustomUser)
def handle_phone_confirmed(sender, user, phone_number, is_initial_confirmation, **kwargs):
    if is_initial_confirmation:
        print(f"User {user.id} confirmed their phone: {phone_number}")
    else:
        print(f"User {user.id} changed their phone to: {phone_number}")

email_confirmed

Emitted when a user successfully confirms their email address.

Parameters:

• sender: The User model class
• user: The user instance whose email was confirmed
• email: The confirmed email address (str)
• is_initial_confirmation: True if this is the first confirmation, False if updating email

Example usage:

from django.dispatch import receiver
from moses.signals import email_confirmed
from moses.models import CustomUser

@receiver(email_confirmed, sender=CustomUser)
def handle_email_confirmed(sender, user, email, is_initial_confirmation, **kwargs):
    if is_initial_confirmation:
        print(f"User {user.id} confirmed their email: {email}")
    else:
        print(f"User {user.id} changed their email to: {email}")