ورود با پیامک لاراول؛ کد یکبارمصرف امن با Hash، RateLimiter و تست
ورود با پیامک لاراول یعنی کاربر شمارهاش را میدهد، کدی کوتاه میگیرد و با آن وارد میشود. لاراول تقریباً همهی ابزارهای لازم را آماده دارد: Hash برای چکیدهی کد، RateLimiter برای سقف درخواست، Http برای صدا زدن سرویس پیامک، Auth برای نشست و Http::fake برای تست. فقط باید درست کنار هم قرار بگیرند. این صفحه یک پیادهسازی کامل و کوتاه را مرحلهبهمرحله میسازد: مایگریشن، سرویس، کنترلر، مسیرها و تست. آخرش هم نشان میدهد برای کاربران اپ فینگت میشود همهی این منطق، و هزینهی هر کد پیامکی، را کنار گذاشت.
ورود با پیامک لاراول از چه قطعههایی ساخته میشود؟
هر ورود با پیامک لاراول سه مرحله دارد. در مرحلهی «درخواست» شماره گرفته و اعتبارسنجی میشود، کدی تصادفی ساخته و چکیدهی آن ذخیره میشود و کد با پیامک میرود. در مرحلهی «بررسی» کاربر کد را میفرستد و سرور انقضا و تعداد تلاشها را میسنجد و چکیده را مقایسه میکند. در مرحلهی سوم، اگر همه چیز درست بود، کاربر با Auth::login وارد میشود و کد باطل میگردد.
خبر خوب این است که otp در laravel با ابزارهای خود فریمورک ساخته میشود و هر مرحله جواب آماده دارد. شما به بستهی جانبی برای رمز یکبارمصرف نیاز ندارید و کدی که در دست خودتان است، کوتاهتر و قابلفهمتر از یک بستهی عمومی میماند. فقط باید چند قاعده را از ابتدا بپذیرید: کد با مولد امن ساخته شود، چکیده ذخیره شود، هر کد انقضا و سقف تلاش داشته باشد و درخواست ارسال محدود باشد.
مسئولیت سایت شما از ساخت کد شروع میشود و با باطلکردن آن تمام میشود. رساندن پیامک به گوشی در دست شرکت پیامکی و اپراتور است و این صفحه وعدهای دربارهی آن نمیدهد.
اگر مفهوم کد یکبارمصرف برایتان تازه است، ابتدا رمز یکبار مصرف otp را بخوانید. اگر قبلاً ورود پیامکی را در PHP ساده نوشتهاید، ورود با موبایل php همین منطق را بدون فریمورک نشان میدهد و این صفحه آن را به شکل لاراولی درمیآورد.
کد را کجا نگه داریم؛ جدول یا Cache؟
برای نگهداری کدهای موقت دو انتخاب رایج در لاراول هست. هیچکدام غلط نیست؛ فقط ملاحظات متفاوتی دارند.
| موضوع | جدول پایگاهداده | Cache (مثل Redis) |
|---|---|---|
| انقضا | ستون expires_at و پاکسازی دورهای لازم است. | انقضا با TTL خودکار است و رکورد خودش پاک میشود. |
| شمارندهی تلاش | ستون attempts؛ با قفل ردیف میشود از شرایط رقابتی جلوگیری کرد. | با increment اتمی ساده است، ولی منطق تراکنشی پیچیدهتر میشود. |
| ردپا برای عیبیابی | میتوانید ببینید برای هر شماره چه شد؛ فقط بدون ذخیرهی خود کد. | با انقضا از بین میرود و ردپایی نمیماند. |
| زیرساخت | همان پایگاهدادهی فعلی؛ چیز تازهای لازم نیست. | به Redis یا Memcached نیاز دارد. |
| مناسب برای | پروژههای کوچک و متوسط، یا وقتی ردپا مهم است. | ترافیک بالا یا وقتی Redis از قبل در پروژه هست. |
در نمونهی این صفحه از جدول استفاده شده چون سادهترین مسیر برای شروع است و مایگریشن هم بخشی از آموزش لاراول به حساب میآید. اگر Cache را ترجیح دادید، همان سرویس را میشود با Cache::put و Cache::increment بازنویسی کرد و قواعد امنیتی یکی میماند.
ساخت کد یکبارمصرف در laravel؛ مایگریشن، مدل و سرویس
سه فایل لازم است. مایگریشن جدول کدها را میسازد و ستون phone را به کاربران اضافه میکند. مدل OtpCode ساده است. سرویس OtpService قلب کار است و دو متد دارد: issue برای ساخت و ارسال و verify برای بررسی.
برای ساخت کد یکبارمصرف در laravel از random_int استفاده میکنیم که منبع تصادفی امن سیستمعامل را میخواند. از Str::random یا rand برای این کار استفاده نکنید؛ هدف آنها امنیت کد نیست. چکیده را هم با Hash::make میسازیم تا اگر پایگاهداده لو برود، کدها مستقیم قابلاستفاده نباشند. توجه کنید چون کد ششرقمی فقط یک میلیون حالت دارد، سقف تلاش و انقضا اصل ماجراست و چکیده فقط لایهی دوم است.
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::create('otp_codes', function (Blueprint $t) {
$t->id();
$t->string('phone', 11)->unique();
$t->string('code_hash');
$t->timestamp('expires_at');
$t->unsignedTinyInteger('attempts')->default(0);
$t->timestamps();
});
// کاربر ورود پیامکی ایمیل و رمز ندارد (در Laravel 11 مستقیم change() کار میکند)
Schema::table('users', function (Blueprint $t) {
$t->string('phone', 11)->nullable()->unique();
$t->string('email')->nullable()->change();
$t->string('password')->nullable()->change();
});
}
public function down(): void
{
Schema::dropIfExists('otp_codes');
}
};<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
class OtpCode extends Model
{
protected $fillable = ['phone', 'code_hash', 'expires_at', 'attempts'];
protected $casts = ['expires_at' => 'datetime'];
}<?php
namespace App\Services;
use App\Models\OtpCode;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Hash;
class OtpService
{
public const TTL_MINUTES = 3;
public const MAX_ATTEMPTS = 5;
public function __construct(private SmsSender $sms)
{
}
// هر شکلی از شماره را به 09xxxxxxxxx برمیگرداند؛ در غیر این صورت null
public static function normalize(string $raw): ?string
{
$raw = strtr($raw, ['۰' => '0', '۱' => '1', '۲' => '2', '۳' => '3', '۴' => '4', '۵' => '5', '۶' => '6', '۷' => '7', '۸' => '8', '۹' => '9']);
$digits = preg_replace('/\D+/', '', $raw);
if (str_starts_with($digits, '98')) {
$digits = '0' . substr($digits, 2);
}
return preg_match('/^09\d{9}$/', $digits) ? $digits : null;
}
public function issue(string $phone): void
{
$code = str_pad((string) random_int(0, 999999), 6, '0', STR_PAD_LEFT);
OtpCode::updateOrCreate(['phone' => $phone], [
'code_hash' => Hash::make($code),
'expires_at' => now()->addMinutes(self::TTL_MINUTES),
'attempts' => 0,
]);
$this->sms->send($phone, 'کد ورود شما: ' . $code);
}
public function verify(string $phone, string $code): bool
{
// قفل ردیف میگذارد تا دو درخواست موازی نتوانند شمارنده را دور بزنند
return DB::transaction(function () use ($phone, $code) {
$row = OtpCode::where('phone', $phone)->lockForUpdate()->first();
if (! $row || $row->expires_at->isPast() || $row->attempts >= self::MAX_ATTEMPTS) {
return false;
}
if (! Hash::check($code, $row->code_hash)) {
$row->increment('attempts');
return false;
}
$row->delete(); // یکبارمصرف: بعد از اولین موفقیت باطل میشود
return true;
});
}
}ارسال پیامک با کلاس SmsSender و Http
کلاس SmsSender تنها جایی است که از سرویسدهندهی پیامکی خبر دارد. همین جداسازی تعویض سرویسدهنده و نوشتن تست را آسان میکند. فیلدها و آدرس زیر جانشیناند؛ قالب واقعی را مستندات شرکت پیامکی شما تعیین میکند. جزئیات کلی وبسرویسها در وب سرویس پیامک آمده است.
یک تصمیم آگاهانه: در این کلاس تلاش دوبارهی خودکار نداریم. برای کد ورود، اگر مهلت تمام شود و نخواهیم ندانیم پیامک رفته یا نه، تکرار میتواند دو کد متفاوت برای کاربر بفرستد. بهتر است خطا را به کاربر نشان دهیم و دکمهی «ارسال مجدد» تصمیم بگیرد.
<?php
namespace App\Services;
use Illuminate\Support\Facades\Http;
class SmsSender
{
public function send(string $phone, string $text): void
{
Http::withToken(config('services.sms.key'))
->timeout(8)
->post(config('services.sms.url'), [
'sender' => config('services.sms.sender'),
'to' => $phone,
'text' => $text,
])
->throw(); // با خطای HTTP استثنا میدهد؛ کنترلر آن را به پیام قابلفهم تبدیل میکند
}
}
// config/services.php
// 'sms' => [
// 'url' => env('SMS_API_URL'),
// 'key' => env('SMS_API_KEY'),
// 'sender' => env('SMS_SENDER'),
// ],rate limiter لاراول؛ جلوی حمله به دکمهی ارسال کد
دکمهی «ارسال کد» برای هر کسی باز است و هر بار که زده شود، به شما هزینهی یک پیامک وارد میکند. اگر محدودیتی نباشد، یک اسکریپت ساده میتواند اعتبار پیامک شما را تمام کند یا گوشی یک نفر را پر از پیام کند. rate limiter لاراول برای همین ساخته شده و دو سطح محدودیت میخواهیم.
سطح اول به ازای شماره است: حداقل ۶۰ ثانیه بین دو ارسال و حداکثر پنج ارسال در ساعت. سطح دوم به ازای آیپی است: مثلاً ده درخواست در دقیقه برای همهی مسیرهای ورود، که با میانافزار throttle ثبت میشود. هر دو لازماند چون مهاجم میتواند شماره را عوض کند یا آیپی را.
در نمونهی کنترلر بعدی هر دو سطح را میبینید. RateLimiter::attempt در هر فراخوانی شمارنده را زیاد میکند و اگر سقف پر شده باشد، تابع را اجرا نمیکند. توضیح بیشتر دربارهی این نوع حمله و راههای مقابله در جلوگیری از sms bombing آمده است.
سقف را فقط بر اساس آیپی نگذارید. شبکهی یک شرکت یا اپراتور موبایل آیپی مشترک دارد و سقف سختگیرانه ممکن است کاربران درست را هم ببندد.
لاگین با شماره موبایل لاراول؛ کنترلر و مسیرها
کنترلر نازک میماند: اعتبارسنجی ورودی، صدا زدن سرویس و ورود دادن. بهجای دو مسیر جدا برای ثبتنام و ورود، یک مسیر کافی است: اگر شماره قبلاً حساب داشته باشد، همان حساب باز میشود و اگر نداشته باشد، ساخته میشود. لاگین با شماره موبایل لاراول از همین الگو بهره میبرد و کاربر را با دو فرم رمز و ثبتنام درگیر نمیکند.
پس از Auth::login حتماً session()->regenerate() را بزنید تا شناسهی نشست قبل از ورود دیگر معتبر نباشد.
<?php
namespace App\Http\Controllers;
use App\Models\User;
use App\Services\OtpService;
use Illuminate\Http\Client\RequestException;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\RateLimiter;
class PhoneLoginController extends Controller
{
public function request(Request $request, OtpService $otp)
{
$phone = OtpService::normalize((string) $request->input('phone'));
if (! $phone) {
return back()->withErrors(['phone' => 'شمارهی موبایل معتبر نیست.']);
}
// سقف ساعتی برای هر شماره
if (RateLimiter::tooManyAttempts('otp-hour:' . $phone, 5)) {
return back()->withErrors(['phone' => 'تعداد درخواستها زیاد است؛ کمی بعد دوباره تلاش کنید.']);
}
// حداقل ۶۰ ثانیه بین دو ارسال برای هر شماره
$sent = RateLimiter::attempt('otp-cool:' . $phone, 1, function () use ($otp, $phone) {
$otp->issue($phone);
}, 60);
if (! $sent) {
return back()->withErrors(['phone' => 'برای درخواست کد تازه کمی صبر کنید.']);
}
RateLimiter::hit('otp-hour:' . $phone, 3600);
return back()->with('otp_sent', $phone);
}
public function verify(Request $request, OtpService $otp)
{
$phone = OtpService::normalize((string) $request->input('phone'));
$code = (string) $request->input('code');
if (! $phone || ! preg_match('/^\d{6}$/', $code) || ! $otp->verify($phone, $code)) {
return back()->withErrors(['code' => 'کد نادرست یا منقضی است.']);
}
$user = User::firstOrCreate(['phone' => $phone], ['name' => 'کاربر']);
Auth::login($user, true);
$request->session()->regenerate();
return redirect()->intended('/');
}
}use App\Http\Controllers\PhoneLoginController;
Route::middleware('throttle:10,1')->group(function () {
Route::post('/login/phone/request', [PhoneLoginController::class, 'request']);
Route::post('/login/phone/verify', [PhoneLoginController::class, 'verify']);
});ایمپورت RequestException در کنترلر برای مدیریت خطای ارسال است: اگر SmsSender استثنا بدهد، آن را بگیرید، پیام «ارسال کد ممکن نشد» نشان دهید و از شمارنده کم کنید تا کاربر بیدلیل در سقف نماند. جزئیات بیشتر دربارهی مدیریت کد در برنامههای واقعی را در ارسال کد تایید میبینید.
تست otp با http fake؛ بدون ارسال هیچ پیامکی
یکی از بهترین بخشهای لاراول، تست راحت آن است. Http::fake جلوی هر درخواست خروجی را میگیرد و میتوانید بررسی کنید چه چیزی قرار بود فرستاده شود. تست otp با http fake دو فایده دارد: هیچ پیامک واقعی نمیرود و کدی که برای کاربر فرستاده شده را از بدنهی درخواست ساختگی میتوانید بخوانید.
تست زیر کل مسیر موفق را اجرا میکند و بعد یک مسیر شکست را. فرض شده کلاس تست از RefreshDatabase استفاده میکند و شما مسیرها را همانطور که بالا آمد ثبت کردهاید.
<?php
namespace Tests\Feature;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
use Tests\TestCase;
class PhoneLoginTest extends TestCase
{
use RefreshDatabase;
protected function setUp(): void
{
parent::setUp();
config(['services.sms.url' => 'http://sms.invalid/send', 'services.sms.key' => 'k', 'services.sms.sender' => '1000']);
Http::fake(); // هیچ درخواست واقعی نمیرود
}
private function requestCode(string $phone): string
{
$this->post('/login/phone/request', ['phone' => $phone]);
$code = null;
Http::assertSent(function (Request $req) use (&$code) {
preg_match('/\d{6}/', $req['text'], $m);
$code = $m[0] ?? null;
return $code !== null;
});
return $code;
}
public function test_user_logs_in_with_correct_code(): void
{
$code = $this->requestCode('09120000000');
$this->post('/login/phone/verify', ['phone' => '09120000000', 'code' => $code])->assertRedirect('/');
$this->assertAuthenticated();
$this->assertDatabaseHas('users', ['phone' => '09120000000']);
$this->assertDatabaseMissing('otp_codes', ['phone' => '09120000000']); // کد باطل شده است
}
public function test_code_is_locked_after_five_wrong_attempts(): void
{
$code = $this->requestCode('09120000001');
for ($i = 0; $i < 5; $i++) {
$this->post('/login/phone/verify', ['phone' => '09120000001', 'code' => '000000']);
}
$this->post('/login/phone/verify', ['phone' => '09120000001', 'code' => $code]);
$this->assertGuest();
$this->assertSame(0, User::count());
}
}در حالت دوم، حتی کد درست هم بعد از پنج تلاش اشتباه کار نمیکند. همین تست مطمئن میکند اگر روزی کسی منطق سقف را ناخواسته بشکند، همان لحظه معلوم شود. تست دیگری هم بنویسید که ثابت کند کد منقضیشده رد میشود؛ با Carbon::setTestNow میتوانید زمان را جلو ببرید.
اشتباههای رایج در لاگین پیامکی لاراول
این چهار مورد را در بازبینی پروژههای لاراولی بیش از همه میبینیم و هر کدام با تغییری کوچک رفع میشود.
ذخیرهی خود کد در پایگاهداده
اگر پایگاهداده یا بکاپ لو برود، همهی کدهای فعال قابلاستفادهاند. فقط چکیده را ذخیره کنید و بعد از موفقیت ردیف را حذف کنید.
نبودن سقف تلاش
بدون سقف، شش رقم در چند دقیقه با اسکریپت حدس زده میشود. شمارندهی attempts و قفل بعد از پنج بار اشتباه، مهمترین قطعه است.
فراموشکردن regenerate نشست
بعد از Auth::login نشست را بازتولید کنید تا شناسهی نشست از قبل از ورود دیگر معتبر نباشد.
لو دادن وجود حساب
پیام «این شماره ثبت نشده» به مهاجم میگوید کدام شمارهها کاربر دارند. با مسیر ترکیبی ورود و ثبتنام این مشکل هم از بین میرود.
ورود با پیامک لاراول را کی خودتان بنویسید و کی نه؟
نوشتن این منطق چند ساعت وقت میگیرد و پس از آن همیشه مال شماست: باید نگهداری شود، هزینهی هر پیام را بپردازید و برای کدهایی که نرسیده پشتیبانی بدهید. این هزینه برای بعضی پروژهها توجیه دارد و برای بعضی نه.
خودتان بنویسید، اگر
- همهی کاربران شما موبایل دارند اما اپ ندارند و پیامک تنها راه مطمئن رسیدن به آنهاست.
- میخواهید روی جزئیات تجربهی ورود و ذخیرهی داده کنترل کامل داشته باشید.
- تیم شما توان نگهداری از جدول کد، سقفها و تماس با شرکت پیامکی را دارد.
فکر دوباره کنید، اگر
- بخش بزرگی از کاربران شما اپ را دارند و میتوانند ورود را در گوشی تأیید کنند.
- هزینهی پیامک و شکایت «کد نمیآید» وقت زیادی از تیم میگیرد؛ نگاه کنید به کد تایید نمیاد.
- میخواهید ورود را سریعتر و بدون نیاز به انتظار برای پیامک کنید.
ورود با فینگت؛ بدون ساخت کد و بدون پیامک
روش کار فینگت شبیه ورود با گوگل است. سایت شما کاربر را به finget.ir میفرستد، کاربر دارندهی اپ ورود را در گوشی خودش تأیید میکند و مرورگر او با یک کد کوتاهعمر، حدود دو دقیقه، به آدرس بازگشت سایت شما برمیگردد. سرور شما این کد را با یک درخواست POST تبدیل به نام، شمارهی تأییدشده و یک شناسهی ثابت برای همین سایت میکند.
در این مسیر نه جدول کد دارید، نه RateLimiter برای دکمهی ارسال، نه SmsSender و نه هزینهی هر ورود. فینگت سرویس پیامک نیست و خط یا پنل پیامکی نمیفروشد؛ برای کاربرانی که اپ را دارند، پیامک ورود را حذف میکند. اپ فعلاً برای اندروید است، پس فرم پیامکی خودتان را برای بقیهی کاربران نگه دارید و دکمهی فینگت را کنار آن بگذارید. اگر سایت شما وردپرس یا ووکامرس است، افزونهی آمادهای هست که همین کار را بدون کدنویسی انجام میدهد؛ ورود با شماره موبایل وردپرس مسیر آن را شرح میدهد.
نمونهی ورود با فینگت در Laravel
دو مسیر کافی است. شناسهی سایت و کلید API را از پنل سرویسدهندگان فینگت میگیرید و آدرس بازگشت را هم همانجا ثبت میکنید. نمونه فرض میکند ستونی به نام finget_id (رشتهی یکتا و nullable) به جدول کاربران اضافه کردهاید و کلیدها را در config/services.php زیر نام finget خواندهاید.
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;
Route::get('/login/finget', function (Request $request) {
$request->session()->put('fg_state', $state = Str::random(32)); // برای جلوگیری از درخواست جعلی
return redirect('https://finget.ir/auth?' . http_build_query([
'client_id' => config('services.finget.site_id'),
'state' => $state,
]));
});
// همین آدرس را در پنل سرویسدهندگان بهعنوان آدرس بازگشت ثبت کنید
Route::get('/login/finget/callback', function (Request $request) {
$expected = $request->session()->pull('fg_state');
abort_unless($expected && hash_equals($expected, (string) $request->query('state')), 400);
$res = Http::withToken(config('services.finget.key'))
->timeout(8)
->post('https://finget.ir/api/v1/auth/token', ['code' => (string) $request->query('code')]);
abort_unless($res->ok() && $res->json('user.id'), 401);
// user شامل id، name و phone است؛ با شناسهی ثابت، کاربر را پیدا یا بسازید
$user = User::firstOrCreate(
['finget_id' => $res->json('user.id')],
['name' => $res->json('user.name') ?: 'کاربر'],
);
Auth::login($user, true);
$request->session()->regenerate();
return redirect('/');
});اگر هر دو روش ورود در یک جدول کاربران کار میکنند، شمارهی دریافتی از فینگت را پیش از مقایسه با شمارههای ورود پیامکی به همان قالب یکسان تبدیل کنید و تصمیم بگیرید حسابهای همشماره یکی شوند یا نه. مفهوم کلی این روش در ورود بدون رمز عبور آمده و مقایسهاش با کد پیامکی در جایگزین otp پیامکی است. برای دیدن اپ هم صفحهی دانلود را باز کنید.
پرسشهای متداول درباره ورود با پیامک لاراول
ورود با پیامک لاراول به بستهی جانبی نیاز دارد؟
نه. Hash، RateLimiter، Http، Auth و ابزارهای تست همه در خود لاراول هستند. بستههای آماده کار را سریعتر شروع میکنند ولی منطق را از دید شما پنهان میکنند؛ برای ورود پیامکی که امنیت به آن تکیه دارد، کدی که خودتان بخوانید و بفهمید ارزش دارد.
چرا کد را با random_int بسازیم و نه Str::random؟
random_int از منبع تصادفی امن سیستمعامل میخواند و برای کدهایی که امنیت به آنها وابسته است درست است. Str::random برای رشتههای عمومی مثل شناسه ساخته شده و هدفش امنیت کد یکبارمصرف نیست؛ rand و mt_rand هم قابلپیشبینیاند.
چرا از lockForUpdate استفاده شده است؟
اگر مهاجم چند درخواست بررسی را همزمان بفرستد، بدون قفل ممکن است همهی آنها شمارندهی قدیمی را بخوانند و سقف پنج تلاش دور زده شود. قفل ردیف داخل تراکنش، درخواستها را پشت سر هم میکند.
چطور بدون ارسال واقعی تست بنویسم؟
با Http::fake جلوی درخواست خروجی را بگیرید و با Http::assertSent بدنهی آن را بخوانید. اینطور هم میفهمید پیامک قرار بود با چه متنی برود، هم کد را برای ادامهی تست از همان میگیرید و هیچ پیام واقعی نمیرود.
زمان انقضای مناسب برای کد چقدر است؟
سه تا پنج دقیقه رایج است. کمتر از آن ممکن است پیامک دیررسیده را بیاثر کند و بیشتر از آن فرصت سوءاستفاده از کدی که کسی دیده را بیشتر میکند.
فینگت پیامک ورود را کامل حذف میکند؟
فقط برای کاربرانی که اپ فینگت دارند. اپ فعلاً برای اندروید است، پس معمولاً دکمهی فینگت کنار ورود پیامکی میماند، نه جای آن. فینگت پنل یا خط پیامکی هم نمیفروشد.