React + Laravel Sanctum: حل مشاكل CSRF وتوثيق الجلسات في تطبيقات SPA

في هذا المقال، سأرشدك خطوة بخطوة لكيفية جعل التوثيق يعمل بسلاسة بين React وLaravel باستخدام Sanctum، مع دعم التوكن عبر الكوكيز وحماية CSRF.

سنتناول المواضيع التالية:

• كيف يعمل Laravel Sanctum
• إعداد Laravel للتوثيق عبر SPA
• كيفية إرسال الكوكيز من React بشكل آمن
• التعامل مع تبادل رموز CSRF
• معالجة المشاكل الشائعة
• حالات خاصة قد تواجهك أثناء التطوير

🔒 لماذا نستخدم Laravel Sanctum؟

Sanctum هو نظام توثيق خفيف من Laravel مصمم لتطبيقات SPA وتطبيقات الجوال وواجهات API البسيطة.

يدعم طريقتين:

• نمط التوكن (API Tokens) – لتطبيقات الطرف الثالث أو الجوال
• نمط الكوكيز (Cookie-based session) – الأفضل لتطبيقات SPA مثل React

في حالة تطبيقات SPA، يستخدم Sanctum كوكيز الجلسة ورمز CSRF لحماية المستخدم.

💡 لا حاجة لتخزين التوكنات يدويًا أو التعامل مع تجديدها.

🧠 كيف يعمل Sanctum في نمط SPA

الصورة العامة للتوثيق عبر Sanctum في SPA كالتالي:

1. تطلب SPA /sanctum/csrf-cookie
2. يرد Laravel بكوكيز يحتوي على رمز CSRF
3. تُرسل SPA بيانات تسجيل الدخول إلى /login مع رمز CSRF
4. يعيد Laravel كوكيز جلسة
5. كل الطلبات التالية ترسل الكوكيز تلقائيًا

🛠️ إعداد Laravel Sanctum

1. تثبيت Sanctum

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

2. تفعيل الميدل وير

في app/Http/Kernel.php تأكد من إضافة:

use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful;

'api' => [
    EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

3. ضبط sanctum.php

افتح config/sanctum.php وعدل:

'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', 'localhost:3000,127.0.0.1:3000')),

وفي ملف .env:

SANCTUM_STATEFUL_DOMAINS=localhost:3000,yourdomain.com

4. ضبط CORS

في config/cors.php:

'paths' => ['api/*', 'sanctum/csrf-cookie'],
'allowed_methods' => ['*'],
'allowed_origins' => ['http://localhost:3000'],
'allowed_headers' => ['*'],
'supports_credentials' => true,

⚛️ إعداد React للعمل مع Sanctum

1. تثبيت Axios

npm install axios

2. إنشاء ملف axios.js

import axios from 'axios';

axios.defaults.withCredentials = true;
axios.defaults.baseURL = 'http://localhost:8000'; // رابط Laravel

export default axios;

3. الحصول على رمز CSRF

import axios from './axios';

export const getCsrfToken = async () => {
  await axios.get('/sanctum/csrf-cookie');
};

4. تسجيل الدخول

export const login = async (email, password) => {
  await getCsrfToken(); // الحصول على رمز CSRF

  const response = await axios.post('/login', { email, password });
  return response.data;
};

بعد نجاح تسجيل الدخول، Laravel يُرسل كوكيز الجلسة تلقائيًا.

🔐 حماية المسارات في Laravel

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

🧪 تسجيل الخروج

export const logout = async () => {
  await axios.post('/logout');
};

Laravel سيتعامل مع إنهاء الجلسة وحذف الكوكيز.

💡 مشاكل شائعة وحالات خاصة

1. الكوكيز لا تُرسل

• تأكد من axios.defaults.withCredentials = true
• Laravel يجب أن يرسل الكوكيز مع SameSite=None و Secure عند استخدام HTTPS
• يجب تطابق النطاقات بين الواجهة الأمامية والخلفية أو تضمينها في SANCTUM_STATEFUL_DOMAINS

2. CSRF Token mismatch

• تأكد دائمًا من استدعاء /sanctum/csrf-cookie قبل إرسال أي POST
• Axios يتعامل مع إرسال الرمز تلقائيًا بعد تخزين الكوكيز

3. مشكلة CORS

• تحقق من أن cors.php يسمح بالنطاق الصحيح
• supports_credentials يجب أن تكون true

4. فرق بين بيئة التطوير والإنتاج

في التطوير:

FRONTEND: http://localhost:3000
BACKEND: http://localhost:8000

في الإنتاج:

• استخدم HTTPS
• اضبط SESSION_DOMAIN و SESSION_SECURE_COOKIE
• تأكد من تفعيل CSRF و CORS بشكل سليم

✅ قائمة التحقق النهائية

• ضبط .env بشكل صحيح
• تفعيل HTTPS في الإنتاج
• إضافة النطاقات في SANCTUM_STATEFUL_DOMAINS
• اختبار إرسال الكوكيز والرمز

🔚 الختام

من خلال Laravel Sanctum، يمكنك إنشاء نظام توثيق آمن وفعال دون الحاجة لإدارة التوكنات يدويًا. إنه متكامل مع نظام الجلسات في Laravel، ويوفر تجربة مستخدم سلسة لتطبيقات React.

إذا واجهت مشاكل أثناء التطبيق، أو لديك حالات خاصة لم تُذكر، لا تتردد في مشاركتها.

تصفح المزيد من المقالات على kaisalhusrom.com 🚀