نسخه:

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

معرفی

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

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

Laravel Sanctum برای حل دو مشکل جداگانه وجود دارد.

توکن های API

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

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

احراز هویت SPA

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

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

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

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

می توانید Laravel Sanctum را از طریق Composer نصب کنید: 

composer require laravel/sanctum

در مرحله بعد، باید فایل های پیکربندی و مهاجرت Sanctum را با استفاده از vendor:publish دستور Artisan منتشر کنید. فایل sanctum پیکربندی در دایرکتوری شما قرار می گیرد config : 

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

در نهایت، شما باید مهاجرت های پایگاه داده خود را اجرا کنید. Sanctum یک جدول پایگاه داده ایجاد می کند تا توکن های API را در آن ذخیره کند: 

php artisan migrate

در مرحله بعد، اگر قصد دارید از Sanctum برای احراز هویت یک SPA استفاده کنید، باید میان افزار Sanctum را به api گروه میان افزار خود در app/Http/Kernel.php فایل خود اضافه کنید: 

use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful;
 
'api' => [
    EnsureFrontendRequestsAreStateful::class,
    'throttle:60,1',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

سفارشی سازی مهاجرت

اگر نمی‌خواهید از مهاجرت‌های پیش‌فرض Sanctum استفاده کنید، باید Sanctum::ignoreMigrations متد موجود در register متد خود را فراخوانی کنید AppServiceProvider . می توانید مهاجرت های پیش فرض را با استفاده از صادر کنید php artisan vendor:publish --tag=sanctum-migrations .

API Token Authentication

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

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

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

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

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

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

$token = $user->createToken('token-name');
 
return $token->plainTextToken;

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

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

توانایی های توکن

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

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

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

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

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

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

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

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

ابطال توکن ها

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

// Revoke all tokens...
$user->tokens()->delete();
 
// Revoke the user's current token...
$request->user()->currentAccessToken()->delete();
 
// Revoke a specific token...
$user->tokens()->where('id', $id)->delete();

احراز هویت SPA

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

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

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

پیکربندی

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

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

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

Sanctum Middleware

در مرحله بعد، باید میان افزار Sanctum را به api گروه میان افزار خود در app/Http/Kernel.php فایل خود اضافه کنید. این میان‌افزار مسئول اطمینان از اینکه درخواست‌های دریافتی از SPA شما می‌توانند با استفاده از کوکی‌های جلسه لاراول احراز هویت شوند، در عین حال به درخواست‌های اشخاص ثالث یا برنامه‌های تلفن همراه اجازه می‌دهد تا با استفاده از توکن‌های API احراز هویت شوند: 

use Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful;
 
'api' => [
    EnsureFrontendRequestsAreStateful::class,
    'throttle:60,1',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

CORS و کوکی ها

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

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

علاوه بر این، باید این withCredentials گزینه را در نمونه جهانی خود فعال کنید axios . resources/js/bootstrap.js به طور معمول، این باید در فایل شما انجام شود : 

axios.defaults.withCredentials = true;

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

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

احراز هویت

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

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

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

هنگامی که حفاظت CSRF مقداردهی اولیه شد، باید POST به مسیر معمولی لاراول درخواست دهید /login . این مسیر ممکن است توسط بسته داربست احراز هویت /login ارائه شود . laravel/ui

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

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

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

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

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

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

اگر SPA شما نیاز به احراز هویت با کانال‌های پخش خصوصی/حضوری دارد ، باید Broadcast::routes روش فراخوانی را در فایل خود قرار دهید routes/api.php : 

Broadcast::routes(['middleware' => ['auth:sanctum']]);

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

window.Echo = new Echo({
    broadcaster: "pusher",
    cluster: process.env.MIX_PUSHER_APP_CLUSTER,
    encrypted: true,
    key: process.env.MIX_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 مبادله می‌کند. نقطه پایانی کد Sanctum متن ساده را برمی‌گرداند که ممکن است در دستگاه تلفن همراه ذخیره شود و برای درخواست‌های API اضافی استفاده شود: 

use App\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 محافظ احراز هویت به مسیرها احراز هویت شوند. به طور معمول، شما این محافظ را به مسیرهای تعریف شده در routes/api.php فایل خود متصل می کنید: 

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

ابطال توکن ها

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

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

آزمایش کردن

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

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

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

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