Laravel Passport PHP: دليل شامل لخادم OAuth2

1. ما هو Laravel Passport ولماذا تحتاجه

Laravel Passport هو تطبيق كامل لخادم OAuth2 لإطار العمل Laravel (PHP). يوفر مجموعة أدوات جاهزة لإنشاء مصادقة API، مما يسمح للمطورين بتطبيق حماية RESTful API الخاصة بهم بسرعة باستخدام رموز الوصول (access tokens) ورموز التحديث (refresh tokens). تم بناء المكتبة على أساس الحزمة القوية League OAuth2 Server، والتي تم تكييفها مع نظام Laravel البيئي، بما في ذلك الترحيلات (migrations) والواجهات (facades) وأوامر Artisan ونماذج Eloquent.

الهدف الرئيسي من Passport هو توفير وقت المطور من الحاجة إلى كتابة منطق معقد لتوليد والتحقق وتخزين الرموز يدويًا. بدلاً من ذلك، تحصل على مسارات جاهزة لإصدار الرموز (عبر أنواع المنح grant types)، و middleware لحماية المسارات، وطرق سهلة لإدارة العملاء (التطبيقات) والرموز. يعتبر Passport مثاليًا لإنشاء تطبيقات الصفحة الواحدة (SPA) وتطبيقات الجوال والعملاء من جانب الخادم الذين يحتاجون إلى وصول آمن إلى API الخاص بك.

لماذا تستخدم Passport بدلاً من حل مكتوب يدويًا؟ أولاً، الأمان: تطبق المكتبة جميع متطلبات مواصفات OAuth2، بما في ذلك الحماية من CSRF والمعالجة الصحيحة للنطاقات (scopes) و PKCE (Proof Key for Code Exchange). ثانيًا، سرعة التطوير: تحصل على ترحيلات ونماذج ووحدات تحكم جاهزة. ثالثًا، المرونة: يدعم Passport جميع أنواع المنح الرئيسية (authorization code, client credentials, password grant, personal access tokens) ويمكن توسيعه بسهولة لتلبية الاحتياجات الخاصة.

2. التركيب (Installation)

يتم تثبيت Laravel Passport عبر Composer، مدير الحزم القياسي لـ PHP. قم بتنفيذ الأمر التالي في جذر مشروع Laravel الخاص بك:

composer require laravel/passport

بعد تثبيت الحزمة، يجب تنفيذ الترحيلات ونشر الإعدادات. يستخدم Passport نظام الترحيلات الخاص به، والذي يقوم بإنشاء جداول لتخزين العملاء والرموز ورموز التفويض والرموز الشخصية:

php artisan migrate

ثم قم بتشغيل الأمر passport:install، والذي سيقوم بإنشاء مفاتيح التشفير والعملاء للرموز الشخصية ومنح كلمة المرور (password grant):

php artisan passport:install

بعد تنفيذ الأمر، سترى في وحدة التحكم client_id و client_secret. الأول مخصص للرموز الشخصية (Personal Access Client)، والثاني لمنح كلمة المرور (Password Grant Client). قم بحفظها في ملف .env:

PASSPORT_PERSONAL_ACCESS_CLIENT_ID=1
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=your-secret-here
PASSPORT_PASSWORD_GRANT_CLIENT_ID=2
PASSPORT_PASSWORD_GRANT_CLIENT_SECRET=your-secret-here

بعد ذلك، أضف trait Laravel\Passport\HasApiTokens إلى نموذج User (app/Models/User.php):

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    protected $fillable = [
        'name', 'email', 'password',
    ];

    protected $hidden = [
        'password', 'remember_token',
    ];
}

في ملف config/auth.php، قم بتغيير برنامج تشغيل المصادقة إلى passport:

'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

أخيرًا، في ملف app/Providers/AuthServiceProvider.php، أضف استدعاء Passport::routes() داخل طريقة boot():

<?php

namespace App\Providers;

use Illuminate\Foundation\Support\Providers\AuthServi