otp django؛ ورود با شماره و کد یکبارمصرف با بک‌اند احراز هویت سفارشی

otp django یعنی کاربر شماره‌ی موبایلش را می‌دهد، کدی کوتاه با پیامک می‌گیرد و با آن به برنامه‌ی جنگویی شما وارد می‌شود. جنگو برای این کار یک نقطه‌ی توسعه‌ی آماده دارد: بک‌اند احراز هویت. به‌جای دست‌کاری فرم ورود یا ساختن نشست دستی، یک کلاس کوچک می‌نویسید که کد را می‌سنجد و تابع استاندارد login بقیه‌اش را انجام می‌دهد. این صفحه همه‌ی قطعه‌ها را می‌سازد: مدل کد، سرویس با چکیده و سقف تلاش، بک‌اند، ویوها، محدودیت درخواست با cache و تست. در پایان هم می‌بینید برای کاربران اپ فینگت چطور می‌شود کل ماجرا را بدون پیامک انجام داد.

بروزرسانی: زمان مطالعه حدود ۱۰ دقیقه نوشته‌ی تیم فنی فینگت

otp django؛ چه قطعه‌هایی لازم است و جنگو کدام را آماده دارد؟

ساخت otp django سه قطعه دارد. اول جایی برای نگه‌داری کد موقت: جدولی کوچک با شماره، چکیده‌ی کد، زمان انقضا و تعداد تلاش‌های اشتباه. دوم منطق ساخت و بررسی کد، که بهتر است در یک ماژول سرویس جدا از ویو باشد. سوم اتصال به سیستم احراز هویت جنگو، که با یک بک‌اند سفارشی انجام می‌شود تا authenticate و login همان رفتار همیشگی را داشته باشند.

جنگو ابزارهای مهم otp django را از قبل دارد: make_password و check_password برای چکیده، تابع login برای نشست، cache برای شمارنده‌ها و TestCase برای آزمایش. چیزی که باید خودتان بسازید فقط چسب میان آنهاست و همین، نتیجه را از یک بسته‌ی جانبی شفاف‌تر می‌کند.

بسته‌ی معروف django-otp عمدتاً برای رمز دومرحله‌ای مبتنی بر زمان و دستگاه‌های احراز هویت است. اگر هدف شما ورود با پیامک است، لازم نیست آن را به کار ببرید؛ مستندات خودش را برای کاربرد دقیقش ببینید.

اگر مفهوم رمز یکبارمصرف را هنوز جا نینداخته‌اید، رمز یکبار مصرف otp را بخوانید. برای دیدن همین منطق در زبان‌های دیگر هم ورود با موبایل php و ورود با پیامک لاراول مرجع مناسبی‌اند.

حساب کاربر؛ چرا مدل کاربر سفارشی لازم نیست؟

تغییر مدل کاربر در جنگو معمولاً باید از ابتدای پروژه انجام شود و بعد از ساخت جدول‌ها پرهزینه است. خبر خوب اینکه برای ورود پیامکی مجبور به این کار نیستید. می‌توانید شماره‌ی موبایل را در فیلد username همان مدل User ذخیره کنید و برای حساب‌هایی که با پیامک ساخته می‌شوند، رمز عبور را «غیرقابل‌استفاده» بگذارید.

تابع set_unusable_password یک مقدار خاص در ستون رمز می‌نویسد که با هیچ رشته‌ای مطابقت نمی‌کند. نتیجه این است که حتی اگر کسی صفحه‌ی ورود با رمز را پیدا کند، نمی‌تواند با آن حساب وارد شود و تنها راه ورود همان کد پیامکی است. اگر بعدها خواستید نام، ایمیل یا فیلد دیگری اضافه کنید، یک مدل Profile با ارتباط یک‌به‌یک ساده‌ترین راه است.

یک نکته‌ی امنیتی مهم: حساب‌های مدیریتی، یعنی is_staff و is_superuser، نباید با کد پیامکی وارد شوند. اگر مهاجمی بتواند شماره‌ی یک مدیر را حدس بزند و فقط به کدش نیاز باشد، سطح حمله بزرگ می‌شود. در بک‌اند پایین این حالت را صریحاً رد می‌کنیم.

مدل و سرویس؛ ساخت و بررسی کد

مدل OtpCode برای هر شماره یک ردیف نگه می‌دارد. در سرویس، کد با ماژول secrets ساخته می‌شود که منبع تصادفی امن سیستم‌عامل را می‌خواند. توابع random مدل‌ساز عمومی برای کدهایی که امنیت به آنها تکیه دارد مناسب نیستند. چکیده را با make_password می‌سازیم که از الگوریتم‌های تنظیم‌شده در جنگو استفاده می‌کند.

بررسی کد داخل یک تراکنش با select_for_update انجام می‌شود تا اگر مهاجم چند درخواست را همزمان بفرستد، همه شمارنده‌ی قدیمی را نخوانند و سقف تلاش دور زده نشود. توجه: روی SQLite قفل ردیف اثری ندارد، پس در محیط تولید با PostgreSQL یا MySQL این محافظت واقعاً کار می‌کند.

accounts/models.py
from django.db import models


class OtpCode(models.Model):
    phone = models.CharField(max_length=11, unique=True)
    code_hash = models.CharField(max_length=128)
    expires_at = models.DateTimeField()
    attempts = models.PositiveSmallIntegerField(default=0)
accounts/services.py؛ ساخت، ارسال و بررسی کد
import re
import secrets
from datetime import timedelta

import requests
from django.conf import settings
from django.contrib.auth.hashers import check_password, make_password
from django.db import transaction
from django.utils import timezone

from .models import OtpCode

TTL = timedelta(minutes=3)
MAX_ATTEMPTS = 5
_FA = str.maketrans("۰۱۲۳۴۵۶۷۸۹", "0123456789")


def normalize_phone(raw):
    """هر شکلی از شماره را به 09xxxxxxxxx برمی‌گرداند؛ در غیر این صورت None."""
    digits = re.sub(r"\D+", "", str(raw).translate(_FA))
    if digits.startswith("98"):
        digits = "0" + digits[2:]
    return digits if re.fullmatch(r"09\d{9}", digits) else None


def send_sms(phone, text):
    # جانشین: آدرس و فیلدها را از مستندات سرویس‌دهنده‌ی خودتان بگیرید
    r = requests.post(
        settings.SMS_API_URL,
        json={"sender": settings.SMS_SENDER, "to": phone, "text": text},
        headers={"Authorization": "Bearer " + settings.SMS_API_KEY},
        timeout=8,
    )
    r.raise_for_status()


def issue(phone):
    code = "%06d" % secrets.randbelow(1_000_000)
    OtpCode.objects.update_or_create(
        phone=phone,
        defaults={"code_hash": make_password(code), "expires_at": timezone.now() + TTL, "attempts": 0},
    )
    send_sms(phone, "کد ورود شما: " + code)


def verify(phone, code):
    with transaction.atomic():
        row = OtpCode.objects.select_for_update().filter(phone=phone).first()
        if row is None or row.expires_at <= timezone.now() or row.attempts >= MAX_ATTEMPTS:
            return False
        if not check_password(code, row.code_hash):
            row.attempts += 1
            row.save(update_fields=["attempts"])
            return False
        row.delete()  # یکبارمصرف: بعد از اولین موفقیت باطل می‌شود
        return True

custom authentication backend؛ اتصال کد به سیستم ورود جنگو

یک custom authentication backend کلاسی است که متد authenticate دارد و اگر اعتبارنامه درست بود، کاربر را برمی‌گرداند و در غیر این صورت None. جنگو بک‌اندهای ثبت‌شده را پشت سر هم امتحان می‌کند. چون backend ما فقط وقتی کار می‌کند که phone و code را بگیرد، با ورود معمولی با رمز تداخلی ندارد و هر دو کنار هم زندگی می‌کنند.

دو قاعده در کد زیر مهم است. اول اینکه کاربر غیرفعال و حساب مدیریتی رد می‌شوند. دوم اینکه کاربر تازه با رمز غیرقابل‌استفاده ساخته می‌شود. متد get_user را هم باید پیاده کنید چون جنگو در هر درخواست نشست، کاربر را با آن بازیابی می‌کند.

accounts/backends.py
from django.contrib.auth import get_user_model
from django.contrib.auth.backends import BaseBackend

from .services import verify


class OtpBackend(BaseBackend):
    def authenticate(self, request, phone=None, code=None):
        if not phone or not code or not verify(phone, code):
            return None

        User = get_user_model()
        user, created = User.objects.get_or_create(username=phone)
        if created:
            user.set_unusable_password()
            user.save(update_fields=["password"])

        # حساب غیرفعال و حساب‌های مدیریتی هرگز با کد پیامکی وارد نشوند
        if not user.is_active or user.is_staff or user.is_superuser:
            return None
        return user

    def get_user(self, user_id):
        User = get_user_model()
        try:
            return User.objects.get(pk=user_id)
        except User.DoesNotExist:
            return None
settings.py
AUTHENTICATION_BACKENDS = [
    "accounts.backends.OtpBackend",
    "django.contrib.auth.backends.ModelBackend",  # ورود مدیر با نام کاربری و رمز
]

SMS_API_URL = os.environ["SMS_API_URL"]
SMS_API_KEY = os.environ["SMS_API_KEY"]
SMS_SENDER = os.environ["SMS_SENDER"]

ورود با شماره موبایل django؛ ویوها و آدرس‌ها

ویو درخواست کد سه چیز را کنترل می‌کند: اعتبار شماره، فاصله‌ی ۶۰ ثانیه‌ای بین دو ارسال و سقف پنج ارسال در ساعت برای هر شماره. برای شمارنده‌ها از cache استفاده شده است. متد cache.add فقط وقتی کلید وجود ندارد آن را می‌سازد و False برمی‌گرداند اگر وجود داشته باشد، پس برای ساخت فاصله‌ی ۶۰ ثانیه‌ای یک عمل اتمی است.

در ورود با شماره موبایل django ویو بررسی کد، تابع authenticate را با phone و code صدا می‌زند. اگر کاربر برگشت، login نشست را می‌سازد و شناسه‌ی نشست را هم عوض می‌کند. چون ما بک‌اند را صریحاً می‌دهیم، جنگو لازم نیست از میان بک‌اندها حدس بزند.

accounts/views.py
import re

from django.contrib.auth import authenticate, login
from django.core.cache import cache
from django.http import JsonResponse
from django.views.decorators.http import require_POST

from .services import issue, normalize_phone

_FA = str.maketrans("۰۱۲۳۴۵۶۷۸۹", "0123456789")


@require_POST
def request_code(request):
    phone = normalize_phone(request.POST.get("phone", ""))
    if not phone:
        return JsonResponse({"error": "invalid_phone"}, status=400)

    cool_key, hour_key = "otp-cool:" + phone, "otp-hour:" + phone
    if not cache.add(cool_key, 1, timeout=60):  # کمتر از ۶۰ ثانیه از ارسال قبلی گذشته
        return JsonResponse({"error": "wait"}, status=429)
    cache.add(hour_key, 0, timeout=3600)
    try:
        sent_this_hour = cache.incr(hour_key)
    except ValueError:  # کلید همین لحظه منقضی شد
        cache.set(hour_key, 1, timeout=3600)
        sent_this_hour = 1
    if sent_this_hour > 5:
        return JsonResponse({"error": "too_many"}, status=429)

    try:
        issue(phone)
    except Exception:
        cache.delete(cool_key)  # ارسال ناموفق نباید کاربر را معطل کند
        return JsonResponse({"error": "sms_failed"}, status=502)
    return JsonResponse({"ok": True})


@require_POST
def verify_code(request):
    phone = normalize_phone(request.POST.get("phone", ""))
    code = request.POST.get("code", "").translate(_FA)
    user = authenticate(request, phone=phone, code=code) if phone and re.fullmatch(r"[0-9]{6}", code) else None
    if user is None:
        return JsonResponse({"error": "bad_code"}, status=400)
    login(request, user, backend="accounts.backends.OtpBackend")
    return JsonResponse({"ok": True})
accounts/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path("login/request/", views.request_code),
    path("login/verify/", views.verify_code),
]

در هر دو ویو otp django به همان مسیر قدیمی نشست متکی است. فرم‌های شما باید توکن CSRF را بفرستند. این حفاظت جنگو را برای مسیرهای ورود خاموش نکنید.

rate limit در django؛ نکته‌ی cache و چند سرور

در نمونه‌ی بالا شمارنده‌ها در cache جنگو هستند، و اینجا یک نکته‌ی عملی وجود دارد که زیاد نادیده گرفته می‌شود. cache پیش‌فرض جنگو، LocMemCache، فقط در حافظه‌ی همان فرایند است. اگر برنامه با چند کارگر Gunicorn یا چند سرور اجرا شود، هر کارگر شمارنده‌ی جدا دارد و سقف پنج‌تایی در عمل پنج برابر یا بیشتر می‌شود. برای otp django در تولید، از cache مشترک مثل Redis یا Memcached استفاده کنید.

دو سطح محدودیت لازم است. سطح اول به ازای شماره است، همان که در ویو آمد. سطح دوم به ازای آی‌پی برای محافظت از کل مسیرهای ورود، که یا با ابزار پروکسی و فایروال انجام می‌شود یا با یک دکوراتور سبک. فقط بر اساس آی‌پی سقف نگذارید: شبکه‌های سازمانی و اپراتورهای موبایل آی‌پی مشترک دارند و سقف سخت‌گیرانه کاربران درست را هم می‌بندد.

اگر آی‌پی را از هدر پروکسی می‌خوانید، فقط هدرهایی را قبول کنید که پروکسی مورد اعتماد خودتان ساخته؛ در غیر این صورت مهاجم با هدر جعلی سقف را دور می‌زند. حمله‌ی پشت این محدودیت‌ها در جلوگیری از sms bombing و ملاحظات عمومی‌تر در امنیت otp آمده است.

تست otp در django بدون ارسال حتی یک پیامک

تست otp در django ساده است چون TestCase هم کلاینت دارد و هم پایگاه‌داده‌ی موقت. تنها چیزی که باید جایگزین شود تابع ارسال پیامک است. با unittest.mock تابع send_sms را در ماژول services می‌گیریم و کد را از متن پیامی که قرار بود فرستاده شود، بیرون می‌کشیم.

دو آزمایش می‌نویسیم: ورود موفق با کد درست، و قفل‌شدن بعد از پنج تلاش اشتباه که حتی کد درست هم بعدش کار نمی‌کند.

accounts/tests.py
import re
from unittest.mock import patch

from django.core.cache import cache
from django.test import TestCase


class OtpLoginTests(TestCase):
    def setUp(self):
        cache.clear()  # شمارنده‌های آزمایش قبلی نماند

    def _request_code(self, send_mock, phone):
        res = self.client.post("/login/request/", {"phone": phone})
        self.assertEqual(res.status_code, 200)
        text = send_mock.call_args[0][1]
        return re.search(r"\d{6}", text).group()

    @patch("accounts.services.send_sms")
    def test_login_with_correct_code(self, send):
        code = self._request_code(send, "09120000000")
        res = self.client.post("/login/verify/", {"phone": "09120000000", "code": code})
        self.assertEqual(res.status_code, 200)
        self.assertIn("_auth_user_id", self.client.session)

    @patch("accounts.services.send_sms")
    def test_locked_after_five_wrong_attempts(self, send):
        code = self._request_code(send, "09120000001")
        for _ in range(5):
            self.client.post("/login/verify/", {"phone": "09120000001", "code": "000000"})
        res = self.client.post("/login/verify/", {"phone": "09120000001", "code": code})
        self.assertEqual(res.status_code, 400)
        self.assertNotIn("_auth_user_id", self.client.session)

با python manage.py test اجرا کنید. اگر در حالت تصادفی کد «000000» همان کد واقعی شد، آزمایش یک بار در یک میلیون بار شکست می‌خورد؛ برای حذف این احتمال می‌توانید در تست، کد اشتباه را از روی کد واقعی بسازید. آزمایش سوم هم مفید است: کد منقضی را با تغییر زمان انقضای ردیف در پایگاه‌داده رد کنید.

اشتباه‌های رایج در otp در جنگو

این چهار مورد را در بازبینی پروژه‌های جنگویی بیشتر می‌بینیم.

ذخیره‌ی خود کد

کد خام در ستون پایگاه‌داده یعنی هر نسخه‌ی پشتیبان لو‌رفته مجموعه‌ای از کدهای قابل‌استفاده است. فقط چکیده را ذخیره کنید و بعد از موفقیت ردیف را حذف کنید.

ساخت کد با random عمومی

ماژول random برای شبیه‌سازی است و خروجی‌اش از روی چند نمونه قابل پیش‌بینی است. برای کد ورود از secrets استفاده کنید.

اجازه‌ی ورود به مدیرها با کد

اگر بک‌اند شما حساب staff را بپذیرد، حدس یک شماره و کد می‌تواند پنل مدیریت را باز کند. مدیران را با رمز و روش قوی‌تر وارد کنید.

cache محلی در چند سرور

LocMemCache بین فرایندها مشترک نیست و سقف‌ها را بی‌اثر می‌کند. در تولید از یک cache مشترک استفاده کنید.

پیام‌های خطای افشاگر

پیام «این شماره ثبت نشده» می‌گوید کدام شماره‌ها کاربر دارند. با مسیر ترکیبی ورود و ثبت‌نام همیشه همان پاسخ را بدهید.

کی این منطق را خودتان نگه دارید و کی نه؟

کدی که بالا نوشتیم کوتاه است، ولی «کوتاه» با «بی‌نگهداری» یکی نیست. هزینه‌ی هر پیام، شکایت‌های «کد نرسید» و بازبینی دوره‌ای سقف‌ها همیشه با شماست.

نگه‌داری آن منطقی است، اگر

  • بخش بزرگ کاربران شما اپ ندارند و پیامک تنها راه قابل‌اتکا برای رسیدن به آنهاست.
  • می‌خواهید جزئیات تجربه‌ی ورود و داده‌ها زیر کنترل خودتان باشد.
  • تیم، توان نگهداری از جدول کد، سقف‌ها و ارتباط با شرکت پیامکی را دارد.

ارزش دارد گزینه‌ی دیگری هم کنارش باشد، اگر

  • کاربرانی دارید که اپ را نصب کرده‌اند و می‌توانند ورود را در گوشی تأیید کنند.
  • هزینه‌ی پیامک و تماس‌های «کد نمی‌آید» زیاد است؛ کد تایید نمیاد دلایل رایج آن را دارد.
  • می‌خواهید کاربران بدون انتظار برای پیامک وارد شوند.

ورود با فینگت؛ همان نتیجه بدون ساخت کد

روش فینگت شبیه ورود با گوگل است. سایت شما کاربر را به finget.ir می‌فرستد، کاربر دارنده‌ی اپ ورود را در گوشی تأیید می‌کند و مرورگر او با یک کد کوتاه‌عمر، حدود دو دقیقه، به آدرس بازگشت شما برمی‌گردد. سرور شما با یک درخواست POST آن کد را به اطلاعات کاربر تبدیل می‌کند: نام، شماره‌ی تأییدشده و یک شناسه‌ی ثابت برای همین سایت.

در این مسیر مدل OtpCode، سرویس ارسال، سقف‌ها و هزینه‌ی هر پیامک وجود ندارد. فینگت سرویس پیامکی نیست و خط یا پنل نمی‌فروشد؛ فقط برای کاربرانی که اپ دارند پیامک ورود را حذف می‌کند. اپ فعلاً برای اندروید است، پس ورود پیامکی بالا برای بقیه‌ی کاربران می‌ماند و دکمه‌ی فینگت کنار آن قرار می‌گیرد. حساب‌های مدیریتی هم همان‌طور که در بک‌اند بالا دیدید، نباید با این مسیر وارد شوند.

نمونه‌ی ورود با فینگت در Django

دو ویو کافی است. شناسه‌ی سایت و کلید API را از پنل سرویس‌دهندگان فینگت می‌گیرید و آدرس بازگشت را هم همان‌جا ثبت می‌کنید. FINGET_SITE_ID و FINGET_API_KEY را مثل تنظیمات پیامک از متغیر محیطی در settings بخوانید.

accounts/finget.py
import hmac
import secrets

import requests
from django.conf import settings
from django.contrib.auth import get_user_model, login
from django.http import HttpResponse, HttpResponseBadRequest
from django.shortcuts import redirect


def finget_login(request):
    request.session["fg_state"] = secrets.token_hex(16)  # برای جلوگیری از درخواست جعلی
    return redirect(
        "https://finget.ir/auth?client_id=%s&state=%s" % (settings.FINGET_SITE_ID, request.session["fg_state"])
    )


# همین آدرس را در پنل سرویس‌دهندگان به‌عنوان آدرس بازگشت ثبت کنید
def finget_callback(request):
    expected = request.session.pop("fg_state", "")
    state = request.GET.get("state", "")
    if not expected or not hmac.compare_digest(expected.encode(), state.encode()):
        return HttpResponseBadRequest()

    r = requests.post(
        "https://finget.ir/api/v1/auth/token",
        json={"code": request.GET.get("code", "")},
        headers={"Authorization": "Bearer " + settings.FINGET_API_KEY},
        timeout=8,
    )
    info = (r.json() if r.ok else {}).get("user") or {}
    if not info.get("id"):
        return HttpResponse(status=401)

    User = get_user_model()
    user, created = User.objects.get_or_create(username=info["id"])  # شناسه‌ی ثابت کاربر برای این سایت
    if created:
        user.set_unusable_password()
        user.save(update_fields=["password"])
    if not user.is_active or user.is_staff or user.is_superuser:
        return HttpResponse(status=403)

    login(request, user, backend="django.contrib.auth.backends.ModelBackend")
    return redirect("/")

info شامل id، name و phone است و می‌توانید نام و شماره‌ی تأییدشده را در پروفایل ذخیره کنید. این کد هیچ ارسال پیامک، جدول کد و سقفی ندارد، چون پیامکی در کار نیست. مفهوم کلی را در ورود بدون رمز عبور و مقایسه‌ی آن با کد پیامکی را در جایگزین otp پیامکی ببینید. برای کار با خود وب‌سرویس پیامک در پایتون هم ارسال پیامک پایتون را بخوانید و برای نصب اپ، صفحه‌ی دانلود را باز کنید.

پرسش‌های متداول درباره otp django

برای otp django حتماً باید از بسته‌ی django-otp استفاده کنم؟

نه. آن بسته بیشتر برای رمز دومرحله‌ای و دستگاه‌های احراز هویت ساخته شده است. برای ورود با کد پیامکی، یک مدل کوچک، سرویس و یک بک‌اند سفارشی کافی است و کدی که خودتان می‌خوانید ساده‌تر بررسی می‌شود.

چرا شماره را در username ذخیره کردیم؟

تا نیازی به مدل کاربر سفارشی نباشد؛ تغییر آن در پروژه‌ی در حال اجرا پرهزینه است. اگر از ابتدا پروژه را می‌سازید و فیلد phone جدا می‌خواهید، مدل کاربر سفارشی هم گزینه‌ی خوبی است و بک‌اند همان کار می‌کند.

چرا حساب‌های staff با کد پیامکی وارد نمی‌شوند؟

چون کد شش‌رقمی و پیامک سطح امنیت پایین‌تری از رمز قوی و روش دومرحله‌ای دارد. اگر مهاجم شماره‌ی یک مدیر را حدس بزند، نباید با تلاش روی کد به پنل مدیریت برسد. مدیران را با رمز و روش قوی‌تر وارد کنید.

rate limit در django را با cache کافی است؟

برای شروع بله، به شرط اینکه cache بین همه‌ی کارگرها مشترک باشد؛ مثلاً Redis. LocMemCache برای هر فرایند جداست و سقف را بی‌اثر می‌کند. علاوه بر سقف به ازای شماره، یک سقف به ازای آی‌پی در لایه‌ی پروکسی هم بگذارید.

چطور بدون ارسال واقعی تست کنم؟

تابع send_sms را در تست با unittest.mock جایگزین کنید و کد را از متن پیام ساختگی بخوانید. هیچ پیامی نمی‌رود و همه‌ی حالت‌ها، از ورود موفق تا قفل‌شدن بعد از پنج تلاش، قابل تکرارند.

فینگت پیامک را از پروژه‌ی من حذف می‌کند؟

فقط پیامک ورود کاربرانی که اپ فینگت دارند. اپ فعلاً برای اندروید است و فینگت پنل یا خط پیامکی نمی‌فروشد، پس معمولاً دکمه‌ی فینگت کنار ورود پیامکی می‌ماند، نه جای آن.