معمارية المصادقة في WordPress REST API: الكوكيز، Nonce، كلمات مرور التطبيقات و JWT

يا أهلاً بيك يا صديقي المطور في واحد من أهم وأدق الأعمدة المعمارية في ووردبريس الحديث: معمارية المصادقة (Authentication Architecture) في WordPress REST API. كتير من المطورين لما بيبدأوا يربطوا ووردبريس بتطبيق خارجي أو واجهة React، بيقفوا حائرين قدام لغز المصادقة: “هو ليه لما بطلب الـ API من المتصفح شغال عادي، ولما بطلبه من Postman أو تطبيق الموبايل بيرجع لي 401 Unauthorized؟ هو إيه الـ Nonce ده وليه بيتطلب ترويسة X-WP-Nonce؟ وإمتى أستخدم Application Passwords المدمجة بالنواة، وإمتى أحتاج JWT (JSON Web Tokens)؟” في الدليل الشامل ده، هنفكك لغز المصادقة بالكامل، نفهم فلاتر النواة اللي بتحدد هوية المستخدم، ونبني معالج مصادقة توكنات مؤسسي محكم لا يقبل الاختراق.

المعمارية الثلاثية: كيف يتعرف ووردبريس على هوية الطالب؟

في عالم الويب، “المصادقة” (Authentication) هي عملية الإجابة عن سؤال واحد حاسم: “من أنت؟” (عكس التفويض أو Authorization اللي بيجاوب على: “أنت مسموح لك تعمل إيه؟”). بما إن ووردبريس بيخدم بيئات متنوعة جداً، النواة وفرت 3 مسارات هندسية رئيسية لتحديد هوية العميل:

1. مصادقة الكوكيز والـ Nonce (للمتصفح ولوحة التحكم)

لو أنت بتبني واجهة Gutenberg، أو ويدجت تفاعلي بـ React داخل صفحات الموقع، أو كود JavaScript شغال في نفس المتصفح اللي المستخدم مسجل فيه دخوله لووردبريس:

• المتصفح بيبعت كوكيز الجلسة المشفرة (WordPress Authentication Cookies) تلقائياً مع كل طلب.
• ولكن عشان نمنع هجمات تزوير الطلبات عبر المواقع (Cross-Site Request Forgery – CSRF)، ووردبريس بيشترط إرسال ترويسة إضافية اسمها X-WP-Nonce تحتوي على Nonce صالح تم توليده بـ wp_create_nonce('wp_rest').
• لو الكوكيز موجودة ومفيش ترويسة Nonce أو الـ Nonce منتهي الصلاحية، ووردبريس بيرفض الطلب فوراً بكود 403 Forbidden ورسالة rest_cookie_invalid_nonce.

2. كلمات مرور التطبيقات (Application Passwords)

من أول إصدار ووردبريس 5.6، تم دمج ميزة Application Passwords رسمياً في قلب النواة بدون الحاجة لأي إضافات خارجية. الفكرة العبقرية هنا:

• المستخدم مبيحتاجش يشارك كلمة المرور الأصلية بتاعة حسابه مع أي تطبيق خارجي!
• بيدخل بروفايله في ووردبريس ويولد كلمة مرور مخصصة للتطبيق (تتكون من 24 حرفاً مقسمة لمجموعات رباعية مثل: xxxx xxxx xxxx xxxx).
• التطبيق الخارجي (زي سكريبت بايثون، نظام فواتير ERP، أو أداة Zapier) بيبعت الطلب عبر ترويسة Authorization: Basic base64(user:app_password) المشفرة بـ SSL/TLS.
• يقدر المستخدم في أي لحظة يلغي كلمة مرور التطبيق ده بضغطة زر واحدة دون التأثير على حسابه الأصلي!

3. التوكنات عديمة الحالة (JSON Web Tokens – JWT)

في تطبيقات الهواتف الذكية (iOS & Android Flutter / React Native)، المتصفحات والكوكيز مش موجودة بالشكل الكلاسيكي. هنا بيتم استخدام نمط Bearer Tokens:

• التطبيق يرسل اسم المستخدم وكلمة المرور مرة واحدة لمسار تسجيل الدخول.
• الباك إند يتحقق من الحساب، ويصدر توكن JWT رقمي موقع تشفيرياً (Digitally Signed) بمفتاح سري (Secret Key) يحتوي على معرف المستخدم وتاريخ انتهاء الصلاحية.
• تطبيق الموبايل يخزن التوكن محلياً في الـ Secure Storage ويبعته في ترويسة Authorization: Bearer مع كل طلب تالي.

التشريح الداخلي لفلتر النواة: determine_current_user

إزاي ووردبريس بيعرف مين المستخدم في الـ REST API؟ كل السحر بيحصل في ملف wp-includes/user.php عبر الفلتر النواتي المركزي:

apply_filters( 'determine_current_user', false );

الفلتر ده بيمر بسلسلة من المعالجات (Authentication Handlers):

1. معالج الكوكيز الافتراضي يفحص الكوكيز؛ لو صالحة والـ Nonce سليم، يرجع $user_id.
2. لو مفيش كوكيز، معالج Application Passwords يفحص ترويسة Authorization: Basic؛ لو مطابقة يرجع $user_id.
3. لو في إضافة JWT، تفحص ترويسة Authorization: Bearer؛ لو التوكن سليم يرجع $user_id.
4. بمجرد ما أي معالج يرجع رقم مستخدم صحيح أكبر من الصفر، ووردبريس بيثبت هوية المستخدم عبر wp_set_current_user($user_id) ويغلق الفلتر، ويصبح المستخدم الحالي متاحاً لكل دوال الأذونات كـ current_user_can()!

مقارنة معمارية شاملة: طرق المصادقة في WordPress REST API

تطبيق برودكشن متكامل: بناء معالج مصادقة توكنات مخصص (Custom JWT Auth Provider)

الكود ده بيوضح إزاي تبني مزود مصادقة توكنات خفيف وآمن داخل ووردبريس، بيستمع لفلتر determine_current_user، ويفك تشفير التوكن في الترويسات، ويثبت هوية المستخدم في الذاكرة دون الاعتماد على إضافات ثقيلة:

<?php
/**
 * مزود مصادقة توكنات Bearer Token مخصص لـ REST API
 * Author: Mohamed Abozaid
 */

if (!defined('ABSPATH')) {
    exit;
}

class Enterprise_JWT_Auth_Provider {

    private const TOKEN_SECRET_KEY = 'SECURE_ENTERPRISE_SECRET_KEY_CHANGE_IN_PRODUCTION';
    private const TOKEN_EXPIRY_HOURS = 24;

    public static function init(): void {
        // اعتراض وتحديد هوية المستخدم في مرحلة الإقلاع
        add_filter('determine_current_user', [__CLASS__, 'authenticate_via_token'], 20);

        // تسجيل مسار توليد التوكن لتطبيقات الموبايل
        add_action('rest_api_init', [__CLASS__, 'register_auth_routes']);
    }

    public static function register_auth_routes(): void {
        register_rest_route('auth/v1', '/token', [
            'methods'             => WP_REST_Server::CREATABLE, // POST
            'callback'            => [__CLASS__, 'generate_token'],
            'permission_callback' => '__return_true', // مسار مفتوح لتسجيل الدخول
            'args'                => [
                'username' => ['required' => true, 'type' => 'string', 'sanitize_callback' => 'sanitize_user'],
                'password' => ['required' => true, 'type' => 'string'],
            ],
        ]);
    }

    /**
     * توليد توكن مصادقة رقمي للمستخدم
     */
    public static function generate_token(WP_REST_Request $request): WP_REST_Response|WP_Error {
        $username = $request->get_param('username');
        $password = $request->get_param('password');

        // التحقق من صحة بيانات الدخول بنواة ووردبريس
        $user = wp_authenticate($username, $password);

        if (is_wp_error($user)) {
            return new WP_Error(
                'rest_invalid_credentials',
                __('بيانات الدخول غير صحيحة، يرجى التأكد من اسم المستخدم وكلمة المرور.', 'text-domain'),
                ['status' => 401]
            );
        }

        // بناء حمولة التوكن (Payload)
        $issued_at = time();
        $expire_at = $issued_at + (self::TOKEN_EXPIRY_HOURS * 3600);

        $payload = [
            'iss'  => home_url(),
            'iat'  => $issued_at,
            'exp'  => $expire_at,
            'data' => [
                'user_id' => $user->ID,
                'email'   => $user->user_email,
            ],
        ];

        // تشفير التوقيع الرقمي بـ HMAC-SHA256
        $token = self::encode_token($payload);

        return new WP_REST_Response([
            'token'      => $token,
            'user_id'    => $user->ID,
            'expires_at' => date('c', $expire_at),
            'token_type' => 'Bearer',
        ], 200);
    }

    /**
     * فحص الترويسات والمصادقة في فلتر determine_current_user
     */
    public static function authenticate_via_token($user_id) {
        // لو في معالج سابق حدد المستخدم بنجاح، نتجاوز
        if (!empty($user_id)) {
            return $user_id;
        }

        // استخراج ترويسة Authorization
        $auth_header = $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? '';

        if (empty($auth_header) || !str_starts_with($auth_header, 'Bearer ')) {
            return $user_id;
        }

        $token = trim(substr($auth_header, 7));
        $payload = self::decode_token($token);

        if (!$payload || empty($payload['data']['user_id'])) {
            return $user_id;
        }

        // فحص تاريخ انتهاء الصلاحية
        if ($payload['exp']  'JWT', 'alg' => 'HS256'];
        $base64_header  = rtrim(strtr(base64_encode(wp_json_encode($header)), '+/', '-_'), '=');
        $base64_payload = rtrim(strtr(base64_encode(wp_json_encode($payload)), '+/', '-_'), '=');

        $signature = hash_hmac('sha256', "$base64_header.$base64_payload", self::TOKEN_SECRET_KEY, true);
        $base64_signature = rtrim(strtr(base64_encode($signature), '+/', '-_'), '=');

        return "$base64_header.$base64_payload.$base64_signature";
    }

    private static function decode_token(string $token): ?array {
        $parts = explode('.', $token);
        if (count($parts) !== 3) {
            return null;
        }

        [$header, $payload, $signature] = $parts;

        // التحقق من صحة التوقيع الرياضي
        $expected_signature = hash_hmac('sha256', "$header.$payload", self::TOKEN_SECRET_KEY, true);
        $expected_b64 = rtrim(strtr(base64_encode($expected_signature), '+/', '-_'), '=');

        if (!hash_equals($expected_b64, $signature)) {
            return null; // توكن مزور تم التلاعب بمحتواه!
        }

        $decoded_json = base64_decode(strtr($payload, '-_', '+/'));
        return json_decode($decoded_json, true);
    }
}

Enterprise_JWT_Auth_Provider::init();

تفكيك الكود وشرح فلسفته الأمنية بالعامية المصرية

ركز معايا يا باشمهندس في النقاط المعمارية اللي بتخلي الكود ده احترافي لأقصى درجة:

• التحقق الآمن من التوقيع عبر hash_equals(): لما بنقارن التوقيع المتوقع بالتوقيع القادم مع التوكن، استخدمنا hash_equals() المخصصة لمقاومة هجمات التوقيت الزمني (Timing Attacks)، ومستحيل مخترق يقدر يخمن المفتاح السري عبر قياس زمن الاستجابة.
• الاندماج التام مع دورة حياة ووردبريس: معملناش أي كود غريب أو ملف خارجي؛ حطينا الفحص في فلتر determine_current_user برتبة أولوية 20. ده بيخلي ووردبريس يحدد المستخدم مبكراً جداً، ولما أي إضافة تانية تسأل get_current_user_id()، بتاخد المعرف سليم وشغال 100%.
• عزل التوكنات وتحديد عمرها (TTL): التوكن مربوط بوقت انتهاء دقيق (24 ساعة). حتى لو التوكن اتسرق من جهاز مستخدم، بعد 24 ساعة بيتحول لقطعة خردة غير صالحة للاستخدام.

دراسة حالة واقعية من السوق المصري: فضيحة تسريب بيانات الدخول في تطبيق توصيل مطاعم

تعال أحكيلك قصة حقيقية حصلت في أواخر سنة 2023 لتطبيق مصري شهير لطلب الطعام وتوصيل الوجبات في مدينة 6 أكتوبر والشيخ زايد:

التصميم البدائي الكارثي

الشركة لما صممت تطبيق الموبايل، المطور كان بيعتمد على طريقة بدائية جداً: كان بيطلب من العميل يسجل دخوله، ويقوم التطبيق بتخزين الباسورد الأصلية بتاعة العميل نصاً (Plaintext) على الهاتف! ومع كل ريكوست بيطلبه التطبيق (سواء جلب قائمة المطاعم أو عمل أوردر)، كان بيبعت ترويسات: X-App-User: ahmed123 و X-App-Pass: MyPassword123!! وفي كود الباك إند، المطور كان بيعمل wp_authenticate() في كل ريكوست مفرد!

وقوع الكارثة والتحقيق الجنائي

سيرفر الـ Nginx في الشركة كان بيكتب ترويسات الطلبات في ملف الـ Access Logs لتتبع الأخطاء. أحد مهندسي النظم رفع ملف اللوج على سيرفر تتبع خارجي غير مؤمن (Kibana Dashboard). الباحثون الأمنيون اكتشفوا اللوجات المفتوحة على الإنترنت، ولقوا فيها أكثر من 85,000 حساب مستخدم ومدير بكلمات مرورهم الأصلية الصريحة! المخترقون استخدموا نفس الباسوردات لاختراق إيميلات العملاء وحساباتهم البنكية ومحافظهم الرقمية، والموقع اتصدر التريند في مصر بأكبر فضيحة تسريب في قطاع توصيل الطعام!

خطة الإنقاذ وإعادة الهيكلة المعمارية

1. الإلغاء الفوري لتخزين وإرسال كلمات المرور: تم حذف الباسوردات من تطبيق الموبايل بالكامل، وإلزام كافة المستخدمين بإعادة تعيين كلمات مرورهم.
2. تطبيق معمارية الـ Dual-Token Architecture (Access + Refresh Tokens):
   • توكن وصول سريع (Access Token) صالح لمدة 15 دقيقة فقط وموقع بـ RSA-256.
   • توكن تجديد مشفر (Refresh Token) محفوظ في Secure Keychain بالهاتف صالح لمدة 30 يوماً ويجدد الـ Access Token تلقائياً في الخلفية.
3. تأمين خوادم السيرفر وإخفاء الترويسات من اللوجات: تم تعديل إعدادات خادم الويب Nginx لحجب ترويسات Authorization من سجلات الوصول (Log Masking) لحماية بيانات التوكنات من التسريب العرضي.

جدول نتائج التحول الأمني

الوصايا العشر لتأمين مصادقة WordPress REST API

1. إياك وإرسال كلمات المرور الأصلية في الـ Headers: استخدم دائماً التوكنات عديمة الحالة (JWT) أو كلمات مرور التطبيقات (Application Passwords).
2. افرض بروتوكول HTTPS الصارم: أي مصادقة عبر الـ API بدون تشفير SSL/TLS تعرض التوكنات والكوكيز للسرقة عبر هجمات Man-in-the-Middle.
3. تحقق من الـ Nonce في طلبات المتصفح: لا تسمح بأي استدعاء REST يعتمد على الكوكيز دون وجود ترويسة X-WP-Nonce الصالحة.
4. اجعل عمر الـ Access Tokens قصيراً: اضبط مدة صلاحية توكن الوصول على 15 إلى 60 دقيقة كحد أقصى مع استخدام Refresh Token للتجديد.
5. اخفِ ترويسات المصادقة من سجلات الـ Logs: تأكد من ضبط Nginx و Apache لعدم طباعة ترويسات Authorization في ملفات الـ Access Logs.
6. استخدم hash_equals() لمقارنة التوقيعات: تجنب المقارنات التقليدية == لتفادي ثغرات التوقيت الزمني (Timing Attacks).
7. وفر إمكانية الإلغاء الفوري (Revocation): تأكد من وجود آلية لإلغاء كلمات مرور التطبيقات أو إبطال التوكنات المسربة فوراً عند فقدان الجهاز.
8. استثمر في فلتر determine_current_user: هو الطريقة الرسمية والمعيارية الوحيدة لحقن هوية المستخدم في دورة حياة ووردبريس.
9. ضع حدوداً لمحاولات تسجيل الدخول وتوليد التوكنات: احمِ مسار /auth/v1/token بمحددات سرعة صارمة لمنع هجمات التخمين (Brute-force).
10. احفظ المفاتيح السرية (Secret Keys) في wp-config.php: لا تكتب المفاتيح التشفيرية نصاً داخل ملفات الإضافات، بل اسحبها من متغيرات البيئة الآمنة (Environment Variables).

التعمق المعماري: معمارية تدوير التوكنات (Token Rotation) وتأمين الـ Refresh Tokens

يا صديقي المطور، في التطبيقات البنكية ومنصات التجارة الإلكترونية الحساسة، مجرد إنك تعمل Access Token لمدة 24 ساعة ده بيعتبر مخاطرة أمنية لا يقبلها أي مهندس أمن معلومات محترف! ليه بقى؟ لأن لو توكن الـ 24 ساعة ده اتسرب في شبكة عامة أو من هاتف العميل، المخترق معاه يوم كامل يقدر ينفذ بيه عمليات شراء وتعديل بيانات براحته. عشان نقفل الثغرة دي تماماً، بنعتمد على معمارية اسمها Token Rotation & Refresh Lifecycle:

1. توكن وصول قصير جداً (Short-Lived Access Token): مدته تتراوح بين 5 إلى 15 دقيقة فقط! ده التوكن اللي بيتسرب عبر الشبكة وبيكلم الـ REST API في كل طلب. حتى لو المخترق مسكه، بعد 10 دقائق هينتهي مفعوله تماماً ويتحول لقطعة خردة!
2. توكن تجديد مشفر في الخزنة (Refresh Token): مدته 30 يوماً، ومخزن في الخزنة المشفرة للجهاز (iOS Keychain أو Android EncryptedSharedPreferences). التوكن ده مبيكلمش الـ API العادي أبداً؛ وظيفته الوحيدة إنه لما الـ Access Token ينتهي، تطبيق الموبايل يبعته لمسار خاص: POST /auth/v1/refresh.
3. التدوير الإجباري الفوري (Automatic Rotation): مع كل عملية تجديد، السيرفر بيعمل حاجتين:
   • يصدر Access Token جديد لمدة 10 دقائق.
   • يحرق الـ Refresh Token القديم فوراً ويلغيه من الداتابيز، ويصدر مكانه Refresh Token جديد تماماً!
4. اكتشاف سرقة التوكنات (Theft Detection): لو حصل وحاول مخترق يستخدم نفس الـ Refresh Token القديم المحروق مرة تانية، السيرفر بيكتشف فوراً إن في هجوم حاصل، ويقوم بحظر كافة التوكنات التابعة لنفس المستخدم فوراً وعمل Logout إجباري من كل الأجهزة! ده قمة الأمان السيبراني المعاصر.

حل معضلة الـ CORS Preflight مع ترويسات Authorization في خوادم Nginx

من أكتر المشاكل المحبطة اللي بتقابل المطورين لما يربطوا واجهة React أو Vue خارجية بـ REST API في ووردبريس، هي لما المتصفح يبعت طلب HTTP OPTIONS فخادم Nginx أو ووردبريس يرمي خطأ 401 Unauthorized أو 403 Forbidden قبل ما الريكوست الحقيقي يبدأ أصلاً! المشكلة دي سببها: المتصفح في طلب الـ Preflight (OPTIONS) ما بيبعتش ترويسة Authorization ولا بيانات الدخول! لو السيرفر بتاعك مفعل فحص الصلاحيات على مستوى خادم الويب بدون استثناء طلبات OPTIONS، الاتصال كله هيفشل. الحل المعماري الحاسم في إعدادات Nginx:

# معالجة طلبات OPTIONS Preflight فوراً وتمرير ترويسات CORS
if ($request_method = 'OPTIONS') {
    add_header 'Access-Control-Allow-Origin' '$http_origin' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, PATCH, DELETE, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-WP-Nonce' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Content-Length' 0;
    add_header 'Content-Type' 'text/plain charset=UTF-8';
    return 204;
}

السطور دي بتخلي Nginx يرد فوراً بكود 204 No Content مع ترويسات الـ CORS المسموحة دون تشغيل محرك PHP، مما يتيح للمتصفح إرسال الريكوست الحقيقي المرفق به توكن المصادقة بكل سلاسة وسرعة.

المصادقة الهجينة للتطبيقات الخارجية: الجمع بين Application Passwords و JWT

في الأنظمة الحديثة التي تتكامل مع تطبيقات الهاتف الذكي أو لوحات تحكم مستقلة، توفر ووردبريس ميزة Application Passwords لتوفير وصول آمن بدون مشاركة كلمة المرور الأصلية، كما تتيح حزم JWT Tokens مصادقة آمنة ومحمية بتشفير عالي عبر رؤوس الـ Authorization Headers.