لاراول پناهگاه

معرفی
- چگونه کار می کند
نصب و راه اندازی
پیکربندی
- نادیده گرفتن مدل های پیش فرض
API Token Authentication
احراز هویت SPA
احراز هویت اپلیکیشن موبایل
آزمایش کردن

معرفی

Laravel Sanctum یک سیستم احراز هویت پر وزن برای SPA ها (برنامه های تک صفحه ای)، برنامه های کاربردی تلفن همراه و API های ساده و مبتنی بر توکن ارائه می کند. Sanctum به هر کاربر برنامه شما اجازه می دهد تا چندین توکن API برای حساب خود ایجاد کند. ممکن است به این نشانه‌ها توانایی‌ها/حوزه‌هایی داده شود که مشخص می‌کند توکن‌ها مجاز به انجام چه اقداماتی هستند.

چگونه کار می کند

Laravel Sanctum برای حل دو مشکل جداگانه وجود دارد. بیایید قبل از کاوش بیشتر در کتابخانه در مورد هر کدام بحث کنیم.

توکن های API

اول، Sanctum یک بسته ساده است که می‌توانید از آن برای صدور توکن‌های API برای کاربران خود بدون پیچیدگی OAuth استفاده کنید. این ویژگی با الهام از GitHub و سایر برنامه‌هایی است که "توکن‌های دسترسی شخصی" را صادر می‌کنند. برای مثال، تصور کنید «تنظیمات حساب» برنامه شما دارای صفحه‌ای است که در آن کاربر ممکن است یک توکن API برای حساب خود ایجاد کند. می توانید از Sanctum برای تولید و مدیریت آن توکن ها استفاده کنید. این توکن‌ها معمولاً دارای زمان انقضای بسیار طولانی (سال‌ها) هستند، اما ممکن است هر زمان که بخواهد توسط کاربر به صورت دستی لغو شوند.

Laravel Sanctum این ویژگی را با ذخیره توکن‌های API کاربر در یک جدول پایگاه داده و احراز هویت درخواست‌های HTTP دریافتی از طریق هدر Authorization که باید حاوی یک نشانه API معتبر باشد، ارائه می‌کند.

احراز هویت SPA

دوم، Sanctum برای ارائه یک راه ساده برای تأیید اعتبار برنامه‌های تک صفحه‌ای (SPA) که نیاز به برقراری ارتباط با API مبتنی بر لاراول دارند، وجود دارد. این SPA ها ممکن است در همان مخزن برنامه Laravel شما وجود داشته باشند یا ممکن است یک مخزن کاملاً مجزا باشند، مانند SPA که با استفاده از Vue CLI یا یک برنامه Next.js ایجاد شده است.

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

Sanctum تنها زمانی با استفاده از کوکی‌ها احراز هویت را انجام می‌دهد که درخواست دریافتی از frontend SPA شما باشد. وقتی Sanctum یک درخواست HTTP ورودی را بررسی می‌کند، ابتدا یک کوکی احراز هویت را بررسی می‌کند و اگر هیچ کدام وجود نداشته باشد، Sanctum هدر را Authorization برای یک توکن معتبر API بررسی می‌کند.

استفاده از Sanctum فقط برای احراز هویت توکن API یا فقط برای احراز هویت SPA کاملاً خوب است. فقط به این دلیل که از Sanctum استفاده می کنید به این معنی نیست که شما ملزم به استفاده از هر دو ویژگی آن نیستید.

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

می توانید Laravel Sanctum را از طریق install:api دستور Artisan نصب کنید:

php artisan install:api

در مرحله بعد، اگر قصد دارید از Sanctum برای احراز هویت یک SPA استفاده کنید، لطفاً به بخش تأیید اعتبار SPA در این مستندات مراجعه کنید.

پیکربندی

نادیده گرفتن مدل های پیش فرض

اگرچه معمولاً مورد نیاز نیست، اما می‌توانید PersonalAccessToken مدل مورد استفاده داخلی توسط Sanctum را گسترش دهید:

use Laravel\Sanctum\PersonalAccessToken as SanctumPersonalAccessToken;
 
class PersonalAccessToken extends SanctumPersonalAccessToken
{
    // ...
}

سپس، ممکن است به Sanctum دستور دهید که از مدل سفارشی شما از طریق usePersonalAccessTokenModel روش ارائه شده توسط Sanctum استفاده کند. به طور معمول، شما باید این متد را در boot متد فایل برنامه خود فراخوانی کنید AppServiceProvider :

use App\Models\Sanctum\PersonalAccessToken;
use Laravel\Sanctum\Sanctum;
 
/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Sanctum::usePersonalAccessTokenModel(PersonalAccessToken::class);
}

API Token Authentication

شما نباید از نشانه های API برای احراز هویت SPA شخص اول خود استفاده کنید. در عوض، از ویژگی‌های احراز هویت داخلی SPA Sanctum استفاده کنید .

صدور توکن های API

Sanctum به شما امکان می‌دهد تا توکن‌های API/توکن‌های دسترسی شخصی را صادر کنید که ممکن است برای احراز هویت درخواست‌های API به برنامه شما استفاده شوند. هنگام درخواست با استفاده از توکن‌های API، توکن باید در Authorization هدر به‌عنوان یک Bearer توکن درج شود.

برای شروع صدور توکن برای کاربران، مدل کاربر شما باید از این Laravel\Sanctum\HasApiTokens ویژگی استفاده کند:

use Laravel\Sanctum\HasApiTokens;
 
class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

برای صدور توکن، می توانید از این createToken روش استفاده کنید. متد createToken یک Laravel\Sanctum\NewAccessToken نمونه را برمی گرداند. توکن‌های API قبل از ذخیره شدن در پایگاه داده شما با استفاده از هش SHA-256 هش می‌شوند، اما می‌توانید با استفاده از plainTextToken ویژگی NewAccessToken نمونه به مقدار متن ساده توکن دسترسی پیدا کنید. شما باید این مقدار را بلافاصله پس از ایجاد توکن به کاربر نمایش دهید:

use Illuminate\Http\Request;
 
Route::post('/tokens/create', function (Request $request) {
    $token = $request->user()->createToken($request->token_name);
 
    return ['token' => $token->plainTextToken];
});

tokens شما می توانید با استفاده از رابطه Eloquent ارائه شده توسط این ویژگی به تمام نشانه های کاربر دسترسی داشته باشید HasApiTokens :

foreach ($user->tokens as $token) {
    // ...
}

قابلیت های توکن

Sanctum به شما امکان می دهد "توانایی" را به نشانه ها اختصاص دهید. توانایی‌ها هدفی مشابه «محدوده‌های OAuth» دارند. می توانید آرایه ای از توانایی های رشته ای را به عنوان آرگومان دوم به createToken متد ارسال کنید:

return $user->createToken('token-name', ['server:update'])->plainTextToken;

هنگام رسیدگی به یک درخواست ورودی که توسط Sanctum احراز هویت شده است، می‌توانید با استفاده از روش زیر تعیین کنید که آیا توکن دارای توانایی خاصی است tokenCan :

if ($user->tokenCan('server:update')) {
    // ...
}

میان افزار توانایی توکن

Sanctum همچنین شامل دو میان‌افزار است که ممکن است برای تأیید صحت یک درخواست دریافتی با توکنی استفاده شود که توانایی مشخصی به آن داده شده است. برای شروع، نام مستعار میان افزار زیر را در bootstrap/app.php فایل برنامه خود تعریف کنید:

use Laravel\Sanctum\Http\Middleware\CheckAbilities;
use Laravel\Sanctum\Http\Middleware\CheckForAnyAbility;
 
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'abilities' => CheckAbilities::class,
        'ability' => CheckForAnyAbility::class,
    ]);
})

میان‌افزار abilities ممکن است به مسیری اختصاص داده شود تا تأیید کند که رمز درخواست ورودی همه توانایی‌های فهرست‌شده را دارد:

Route::get('/orders', function () {
    // Token has both "check-status" and "place-orders" abilities...
})->middleware(['auth:sanctum', 'abilities:check-status,place-orders']);

میان ability افزار ممکن است به مسیری اختصاص داده شود تا تأیید کند که رمز درخواست ورودی حداقل یکی از توانایی های فهرست شده را دارد:

Route::get('/orders', function () {
    // Token has the "check-status" or "place-orders" ability...
})->middleware(['auth:sanctum', 'ability:check-status,place-orders']);

درخواست‌های آغاز شده از UI شخص اول

برای راحتی کار، اگر درخواست احراز هویت شده دریافتی از SPA شخص اول شما باشد و از احراز هویت داخلی Sanctum در SPA tokenCan استفاده می‌کنید، این روش همیشه برمی‌گردد . true

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

به عنوان مثال، اگر برنامه‌ای را تصور کنیم که سرورها را مدیریت می‌کند، این ممکن است به معنای بررسی این باشد که آیا توکن برای به‌روزرسانی سرورها مجاز است و آیا سرور متعلق به کاربر است:

return $request->user()->id === $server->user_id &&
       $request->user()->tokenCan('server:update')

در ابتدا، اجازه دادن به tokenCan متد برای فراخوانی و بازگشت همیشه true برای درخواست‌های آغاز شده توسط UI شخص اول ممکن است عجیب به نظر برسد. با این حال، راحت است که بتوان همیشه فرض کرد که یک توکن API در دسترس است و می توان از طریق این tokenCan روش بازرسی کرد. با اتخاذ این رویکرد، می‌توانید همیشه tokenCan روش را در خط‌مشی‌های مجوز برنامه خود فراخوانی کنید، بدون اینکه نگران این باشید که آیا درخواست از UI برنامه شما راه‌اندازی شده است یا توسط یکی از مصرف‌کنندگان شخص ثالث API شما آغاز شده است.

حفاظت از مسیرها

برای محافظت از مسیرها به طوری که تمام درخواست های دریافتی باید احراز هویت شوند، باید sanctum محافظ احراز هویت را به مسیرهای محافظت شده خود در فایل های مسیر routes/web.php و routes/api.php مسیر خود متصل کنید. اگر درخواست از طرف شخص ثالث باشد، این محافظ اطمینان حاصل می‌کند که درخواست‌های دریافتی به‌عنوان درخواست‌های احراز هویت شده یا احراز هویت کوکی تأیید می‌شوند یا حاوی یک سرآیند توکن API معتبر هستند.

ممکن است تعجب کنید که چرا پیشنهاد می کنیم مسیرهای موجود در routes/web.php فایل برنامه خود را با استفاده از sanctum گارد احراز هویت کنید. به یاد داشته باشید که Sanctum ابتدا سعی می کند درخواست های دریافتی را با استفاده از کوکی احراز هویت جلسه معمولی لاراول احراز هویت کند. اگر آن کوکی وجود نداشته باشد، Sanctum سعی خواهد کرد با استفاده از یک نشانه در Authorization هدر درخواست، درخواست را تأیید کند. علاوه بر این، احراز هویت همه درخواست‌ها با استفاده از Sanctum تضمین می‌کند که همیشه می‌توانیم متد را tokenCan در نمونه کاربر تأیید شده فعلی فراخوانی کنیم:

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

ابطال توکن ها

شما می‌توانید توکن‌ها را با حذف آنها از پایگاه داده خود با استفاده از tokens رابطه‌ای که توسط این ویژگی ارائه می‌شود، «لغو» کنید Laravel\Sanctum\HasApiTokens :

// Revoke all tokens...
$user->tokens()->delete();
 
// Revoke the token that was used to authenticate the current request...
$request->user()->currentAccessToken()->delete();
 
// Revoke a specific token...
$user->tokens()->where('id', $tokenId)->delete();

انقضای توکن

به‌طور پیش‌فرض، توکن‌های Sanctum هرگز منقضی نمی‌شوند و ممکن است تنها با لغو توکن باطل شوند . با این حال، اگر می‌خواهید زمان انقضا را برای توکن‌های API برنامه خود پیکربندی کنید، می‌توانید این کار را از طریق expiration گزینه پیکربندی تعریف شده در فایل پیکربندی برنامه خود انجام دهید sanctum . این گزینه پیکربندی، تعداد دقیقه‌هایی را مشخص می‌کند که یک توکن صادر شده منقضی شده در نظر گرفته شود:

'expiration' => 525600,

اگر می خواهید زمان انقضای هر توکن را به طور مستقل مشخص کنید، می توانید این کار را با ارائه زمان انقضا به عنوان آرگومان سوم متد انجام دهید createToken :

return $user->createToken(
    'token-name', ['*'], now()->addWeek()
)->plainTextToken;

اگر زمان انقضای رمز را برای برنامه خود پیکربندی کرده اید، ممکن است بخواهید یک کار برای هرس کردن توکن های منقضی شده برنامه خود نیز برنامه ریزی کنید. خوشبختانه، Sanctum شامل یک sanctum:prune-expired دستور Artisan است که می توانید برای انجام این کار از آن استفاده کنید. به عنوان مثال، می‌توانید یک کار زمان‌بندی‌شده را برای حذف تمام رکوردهای پایگاه داده رمز منقضی که حداقل 24 ساعت منقضی شده‌اند پیکربندی کنید:

use Illuminate\Support\Facades\Schedule;
 
Schedule::command('sanctum:prune-expired --hours=24')->daily();

احراز هویت SPA

Sanctum همچنین برای ارائه یک روش ساده برای تأیید اعتبار برنامه‌های تک صفحه‌ای (SPA) که نیاز به برقراری ارتباط با API مبتنی بر لاراول دارند، وجود دارد. این SPA ها ممکن است در همان مخزن برنامه لاراول شما وجود داشته باشند یا ممکن است یک مخزن کاملا مجزا باشند.

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

برای احراز هویت، SPA و API شما باید یک دامنه سطح بالا را به اشتراک بگذارند. با این حال، آنها ممکن است در زیر دامنه های مختلف قرار بگیرند. علاوه بر این، باید اطمینان حاصل کنید که Accept: application/json هدر و Referer یا Origin هدر را همراه با درخواست خود ارسال می کنید.

پیکربندی

پیکربندی دامنه های شخص اول شما

ابتدا، باید پیکربندی کنید که SPA شما از کدام دامنه ها درخواست می دهد. می توانید این دامنه ها را با استفاده از stateful گزینه پیکربندی موجود در sanctum فایل پیکربندی خود پیکربندی کنید. این تنظیمات پیکربندی تعیین می‌کند که کدام دامنه‌ها با استفاده از کوکی‌های جلسه لاراول هنگام درخواست به API شما، احراز هویت "stateful" را حفظ کنند.

اگر از طریق یک URL که دارای پورت ( ) است به برنامه خود دسترسی دارید 127.0.0.1:8000 ، باید مطمئن شوید که شماره پورت را با دامنه وارد کرده اید.

Sanctum Middleware

در مرحله بعد، باید به لاراول دستور دهید که درخواست‌های دریافتی از SPA شما می‌توانند با استفاده از کوکی‌های جلسه لاراول احراز هویت شوند، در حالی که همچنان به درخواست‌های اشخاص ثالث یا برنامه‌های موبایل اجازه می‌دهید با استفاده از توکن‌های API احراز هویت شوند. این را می توان به راحتی با فراخوانی statefulApi روش میان افزار در فایل برنامه خود انجام داد bootstrap/app.php :

->withMiddleware(function (Middleware $middleware) {
    $middleware->statefulApi();
})

CORS و کوکی ها

اگر در تأیید اعتبار برنامه خود از یک SPA که در یک زیر دامنه جداگانه اجرا می شود مشکل دارید، احتمالاً CORS (اشتراک گذاری منبع متقابل) یا تنظیمات کوکی جلسه خود را اشتباه پیکربندی کرده اید.

فایل config/cors.php پیکربندی به طور پیش فرض منتشر نمی شود. اگر می‌خواهید گزینه‌های CORS لاراول را سفارشی کنید، باید cors فایل پیکربندی کامل را با استفاده از config:publish دستور Artisan منتشر کنید:

php artisan config:publish cors

در مرحله بعد، باید مطمئن شوید که پیکربندی CORS برنامه شما هدر را Access-Control-Allow-Credentials با مقدار True . این ممکن است با تنظیم گزینه در فایل پیکربندی supports_credentials برنامه شما روی . config/cors.php true

علاوه بر این، باید گزینه های withCredentials و withXSRFToken را در نمونه جهانی برنامه خود فعال کنید axios . به طور معمول، این باید در resources/js/bootstrap.js فایل شما انجام شود. اگر از Axios برای درخواست HTTP از frontend خود استفاده نمی کنید، باید پیکربندی معادل آن را در سرویس گیرنده HTTP خود انجام دهید:

axios.defaults.withCredentials = true;
axios.defaults.withXSRFToken = true;

در نهایت، باید مطمئن شوید که پیکربندی دامنه کوکی جلسه برنامه شما از هر زیر دامنه دامنه ریشه شما پشتیبانی می کند. شما می توانید این کار را با پیشوند دامنه با یک پیشوند . در فایل پیکربندی برنامه خود انجام دهید config/session.php :

'domain' => '.domain.com',

احراز هویت

حفاظت CSRF

برای احراز هویت SPA، صفحه "ورود" SPA شما باید ابتدا درخواستی را به /sanctum/csrf-cookie نقطه پایانی ارسال کند تا حفاظت CSRF را برای برنامه اولیه تنظیم کند:

axios.get('/sanctum/csrf-cookie').then(response => {
    // Login...
});

در طول این درخواست، لاراول یک XSRF-TOKEN کوکی حاوی توکن CSRF فعلی تنظیم می کند. سپس این نشانه باید در یک هدر در درخواست های بعدی ارسال شود X-XSRF-TOKEN ، که برخی از کتابخانه های سرویس گیرنده HTTP مانند Axios و Angular HttpClient به طور خودکار برای شما انجام می دهند. اگر کتابخانه HTTP جاوا اسکریپت شما مقداری را برای شما تنظیم نمی کند، باید هدر را به صورت دستی تنظیم کنید X-XSRF-TOKEN تا با مقدار XSRF-TOKEN کوکی تنظیم شده توسط این مسیر مطابقت داشته باشد.

ورود به سیستم در

هنگامی که حفاظت CSRF مقداردهی اولیه شد، باید یک POST درخواست به مسیر برنامه لاراول خود ارسال کنید /login . این /login مسیر ممکن است به صورت دستی یا با استفاده از یک بسته احراز هویت هدلس مانند Laravel Fortify پیاده سازی شود .

اگر درخواست ورود موفقیت آمیز باشد، احراز هویت می شوید و درخواست های بعدی به مسیرهای برنامه شما به طور خودکار از طریق کوکی جلسه ای که برنامه لاراول برای مشتری شما صادر کرده است، احراز هویت می شود. علاوه بر این، از آنجایی که برنامه شما قبلاً درخواستی برای /sanctum/csrf-cookie مسیر ارسال کرده است، درخواست‌های بعدی باید به طور خودکار محافظت CSRF را دریافت کنند تا زمانی که کلاینت HTTP جاوا اسکریپت شما مقدار XSRF-TOKEN کوکی را در X-XSRF-TOKEN هدر ارسال کند.

البته اگر جلسه کاربر شما به دلیل عدم فعالیت منقضی شود، درخواست های بعدی به برنامه لاراول ممکن است پاسخ خطای HTTP 401 یا 419 را دریافت کند. در این صورت، باید کاربر را به صفحه ورود به سیستم SPA خود هدایت کنید.

شما آزاد هستید که نقطه پایانی خود را بنویسید /login . با این حال، باید اطمینان حاصل کنید که با استفاده از سرویس‌های احراز هویت استاندارد و مبتنی بر جلسه که لاراول ارائه می‌کند، کاربر را احراز هویت می‌کند . به طور معمول، این به معنای استفاده از web محافظ احراز هویت است.

حفاظت از مسیرها

برای محافظت از مسیرها به طوری که تمام درخواست های دریافتی باید احراز هویت شوند، باید sanctum محافظ احراز هویت را به مسیرهای API خود در routes/api.php فایل خود متصل کنید. این محافظ تضمین می‌کند که درخواست‌های دریافتی به‌عنوان درخواست‌های احراز هویت شده از سوی SPA شما احراز هویت می‌شوند یا اگر درخواست از طرف شخص ثالث باشد، یک سرآیند توکن API معتبر دارند:

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

مجوز کانال های پخش خصوصی

اگر SPA شما نیاز به احراز هویت با کانال‌های پخش خصوصی/حضوری دارد ، باید channels ورودی را از withRouting روش موجود در فایل برنامه خود حذف کنید bootstrap/app.php . در عوض، باید withBroadcasting روش را فراخوانی کنید تا بتوانید میان افزار صحیحی را برای مسیرهای پخش برنامه خود مشخص کنید:

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        // ...
    )
    ->withBroadcasting(
        __DIR__.'/../routes/channels.php',
        ['prefix' => 'api', 'middleware' => ['auth:sanctum']],
    )

در مرحله بعد، برای اینکه درخواست‌های مجوز Pusher موفق شوند، باید authorizer هنگام مقداردهی اولیه Laravel Echo یک Pusher سفارشی ارائه دهید . این به برنامه شما اجازه می دهد تا Pusher را برای استفاده از axios نمونه ای که به درستی برای درخواست های بین دامنه پیکربندی شده است، پیکربندی کند :

window.Echo = new Echo({
    broadcaster: "pusher",
    cluster: import.meta.env.VITE_PUSHER_APP_CLUSTER,
    encrypted: true,
    key: import.meta.env.VITE_PUSHER_APP_KEY,
    authorizer: (channel, options) => {
        return {
            authorize: (socketId, callback) => {
                axios.post('/api/broadcasting/auth', {
                    socket_id: socketId,
                    channel_name: channel.name
                })
                .then(response => {
                    callback(false, response.data);
                })
                .catch(error => {
                    callback(true, error);
                });
            }
        };
    },
})

احراز هویت اپلیکیشن موبایل

همچنین می‌توانید از نشانه‌های Sanctum برای احراز هویت درخواست‌های برنامه تلفن همراه خود به API خود استفاده کنید. فرآیند احراز هویت درخواست های برنامه های کاربردی تلفن همراه مشابه احراز هویت درخواست های API شخص ثالث است. با این حال، تفاوت های کوچکی در نحوه صدور توکن های API وجود دارد.

صدور توکن های API

برای شروع، مسیری ایجاد کنید که ایمیل / نام کاربری، رمز عبور و نام دستگاه کاربر را می‌پذیرد، سپس آن اعتبارنامه‌ها را با یک توکن جدید Sanctum مبادله می‌کند. "نام دستگاه" داده شده به این نقطه پایانی برای مقاصد اطلاعاتی است و ممکن است هر مقداری که بخواهید باشد. به طور کلی، مقدار نام دستگاه باید نامی باشد که کاربر آن را تشخیص می دهد، مانند «آیفون 12 Nuno».

به طور معمول، از صفحه "ورود" برنامه تلفن همراه خود به نقطه پایانی رمز درخواست می دهید. نقطه پایانی کد API متن ساده را برمی گرداند که ممکن است در دستگاه تلفن همراه ذخیره شود و برای درخواست های API اضافی استفاده شود:

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;
 
Route::post('/sanctum/token', function (Request $request) {
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
        'device_name' => 'required',
    ]);
 
    $user = User::where('email', $request->email)->first();
 
    if (! $user || ! Hash::check($request->password, $user->password)) {
        throw ValidationException::withMessages([
            'email' => ['The provided credentials are incorrect.'],
        ]);
    }
 
    return $user->createToken($request->device_name)->plainTextToken;
});

هنگامی که برنامه تلفن همراه از توکن برای ارسال درخواست API به برنامه شما استفاده می کند، باید توکن را در Authorization هدر به عنوان یک Bearer توکن ارسال کند.

هنگام صدور توکن برای یک برنامه تلفن همراه، می توانید توانایی های توکن را نیز مشخص کنید .

حفاظت از مسیرها

همانطور که قبلاً مستند شده است، می‌توانید از مسیرها محافظت کنید به طوری که تمام درخواست‌های دریافتی باید با اتصال sanctum محافظ احراز هویت به مسیرها احراز هویت شوند:

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

ابطال توکن ها

برای اینکه به کاربران اجازه دهید توکن‌های API صادر شده برای دستگاه‌های تلفن همراه را لغو کنند، می‌توانید آن‌ها را با نام، همراه با دکمه «لغو»، در بخش «تنظیمات حساب» از UI برنامه وب خود فهرست کنید. هنگامی که کاربر روی دکمه "Revoke" کلیک می کند، می توانید رمز را از پایگاه داده حذف کنید. به یاد داشته باشید، شما می توانید از طریق tokens رابطه ای که توسط این ویژگی ارائه می شود، به نشانه های API کاربر دسترسی داشته باشید Laravel\Sanctum\HasApiTokens :

// Revoke all tokens...
$user->tokens()->delete();
 
// Revoke a specific token...
$user->tokens()->where('id', $tokenId)->delete();

آزمایش کردن

در حین آزمایش، این Sanctum::actingAs روش ممکن است برای احراز هویت یک کاربر و مشخص کردن توانایی هایی که باید به توکن آنها اعطا شود استفاده شود:

use App\Models\User;
use Laravel\Sanctum\Sanctum;
 
test('task list can be retrieved', function () {
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );
 
    $response = $this->get('/api/task');
 
    $response->assertOk();
});

use App\Models\User;
use Laravel\Sanctum\Sanctum;
 
public function test_task_list_can_be_retrieved(): void
{
    Sanctum::actingAs(
        User::factory()->create(),
        ['view-tasks']
    );
 
    $response = $this->get('/api/task');
 
    $response->assertOk();
}

اگر می‌خواهید همه توانایی‌ها را به توکن اعطا کنید، باید * در لیست توانایی‌های ارائه‌شده به actingAs روش بنویسید:

Sanctum::actingAs(
    User::factory()->create(),
    ['*']
);