تطوير واجهات REST API

مصادقة API باستخدام Sanctum

20 دقيقة الدرس 9 من 35

فهم Laravel Sanctum

يوفر Laravel Sanctum نظام مصادقة خفيف الوزن لـ SPAs (تطبيقات الصفحة الواحدة) وتطبيقات الجوال وواجهات برمجة التطبيقات البسيطة القائمة على الرموز. إنه مثالي لمصادقة واجهات برمجة التطبيقات بدون تعقيد OAuth2.

ما هو Sanctum؟

يوفر Sanctum طريقتين للمصادقة:

رموز API: مصادقة بسيطة قائمة على الرموز لتطبيقات الجوال والمستهلكين من طرف ثالث
مصادقة SPA: مصادقة قائمة على ملفات تعريف الارتباط لـ JavaScript SPAs التي تعمل على نفس النطاق

ملاحظة: Sanctum مثالي لمعظم واجهات برمجة التطبيقات. استخدم Passport فقط إذا كنت بحاجة إلى تنفيذ خادم OAuth2 كامل مع أنواع منح متعددة.

تثبيت Sanctum

قم بتثبيت Sanctum عبر Composer:

composer require laravel/sanctum

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

php artisan migrate

ينشئ هذا جدول personal_access_tokens لتخزين رموز API.

تكوين Sanctum

أضف وسيط Sanctum إلى app/Http/Kernel.php:

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

أضف سمة HasApiTokens إلى نموذج المستخدم الخاص بك:

use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, HasFactory, Notifiable;

    // ... باقي النموذج
}

إنشاء رموز API

قم بتوليد رموز للمستخدمين بعد المصادقة:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

public function login(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' => ['بيانات الاعتماد المقدمة غير صحيحة.'],
        ]);
    }

    // إنشاء رمز
    $token = $user->createToken($request->device_name)->plainTextToken;

    return response()->json([
        'success' => true,
        'message' => 'تم تسجيل الدخول بنجاح',
        'data' => [
            'user' => $user,
            'token' => $token,
        ]
    ]);
}

نصيحة: يساعد device_name المستخدمين على تحديد الجهاز أو التطبيق الذي ينتمي إليه الرمز.

حماية المسارات باستخدام Sanctum

قم بتطبيق وسيط auth:sanctum لحماية المسارات:

// routes/api.php
use Illuminate\Support\Facades\Route;

// مسارات عامة
Route::post('/register', [AuthController::class, 'register']);
Route::post('/login', [AuthController::class, 'login']);

// مسارات محمية
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', function (Request $request) {
        return $request->user();
    });

    Route::post('/logout', [AuthController::class, 'logout']);

    Route::apiResource('posts', PostController::class);
});

إجراء طلبات مصادق عليها

قم بتضمين الرمز في رأس التفويض:

# باستخدام cURL
curl -H "Accept: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://api.example.com/api/user

# باستخدام JavaScript Fetch
fetch('https://api.example.com/api/user', {
    headers: {
        'Accept': 'application/json',
        'Authorization': 'Bearer ' + token
    }
})

إلغاء الرموز

اسمح للمستخدمين بتسجيل الخروج عن طريق إلغاء رمزهم الحالي:

public function logout(Request $request)
{
    // إلغاء الرمز الحالي
    $request->user()->currentAccessToken()->delete();

    return response()->json([
        'success' => true,
        'message' => 'تم تسجيل الخروج بنجاح'
    ]);
}

إلغاء جميع الرموز للمستخدم:

// إلغاء جميع الرموز
$user->tokens()->delete();

// إلغاء رمز محدد بواسطة المعرف
$user->tokens()->where('id', $tokenId)->delete();

قدرات الرموز (النطاقات)

منح أذونات محددة للرموز:

// إنشاء رمز مع قدرات محددة
$token = $user->createToken('mobile-app', [
    'post:create',
    'post:update',
    'post:delete',
    'comment:create'
])->plainTextToken;

// إنشاء رمز للقراءة فقط
$readOnlyToken = $user->createToken('analytics', [
    'post:read',
    'user:read'
])->plainTextToken;

تحقق من قدرات الرموز في كودك:

public function store(Request $request)
{
    // تحقق مما إذا كان الرمز لديه القدرة المطلوبة
    if (!$request->user()->tokenCan('post:create')) {
        return response()->json([
            'success' => false,
            'message' => 'أذونات غير كافية'
        ], 403);
    }

    // إنشاء منشور...
}

حماية المسارات حسب القدرة

استخدم وسيط abilities:

Route::middleware(['auth:sanctum', 'abilities:post:create,post:update'])
    ->post('/posts', [PostController::class, 'store']);

// يجب أن يكون لدى المستخدم جميع القدرات المحددة

Route::middleware(['auth:sanctum', 'ability:post:create,post:read'])
    ->get('/posts', [PostController::class, 'index']);

// يجب أن يكون لدى المستخدم قدرة واحدة على الأقل من القدرات المحددة

انتهاء صلاحية الرمز

قم بتكوين انتهاء صلاحية الرمز في config/sanctum.php:

'expiration' => 60 * 24, // 24 ساعة (بالدقائق)

// أو اضبطه على null للرموز التي لا تنتهي صلاحيتها أبداً
'expiration' => null,

التسجيل مع رمز

أنشئ نقطة نهاية تسجيل تعيد رمزاً:

public function register(Request $request)
{
    $validated = $request->validate([
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users,email',
        'password' => 'required|string|min:8|confirmed',
        'device_name' => 'required',
    ]);

    $user = User::create([
        'name' => $validated['name'],
        'email' => $validated['email'],
        'password' => Hash::make($validated['password']),
    ]);

    $token = $user->createToken($validated['device_name'])->plainTextToken;

    return response()->json([
        'success' => true,
        'message' => 'تم التسجيل بنجاح',
        'data' => [
            'user' => $user,
            'token' => $token,
        ]
    ], 201);
}

إدارة رموز المستخدم

اسمح للمستخدمين بعرض وإدارة رموزهم:

public function tokens(Request $request)
{
    $tokens = $request->user()->tokens->map(function ($token) {
        return [
            'id' => $token->id,
            'name' => $token->name,
            'abilities' => $token->abilities,
            'last_used_at' => $token->last_used_at,
            'created_at' => $token->created_at,
        ];
    });

    return response()->json([
        'success' => true,
        'data' => $tokens
    ]);
}

تمرين:

قم بتثبيت وتكوين Sanctum في تطبيقك
أنشئ نقاط نهاية التسجيل وتسجيل الدخول التي تعيد الرموز
احمِ مسارات Post CRUD بوسيط auth:sanctum
نفذ قدرات الرموز للقراءة فقط والوصول الكامل
أنشئ نقطة نهاية تسرد جميع رموز المستخدم مع قدراتها ووقت آخر استخدام
أضف نقطة نهاية تسجيل الخروج التي تلغي الرمز الحالي

أفضل ممارسات الأمان

استخدم HTTPS: استخدم دائماً HTTPS في الإنتاج لحماية الرموز أثناء النقل
رموز قصيرة الأجل: حدد أوقات انتهاء صلاحية معقولة (24 ساعة لتطبيقات الجوال)
تتبع الجهاز: قم بتخزين اسم الجهاز وIP ووكيل المستخدم للتدقيق الأمني
نطاقات القدرة: امنح الحد الأدنى من الأذونات الضرورية للرموز
الإلغاء: وفر إلغاء رمز سهل للمستخدمين
تحديد المعدل: قم بتطبيق تحديد المعدل على نقاط نهاية المصادقة

الخلاصة

يوفر Laravel Sanctum نظام مصادقة بسيطاً وآمناً مثالياً لواجهات برمجة التطبيقات وتطبيقات SPA. مع قدرات الرموز وانتهاء الصلاحية والإلغاء السهل، يغطي معظم احتياجات المصادقة بدون تعقيد OAuth2. في الدرس التالي، سنستكشف Laravel Passport للتطبيقات التي تتطلب تنفيذ OAuth2 كاملاً.