انتقل إلى محتوى الدرس
الدرس 95
تاريخ النشر: تاريخ التحديث:
دورة PHP

مصادقة واجهات API ورؤوس CORS في PHPPHP API Bearer Authentication and CORS Headers طريقة معالجة طلبات OPTIONS الاستباقية، وتوليد وتشفير رموز API، وقراءة رأس التفويض Bearer

أمّن واجهات JSON البرمجية في PHP 8 باستخدام مصادقة رموز Bearer وتخزين مفاتيح API المشفرة بـ SHA-256 وضبط رؤوس CORS ومعالجة طلبات OPTIONS الاستباقية.
أقسام الدرس
6
الأمثلة
6
اللغة
العربية
المشاهدات
31
محتوى الدرس
في هذا الدرس 6تصفّح المواضيع

عندما يتصل تطبيق واجهة أمامية يعمل على النطاق https://app.example.com بواجهة JSON API مستضافة على https://api.example.com، يفرض المتصفح سياسة النطاق الواحد (Same-Origin Policy). وما لم يرسل خادم PHP رؤوس مشاركة الموارد عبر النطاقات (CORS) التي تصرح لهذا النطاق، سيمنع المتصفح كود JavaScript من قراءة الاستجابة.

  • لا ترسل أبداً الرأس المفتوح Access-Control-Allow-Origin: * في الواجهات المحمية؛ بل افحص $_SERVER['HTTP_ORIGIN'] مقابل قائمة بيضاء صريحة باستخدام in_array($origin, $allowed, true).
  • أرسل دائماً الرأس Vary: Origin عند اختيار النطاق ديناميكياً لمنع خوادم التخزين المؤقت (CDN) من خلط رؤوس النطاقات.
  • حدد طرق HTTP والرؤوس المسموحة صراحةً عبر Access-Control-Allow-Methods وAccess-Control-Allow-Headers.

تفحص هذه الدالة النطاق الطالب مقابل قائمة بيضاء صارمة وتضبط رؤوس CORS المناسبة:

مخطط مصادقة واجهات API برموز Bearer ورؤوس CORS في PHP
PHP
<?php
$origin = $_SERVER['HTTP_ORIGIN'] ?? 'https://app.closetag.com';
$allowed = ['https://app.closetag.com', 'https://admin.closetag.com'];
$headers = ['Vary: Origin'];
if (in_array($origin, $allowed, true)) {
    $headers[] = "Access-Control-Allow-Origin: {$origin}";
    $headers[] = 'Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS';
    $headers[] = 'Access-Control-Allow-Headers: Content-Type, Authorization';
}
echo implode("\n", $headers) . "\n";

قبل أن يرسل المتصفح طلباً عابراً للنطاقات يحتوي على جسم Content-Type: application/json أو رأس المصادقة Authorization: Bearer، فإنه يرسل تلقائياً طلب فحص استباقي (CORS Preflight) بطريقة OPTIONS للتأكد من موافقة الخادم.

  • لا يرسل المتصفح رأس Authorization أثناء طلب OPTIONS الاستباقي؛ لذلك إذا شغل سكربت PHP فحص المصادقة قبل فحص طريقة OPTIONS فستفشل جميع الطلبات الاستباقية بخطأ 401!
  • اعترض الشرط $_SERVER['REQUEST_METHOD'] === 'OPTIONS' في بداية نقطة دخول الـ API، وأرسل رؤوس CORS مع كود الحالة 204 No Content وأنهِ التنفيذ فوراً.
  • أضف الرأس Access-Control-Max-Age: 86400 ليحفظ المتصفح نتيجة الفحص الاستباقي لمدة 24 ساعة بدلاً من تكرار طلب OPTIONS قبل كل استدعاء.

يوضح هذا المثال كيفية معالجة طلب OPTIONS الاستباقي فوراً قبل تشغيل أي استعلامات قاعدة بيانات:

PHP
<?php
function handleCorsPreflight(string $method, string $origin): array {
    $allowed = ['https://app.closetag.com'];
    if (!in_array($origin, $allowed, true)) return ['status' => 403, 'headers' => []];
    $headers = ["Access-Control-Allow-Origin: {$origin}", 'Access-Control-Max-Age: 86400'];
    if ($method === 'OPTIONS') return ['status' => 204, 'headers' => $headers];
    return ['status' => 200, 'headers' => $headers];
}
$res = handleCorsPreflight('OPTIONS', 'https://app.closetag.com');
echo "Status: {$res['status']} (" . count($res['headers']) . " CORS headers)\n";

تعتمد واجهات JSON API عديمة الحالة (Stateless) على رموز Bearer العشوائية لمصادقة العملاء بدلاً من كوكيز الجلسات. ولّد هذه الرموز باستخدام المولد التشفيري الآمن bin2hex(random_bytes(32)) وخزّن بصمتها المشفرة بـ SHA-256 فقط في قاعدة البيانات.

  • أضف بادئة واضحة للرمز الخام (مثل ct_live_) لمساعدة المطورين وأدوات فحص الأسرار على تمييز المفاتيح فوراً.
  • اعرض الرمز النصي الخام للمستخدم مرة واحدة فقط لحظة إنشائه، وخزّن ناتج hash('sha256', $plainToken) في عمود token_hash.
  • نظراً لأن الرمز المولد من 32 بايت عشوائي يمتلك كثافة احتمالات تبلغ 256 بت، فإن تجزئة SHA-256 آمنة تماماً ضد القواميس وتسمح بالبحث المفهرس السريع في SQL.

يولّد هذا الكود رمز API عشوائياً ببادئة قياسية ويحسب بصمة SHA-256 المكونة من 64 محرفاً لتخزينها في قاعدة البيانات:

PHP
<?php
$plainToken = 'ct_live_' . bin2hex(random_bytes(32));
$tokenHash = hash('sha256', $plainToken);
echo 'Token Prefix: ' . substr($plainToken, 0, 16) . "...\n";
echo 'SHA-256 Length: ' . strlen($tokenHash) . " hex chars\n";

يرسل العميل رمز الوصول داخل رأس HTTP القياسي Authorization: Bearer <token>. وباختلاف بيئة تشغيل PHP (سواء كانت Apache أو Nginx مع PHP-FPM)، قد يظهر هذا الرأس في مفاتيح مختلفة داخل المصفوفة $_SERVER.

  • افحص المفتاح $_SERVER['HTTP_AUTHORIZATION'] أولاً، ثم وفر بديلاً عبر $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] الذي يضعه Apache عند تفعيل إعادة توجيه الروابط.
  • استخدم التعبير النمطي preg_match('/^Bearer\s+([A-Za-z0-9_\-\.]+)$/i', trim($header), $matches) لاستخراج الرمز بدقة ورفض الرؤوس المشوهة.
  • لا تقبل أبداً إرسال مفاتيح API داخل رابط الاستعلام (?api_key=...)، لأن الروابط تُسجّل كنص مكشوف في سجلات الخادم وتاريخ المتصفح.

تستخرج هذه الدالة رمز Bearer بأمان عبر بيئات Apache وNginx المختلفة:

مخطط توليد وتشفير رموز API بـ SHA-256 والتحقق منها عبر PDO
PHP
<?php
function getBearerToken(array $server): ?string {
    $header = $server['HTTP_AUTHORIZATION']
        ?? $server['REDIRECT_HTTP_AUTHORIZATION']
        ?? '';
    if (preg_match('/^Bearer\s+([A-Za-z0-9_\-\.]+)$/i', trim($header), $m) === 1) {
        return $m[1];
    }
    return null;
}
$token = getBearerToken(['HTTP_AUTHORIZATION' => 'Bearer ct_live_9988776655']);
echo 'Extracted: ' . ($token ?? 'NONE') . "\n";

بمجرد استخراج رمز Bearer من الطلب، احسب بصمته عبر hash('sha256', $rawToken) وابحث عنها في جدول api_tokens مربوطاً بجدول users. تحقق دائماً من أن صلاحية الرمز لم تنتهِ (expires_at > :now) وأنه غير ملغى.

  • ضع فهرساً فريداً UNIQUE على العمود api_tokens(token_hash) ليتم التحقق من كل طلب API في أجزاء من المللي ثانية.
  • اربط جدول users عبر INNER JOIN في نفس الاستعلام المحضر لجلب معرف المستخدم ودوره في رحلة استعلام واحدة.
  • يمكنك تحديث حقل last_used_at لتمكين المستخدم من مراقبة آخر استخدام لكل مفتاح API من إعدادات حسابه.

يتحقق هذا المثال عبر PDO من بصمة الرمز وتاريخ انتهاء صلاحيته ويجلب بيانات المستخدم المالك له:

PHP
<?php
$pdo = new PDO('sqlite::memory:');
$pdo->exec('CREATE TABLE users (id INT, name TEXT, role TEXT)');
$pdo->exec('CREATE TABLE api_tokens (user_id INT, token_hash TEXT UNIQUE, expires_at INT)');
$raw = 'ct_live_secret_token_99';
$pdo->exec("INSERT INTO users VALUES (5, 'Omar Khaled', 'editor')");
$pdo->prepare('INSERT INTO api_tokens VALUES (5, :h, :e)')->execute(['h' => hash('sha256', $raw), 'e' => time() + 3600]);
$stmt = $pdo->prepare('SELECT u.id, u.name, u.role FROM api_tokens t JOIN users u ON u.id = t.user_id WHERE t.token_hash = :h AND t.expires_at > :now');
$stmt->execute(['h' => hash('sha256', $raw), 'now' => time()]);
echo json_encode($stmt->fetch(PDO::FETCH_ASSOC)) . "\n";

عندما يفشل طلب الـ API في المصادقة أو يتجاوز حصة الطلبات المسموحة، لا تقم أبداً بإعادة توجيه العميل إلى صفحة تسجيل دخول HTML؛ بل أعد استجابة خطأ بصيغة JSON موحدة مع رمز حالة HTTP القياسي والرؤوس المرافقة.

  • أعد الحالة 401 Unauthorized مع الرأس WWW-Authenticate: Bearer عند غياب الرمز أو عدم صحته أو انتهاء صلاحيته.
  • أعد الحالة 403 Forbidden عندما يكون الرمز صحيحاً ولكن المستخدم لا يمتلك الصلاحية الكافية لتنفيذ الإجراء المطلوب.
  • أعد الحالة 429 Too Many Requests مع الرأس Retry-After عند تجاوز الحد المسموح من الطلبات في الدقيقة.

يلخص الجدول التالي رموز الحالة القياسية والرؤوس المرافقة لها في واجهات PHP JSON API المحمية:

رمز حالة HTTPالحالة التي يمثلهاالرأس المرافق المطلوب
204 No Contentنجاح طلب الفحص الاستباقي OPTIONSAccess-Control-Allow-Origin وAccess-Control-Max-Age
401 Unauthorizedغياب رمز Bearer أو عدم صحته أو انتهاء صلاحيتهWWW-Authenticate: Bearer
403 Forbiddenالرمز موثق لكن المستخدم لا يملك صلاحية الوصولContent-Type: application/json
429 Too Many Requestsتجاوز حصة الطلبات المسموحة في النافذة الزمنيةRetry-After: 60
PHP
<?php
function jsonApiError(int $status, string $code, string $message): string {
    return json_encode([
        'ok' => false,
        'status' => $status,
        'error' => ['code' => $code, 'message' => $message],
    ], JSON_UNESCAPED_UNICODE);
}
echo jsonApiError(401, 'TOKEN_EXPIRED', 'Your Bearer token has expired.') . "\n";
echo jsonApiError(429, 'QUOTA_EXCEEDED', 'Rate limit exceeded. Retry in 60s.') . "\n";
خلاصة المعرفة ومحطة الانتقال

ملخص الدرس

حصاد الدرس

مراجعة مركّزة لأهم المفاهيم والقواعد الهندسية التي أتقنتها في هذا الدرس قبل التطبيق العملي

ماذا تعلّمت في هذا الدرس؟

أتقنت في هذا الدرس ضبط رؤوس CORS بقائمة بيضاء، ومعالجة طلبات OPTIONS الاستباقية بكود 204، وتوليد وتشفير رموز Bearer بـ SHA-256، والتحقق منها عبر PDO، وإرجاع أخطاء 401 و429 القياسية. في الوحدة التالية سننتقل إلى بناء تطبيق الويب المتكامل بدءاً من الموجه ومعمارية MVC.

مشاركة

هل كان هذا الدرس مفيدًا؟

جارٍ تحميل الآراء…

ابنِ لغتك البرمجية

المصطلحات4

راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.

0 / 4 مفهومةأول بطاقة، أول خطوة
01 Cross-Origin Resource Sharing (CORS) مشاركة الموارد عبر النطاقات (CORS)
آلية تعتمد على رؤوس HTTP تسمح للخادم بتحديد النطاقات الخارجية المسموح لها بقراءة استجاباته داخل المتصفح.
للمراجعة
02 Preflight Request (OPTIONS) طلب الفحص الاستباقي (OPTIONS Preflight)
طلب OPTIONS تلقائي يرسله المتصفح قبل الطلبات العابرة للنطاقات التي تضم رؤوساً مخصصة مثل Authorization أو جسم JSON.
للمراجعة
03 Bearer Token Authentication مصادقة رمز الحامل (Bearer Token)
نظام مصادقة عديم الحالة يرسل فيه العميل رمزاً سرياً داخل الرأس Authorization: Bearer مع كل طلب.
للمراجعة
04 SHA-256 Token Digest بصمة الرمز المشفرة (SHA-256 Digest)
بصمة سداسية عشرية بطول 64 محرفاً غير قابلة للعكس تُخزن في قاعدة البيانات بدلاً من رمز API النصي الخام.
للمراجعة

اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.

حروف قليلة. معنى كامل.

الاختصارات4

راجع المعنى، اشرحه لنفسك، ثم علّم البطاقة كمفهومة.

0 / 4 مفهومةأول بطاقة، أول خطوة
01 CORS مشاركة الموارد عبر النطاقات
Cross-Origin Resource Sharing
بروتوكول أمان في المتصفح ينظم الطلبات العابرة للنطاقات عبر رؤوس Access-Control-*.
للمراجعة
02 API واجهة برمجة التطبيقات
Application Programming Interface
نقاط نهاية برمجية تتبادل بيانات JSON المهيكلة بين التطبيقات والخادم.
للمراجعة
03 CSPRNG مولد أرقام عشوائية آمن تشفيرياً
Cryptographically Secure Pseudo-Random Number Generator
مصدر عشوائية تشفيري في نظام التشغيل يُستدعى عبر random_bytes() لتوليد رموز غير قابلة للتخمين.
للمراجعة
04 SPA تطبيق الصفحة الواحدة
Single-Page Application
تطبيق واجهة أمامية يتخاطب مع خادم PHP عبر واجهات JSON API المدعومة برؤوس CORS.
للمراجعة

اقرأ البطاقات بحرية. سجّل الدخول لحفظ تقدم مراجعتك.

من الفهم للتطبيق

مهامك قبل الاختبار

خطوة صغيرة كل مرة. وإنجاز تقدر ترجع له.

0/2مهام منجزة
  1. اكتب فحصاً في PHP يتحقق من وجود النطاق ضمن القائمة البيضاء ويرد على طلبات OPTIONS بكود 204 مع رأس Access-Control-Allow-Headers.

  2. استخرج رمز Bearer من رأس Authorization عبر preg_match() واحسب بصمته بـ hash("sha256", $token) للبحث عنه في جدول api_tokens.

تأشير المهمة إقرار منك بإتمامها، وليس تصحيحًا آليًا للكود. يُحفظ تقدمك في حسابك.

مساحة التحدي

اختبر فهمك.
ووصلها للإتقان.

كل سؤال خطوة لقدّام. اختار، اكتب كود، وشوف نتيجتك فورًا.

8أسئلة 3أنواع تحديات 100%هدف الإتقان
تصحيح تلقائي. فرص بلا حدود.

أكمل المهام، واجمع كل الإجابات الصحيحة. أقل من 100%؟ راجع وأعد المحاولة.

الأسئلة متاحة للاطلاع. سجّل الدخول للتفاعل وحفظ تقدمك.

لمحة عن التحدي8 أسئلة تنتظرك
01

لماذا يجب إرسال الرأس "Vary: Origin" عند تحديد قيمة Access-Control-Allow-Origin ديناميكياً من قائمة بيضاء؟

يخبر الرأس Vary: Origin خوادم التخزين المؤقت بعدم تقديم استجابة CORS المخزنة لنطاق معين إلى زائر قادم من نطاق آخر.

02

ماذا يحدث إذا قام سكربت الـ API بفحص رمز Bearer قبل التحقق مما إذا كانت طريقة الطلب هي OPTIONS؟

لا يرسل المتصفح رأس Authorization في طلبات OPTIONS الاستباقية، مما يؤدي لفشل الفحص الاستباقي بخطأ 401 وحظر الطلب الفعلي.

03

يجب تشفير رموز API المولدة عبر random_bytes(32) بدالة التجزئة hash("sha256", $token) قبل حفظها في قاعدة البيانات.

صواب؛ حفظ بصمة SHA-256 فقط يحمي حسابات المستخدمين حتى لو تسربت بيانات جدول الرموز.

04

لماذا يجب إرسال رموز API داخل الرأس "Authorization: Bearer" بدلاً من رابط الاستعلام (?api_key=...)؟

معاملات الرابط تُسجّل كنص واضح في سجلات الخادم وسجل تصفح المتصفح ورأس Referer، مما يعرض المفتاح للتسريب.

05

أي شرط في استعلام SQL يضمن رفض رموز API منتهية الصلاحية مباشرةً أثناء التحقق عبر PDO؟

إضافة الشرط AND expires_at > :now يستبعد الرموز منتهية الصلاحية مباشرة أثناء الاستعلام.

06

ما رمز حالة HTTP القياسي الذي يجب أن تعيده واجهة JSON API عند غياب رمز Bearer أو عدم صحته؟

الرمز 401 Unauthorized هو الرمز القياسي لفشل المصادقة بسبب غياب الرمز أو عدم صلاحيته.

07

اختر جميع الممارسات الأمنية الصحيحة عند بناء واجهة API تدعم CORS ورموز Bearer في PHP:

فحص النطاق في قائمة بيضاء، والرد المبكر على OPTIONS بكود 204، وتشفير الرموز بـ SHA-256 هي الممارسات الأساسية.

08

عند تجاوز العميل لحد الطلبات في واجهة API، فإن إرجاع الكود 429 Too Many Requests مع الرأس Retry-After يحدد للعميل عدد الثواني اللازمة للانتظار قبل إعادة المحاولة.

صواب؛ الكود 429 مع الرأس Retry-After هو المعيار القياسي لتحديد معدل الطلبات في واجهات API.