Yii2 Auth Modules — SSO, OTP, Biometric

صفحة توثيق تفصيلية جاهزة للدمج داخل مشروع Yii2 (Advanced/Basic). تحتوي على شرح، إعدادات، وقوالب كود لميزات:

• تسجيل الدخول الموحد (SSO) — Google / Microsoft
• OTP عبر SMS و WhatsApp
• المصادقة الحيوية (Biometric) عبر WebAuthn / Passkeys

ملخص الحزمة

الحزمة تتضمن موديولات ومكونات جاهزة للنسخ داخل مشروعك:

• common/modules/sso
• common/modules/otp
• common/modules/biometric
• common/components/SmsComponent.php و common/components/WhatsappComponent.php
• أمثلة إعدادات في config_examples/ وملف SQL لـ WebAuthn

خطوات التثبيت السريعة

1. انسخ الملفات إلى مجلدات المشروع: common/modules/, common/components/.
2. ثبت الحزم المطلوبة عبر Composer:

composer require yiisoft/yii2-authclient
composer require web-auth/webauthn-framework
composer require twilio/sdk
composer require guzzlehttp/guzzle

تكوين (config)

أضف إلى config/main.php أو frontend/config/main.php:

'modules' => [
  'sso' => ['class' => 'common\modules\sso\Module'],
  'otp' => ['class' => 'common\modules\otp\Module'],
  'biometric' => ['class' => 'common\modules\biometric\Module'],
],
'components' => [
  'authClientCollection' => [
    'class' => 'yii\authclient\Collection',
    'clients' => [
      'google' => [
        'class' => 'yii\authclient\clients\Google',
        'clientId' => 'YOUR_GOOGLE_CLIENT_ID',
        'clientSecret' => 'YOUR_GOOGLE_CLIENT_SECRET',
      ],
      'microsoft' => [
        'class' => 'yii\authclient\clients\Azure',
        'clientId' => 'YOUR_AZURE_CLIENT_ID',
        'clientSecret' => 'YOUR_AZURE_CLIENT_SECRET',
      ],
    ],
  ],
  'sms' => [ 'class' => 'common\\components\\SmsComponent', 'apiKey' => 'YOUR_SMS_API_KEY' ],
  'whatsapp' => [ 'class' => 'common\\components\\WhatsappComponent', 'accessToken' => 'YOUR_WHATSAPP_ACCESS_TOKEN', 'phoneNumberId' => 'YOUR_PHONE_NUMBER_ID' ],
],

قواعد البيانات

نفّذ ملف SQL لإنشاء جدول اعتماد WebAuthn:

CREATE TABLE `webauthn_credentials` (
  `id` int NOT NULL AUTO_INCREMENT,
  `user_id` int NOT NULL,
  `credential` longtext NOT NULL,
  `created_at` int NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

تعديل نموذج المستخدم (User)

تأكد أن نموذج User يحتوي الحقول التالية: id, username, email, phone, password_hash, auth_key، وأضف الوظائف:

public function setPassword($password)
{
  $this->password_hash = Yii::$app->security->generatePasswordHash($password);
}

public function generateAuthKey()
{
  $this->auth_key = Yii::$app->security->generateRandomString();
}

شرح الموديولات والواجهات

SSO (Google / Microsoft)

صفحة التسجيل تعرض أزرار OAuth من yii\authclient. بعد المصادقة يرسل الموفر بيانات المستخدم (email, name) ويُنشئ حسابًا إذا لم يكن موجودًا.

OTP (SMS / WhatsApp)

تدفق العملية:

• المستخدم يدخل رقم الجوال.
• النظام يولد OTP (6 أرقام) ويخزّنه مؤقتًا (Session أو Redis).
• يرسل الكود عبر SmsComponent أو WhatsappComponent.
• المستخدم يدخل الكود → النظام يتحقق ويقوم بتسجيل الدخول أو إنشاء المستخدم.

Biometric (WebAuthn)

الاتجاه الصحيح للتطبيقات الحديثة: WebAuthn / Passkeys. المتصفح/الجهاز يولّد مفتاحًا خاصًا ويخزن العام على الخادم. يتطلب HTTPS.

نصائح أمان مهمة

• اجعل الموقع يعمل عبر HTTPS دائماً (مطلوب للـ WebAuthn وOAuth).
• لا تحتفظ بمفاتيحك في ملفات عامة — استخدم secrets/env.
• استخدم تخزين آمن للمفاتيح العامة والاعتمادات (encrypt at rest).
• فعّل CSRF وHTTP-only & Secure cookies.

خيارات تخصيص مستقبلية

• إضافة موفري OAuth آخرين (Facebook, Apple, LinkedIn).
• دعم إعادة المحاولة والـ rate-limit للـ OTP.
• Webhook لاستقبال ردود WhatsApp واستكمال التحقق أو الاعتماد التلقائي.
• إنشاء migrations وcomposer script للتثبيت الآلي.

الخطوات التالية أقدمها لك

1. أدمج الملفات داخل مشروعك — أستطيع تجهيز سكربت تثبيت (install.php) أو Shell.
2. أجهز Migration جاهز لقاعدة البيانات (WebAuthn + أي تغييرات على User).
3. أقوم بضبط Config تلقائياً إذا أعطيتني ملف config/main.php أو هيكل User.