وقتی می خواهی یک API یا پنل کاربری بسازی، اولین چیزی که به آن برمی خوری این است که احراز هویت را چطور پیاده کنی که هم امن باشد و هم دردسر اضافه درست نکند. اینجاست که لاراول sanctum به درد می خورد. لاراول sanctum یک روش ساده و استاندارد برای مدیریت ورود کاربران، صدور توکن و حفاظت از مسیرهای API است، مخصوصا وقتی با SPA یا اپ موبایل سروکار داری.

لاراول sanctum چیست و دقیقا چه کاری انجام می دهد

لاراول sanctum پکیج رسمی لاراول برای احراز هویت است که دو سناریوی مهم را خیلی تمیز پوشش می دهد. سناریوی اول، احراز هویت SPA با کوکی و سشن است. یعنی فرانت مثل React یا Vue روی یک دامنه یا زیر دامنه مشخص اجرا می شود و با کوکی امن لاگین می کند. سناریوی دوم، احراز هویت مبتنی بر توکن برای API است. یعنی برای اپ موبایل یا سرویس های خارجی، به کاربر یک توکن می دهی و هر درخواست با همان توکن اعتبارسنجی می شود.

چه زمانی لاراول sanctum انتخاب خوبی است

اگر پروژه تو یکی از این حالت هاست، Sanctum معمولا انتخاب خوبی است. وقتی یک SPA داری و دوست داری احراز هویت شبیه وب کلاسیک باشد اما با API کار کنی. وقتی اپ موبایل داری و می خواهی توکن ساده و قابل مدیریت داشته باشی. وقتی نمی خواهی وارد پیچیدگی OAuth2 و پکیج هایی مثل Passport شوی. Sanctum سبک تر است و برای خیلی از پروژه ها دقیقا همان چیزی است که لازم داری.

پیش نیازهای درست قبل از شروع

قبل از نصب، باید مشخص کنی سیستم تو کدام مدل را می خواهد. اگر SPA است، مسیر درخواست ها معمولا با کوکی و CSRF امن می شود و نباید با توکن Bearer قاطی شود. اگر موبایل یا کلاینت خارجی است، مدل توکن شخصی بهتر است. این تصمیم روی تنظیمات فایل ها و میدلورهای تو اثر مستقیم دارد.

نصب و راه اندازی لاراول sanctum

برای شروع باید پکیج را نصب کنی و فایل های لازم را منتشر کنی. بعد جدول های مرتبط با توکن ساخته می شوند و می توانی migration را اجرا کنی. در مرحله بعد، میدلورهای مربوط به Sanctum را در کرنل پروژه فعال می کنی تا درخواست های API بتوانند احراز هویت شوند.

تنظیم Sanctum برای SPA مبتنی بر کوکی

اگر فرانت و بک اند جدا هستند، باید دامنه هایی که اجازه دارند با کوکی احراز هویت شوند مشخص شوند. همچنین تنظیمات مربوط به CORS باید درست باشد تا مرورگر اجازه ارسال کوکی را بدهد. در این مدل، Sanctum به جای Bearer Token از سشن و کوکی استفاده می کند و موضوع CSRF خیلی مهم می شود. باید مطمئن شوی که فرانت قبل از لاگین، کوکی CSRF را دریافت می کند و درخواست های بعدی را همراه آن ارسال می کند.

مسیرهای مهم در سناریوی SPA

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

تنظیم Sanctum برای توکن های API

برای اپ موبایل یا سرویس های خارجی، Sanctum توکن شخصی می سازد. کاربر لاگین می کند و یک توکن دریافت می کند. از آن لحظه به بعد، هر درخواست باید هدر Authorization با مقدار Bearer Token داشته باشد. این مدل برای کلاینت هایی که کوکی ندارند یا خارج از مرورگر هستند، بهترین انتخاب است.

ساخت API برای ثبت نام و ورود

در عمل تو دو مسیر مهم داری. ثبت نام که کاربر را می سازد و ورود که اعتبار کاربر را بررسی می کند و توکن صادر می کند. توکن را می توانی با نام مشخص و سطح دسترسی بسازی. Sanctum امکان این را دارد که برای هر دستگاه یا اپ، توکن جدا داشته باشی و در صورت نیاز آنها را revoke کنی.

محافظت از مسیرهای API با میدلور auth

بعد از صدور توکن یا ایجاد سشن، باید مسیرهای حساس را محافظت کنی. این کار با میدلور auth انجام می شود. هر مسیری که پشت این میدلور باشد، فقط با کاربر لاگین شده قابل دسترسی است. این بخش ساده است اما مهم است که درست در routes/api یا routes/web قرار بگیرد تا رفتار مورد انتظار را داشته باشد.

مدیریت سطح دسترسی و توانایی ها

Sanctum به تو اجازه می دهد روی توکن ها توانایی تعریف کنی. مثلا یک توکن فقط اجازه خواندن داشته باشد و دیگری اجازه نوشتن. این موضوع در پروژه های واقعی خیلی کاربردی است، چون همیشه لازم نیست همه توکن ها دسترسی کامل داشته باشند. با این روش می توانی ریسک را کم کنی.

امنیت در پیاده سازی لاراول sanctum

چند نکته امنیتی در Sanctum حیاتی است. توکن را در کلاینت به صورت امن نگه دار. برای SPA از HTTPS استفاده کن تا کوکی ها در مسیر امن منتقل شوند. در CORS فقط دامنه های لازم را مجاز کن. لاگ ها را طوری تنظیم کن که توکن ها لو نروند. و مهم تر از همه، مسیرهای حساس را حتما پشت احراز هویت و سطح دسترسی درست قرار بده.

خطاهای رایج در کار با Sanctum

یکی از رایج ترین خطاها قاطی کردن مدل کوکی و مدل توکن است. مثلا فرانت SPA با Bearer Token کار کند و همزمان CSRF را هم نصفه اجرا کند. خطای رایج دیگر، تنظیم اشتباه CORS و دامنه های stateful است که باعث می شود کوکی اصلا ست نشود یا درخواست ها 401 شوند. همچنین خیلی ها فراموش می کنند که جدول های Sanctum را migrate کنند و بعد دنبال باگ می گردند.

تست و دیباگ سریع

برای تست توکن ها می توانی از Postman یا Thunder Client استفاده کنی. اول لاگین، بعد گرفتن توکن، بعد ارسال درخواست با Authorization. برای مدل SPA هم باید شبکه مرورگر را چک کنی که کوکی ها ارسال می شوند و پاسخ 419 یا 401 نمی گیری. اگر این دو تست را درست انجام دهی، خیلی از مشکلات همان اول مشخص می شوند.

جمع بندی

لاراول sanctum یک روش تمیز و سبک برای احراز هویت در لاراول است. هم برای SPA با کوکی و CSRF مناسب است و هم برای API با توکن. اگر تصمیم بگیری کدام سناریو برای پروژه توست و تنظیمات CORS و میدلورها را درست انجام دهی، پیاده سازی احراز هویت با Sanctum هم سریع جلو می رود و هم امن باقی می ماند.