يأتي Laravel بحزمتين رسميتين لمصادقة الـ API، والاختيار بينهما يُتخذ خطأً أكثر من أي قرار مبكر آخر في Laravel API. هذه المقالة موجّهة للمطوّرين والقادة التقنيين الذين يبدؤون API ستستدعيه واجهة ويب أو تطبيق جوال أو طرف ثالث، وتقدّم جواباً مباشراً: استخدم Sanctum ما لم تكن تبني مزوّد OAuth، واعرف بالضبط ما يعنيه ذلك قبل أن تقرر أنك كذلك.
ما الفرق بين Sanctum وPassport؟
يفعل Sanctum شيئين. يتيح لتطبيق صفحة واحدة تابع لك المصادقة بكعكة الجلسة العادية، ويصدر رموز وصول شخصية بسيطة لتطبيقات الجوال والسكربتات والتكاملات. يخزّن الرموز كسلاسل مجزّأة في جدول، ولا مفهوم لديه للعملاء أو المنح، ويضيف وسيطاً واحداً.
أما Passport فخادم OAuth2 كامل. ينفّذ رموز التفويض، ورموز التحديث، وبيانات اعتماد العميل، وPKCE، والنطاقات، وشاشة الموافقة التي يراها المستخدم حين يطلب تطبيق طرف ثالث التصرف نيابة عنه. وهو الأداة الصحيحة حين تحتاج برمجيات الآخرين إلى الوصول إلى الـ API نيابة عن مستخدميك. وهو آلية ضخمة حين تكون واجهاتك وحدها من تفعل ذلك.
الفرق ليس الأمان. فكلاهما آمن حين يُضبط بشكل صحيح. الفرق في المشكلة التي يحلها كل منهما.
كيف ينبغي أن يصادق تطبيق SPA مع Laravel؟
إن كانت واجهة Next.js أو Vue لديك تعيش على النطاق الأعلى نفسه الذي يعيش عليه الـ API، فاستخدم وضع الكعكة في Sanctum ولا رموز على الإطلاق. يرسل المتصفح كعكة الجلسة؛ ويتحقق Laravel من رمز CSRF؛ ولا شيء يُخزَّن في local storage ولا شيء يسرقه سكربت حُقن في الصفحة. هكذا تتحدث واجهات Next.js لدينا مع Laravel: كعكة same-site، وwithCredentials في العميل، وSANCTUM_STATEFUL_DOMAINS يسرد مضيفي الواجهة، واستدعاء /sanctum/csrf-cookie قبل أول تسجيل دخول.
اضبط النطاقات أولاً. الكعكة محدودة بنطاق الـ API، لذا يعمل app.example.com مع api.example.com؛ ولا يعمل example.com مع example-api.com، والإصلاح في DNS لا في الكود. اضبط SESSION_DOMAIN على الأصل المشترك بنقطة في البداية، وتأكد أن SESSION_SECURE_COOKIE مفعّل في الإنتاج.
ماذا عن تطبيقات الجوال والرموز؟
لا تستطيع تطبيقات الجوال استخدام جلسة الكعكة، فتستخدم رموز الوصول الشخصية في Sanctum. يرسل التطبيق بيانات الاعتماد إلى نقطة دخول، ويتلقى رمزاً نصياً مرة واحدة، ويخزّنه في التخزين الآمن للمنصة (Keychain أو Keystore)، ويرسله كترويسة bearer. رمز واحد لكل جهاز، مسمّى باسم الجهاز، ليستطيع المستخدم رؤية جلساته وإلغاءها.
امنح الرموز قدرات وتاريخ انتهاء. فـ createToken('ios', ['orders:read', 'orders:write']) يحدّ ما يستطيع الرمز فعله؛ وexpires_at مع أمر sanctum:prune-expired يبقي الجدول نظيفاً ويحدّ من أثر رمز مسرّب. ألغِ كل الرموز عند تغيير كلمة المرور. قدرات Sanctum خشنة وتُفحص في كودك بـ tokenCan، وهذا كافٍ لتطبيق تابع لك وأبسط بكثير من نطاقات Passport.
متى تحتاج فعلاً إلى Passport وOAuth؟
تحتاج إلى Passport حين يكون جواب «من يستدعي الـ API؟» هو «تطبيق لا نتحكم به، نيابة عن مستخدم يجب أن يوافق». شركاء يتكاملون مع منصتك، وبرنامج مطوّرين عام، ومتجر تطبيقات، وتسجيل دخول موحّد حيث أنت مزوّد الهوية. في هذه الحالات تحتاج إلى تسجيل العملاء، والتحقق من عناوين إعادة التوجيه، ومنحة رمز التفويض مع PKCE، وموافقة بنطاقات، ورموز تحديث، ويمنحك Passport كل ذلك بصيغة يفهمها المطوّرون الخارجيون أصلاً.
صمّم النطاقات كأسماء وأفعال يقرؤها الشريك: invoices:read وcustomers:write. أبقِ رموز الوصول قصيرة العمر ورموز التحديث قابلة للإلغاء. احتفظ بمنحة بيانات اعتماد العميل للتكاملات بين الخوادم بلا مستخدم في الحلقة، ولا تسلّم سر العميل أبداً لتطبيق جوال أو متصفح؛ فلهذا وُجد PKCE.
وإن كنت تحتاج إلى استهلاك OAuth لدى غيرك (تسجيل الدخول بـ Google، أو الربط بمنصة محاسبة)، فذلك Socialite أو مكتبة عميل، لا Passport. فـ Passport فقط لحين تكون أنت المزوّد.
ما الأخطاء الشائعة مع Sanctum وPassport؟
- تشغيل الاثنين لأن درساً تعليمياً قال ذلك. اختر واحداً لكل API. حارسا مصادقة على المسارات نفسها مصدر لأخطاء 401 محيّرة وسطح هجوم أوسع.
- تخزين رمز Sanctum في local storage لتطبيق SPA على النطاق نفسه. استخدم الكعكة؛ هذا هو المغزى كله.
- رموز لا تنتهي أبداً. اضبط
expirationفي إعداد Sanctum أو لكل رمز، ونظّف. - نسيان
EnsureFrontendRequestsAreStatefulفي مجموعة وسائط الـ API، ثم التساؤل لماذا تُتجاهل الكعكة. - معاملة القدرات كتفويض.
tokenCan('orders:write')يقول ما يجوز للرمز محاولته؛ والـ policy تقول ما إذا كان يجوز لهذا المستخدم لمس هذا الطلب. تحتاج إلى الاثنين. - اختيار Passport «تحسباً لحاجتنا إلى OAuth لاحقاً». الانتقال من Sanctum إلى Passport حين تحتاجه عمل محدود؛ أما حمل Passport لسنوات من أجل SPA واحد فضريبة دائمة.
المصادقة تُحسم في الأسبوعين الأولين ويُعاش معها طوال عمر المنتج، ولهذا فهي من الأمور التي نحسمها في ورشة الاكتشاف قبل تسعير أي نطاق.