#توسيع أنواع المصادقة

#نظرة عامة

يدعم NocoBase توسيع أنواع مصادقة المستخدم حسب الحاجة. تنقسم مصادقة المستخدم بشكل عام إلى نوعين: الأول هو تحديد هوية المستخدم داخل تطبيق NocoBase نفسه، مثل تسجيل الدخول بكلمة مرور، أو تسجيل الدخول عبر الرسائل النصية القصيرة، وما إلى ذلك؛ والآخر هو أن تقوم خدمات طرف ثالث بتحديد هوية المستخدم وإبلاغ تطبيق NocoBase بالنتيجة عبر ردود الاتصال (callbacks)، مثل طرق المصادقة OIDC و SAML وغيرها. عملية المصادقة لهذين النوعين المختلفين من طرق المصادقة في NocoBase هي كالتالي:

#لا تتطلب ردود اتصال من طرف ثالث

1. يستخدم العميل حزمة تطوير البرمجيات (SDK) الخاصة بـ NocoBase لاستدعاء واجهة تسجيل الدخول api.auth.signIn()، لطلب واجهة تسجيل الدخول auth:signIn، مع تمرير معرف المصادقة الحالي عبر رأس الطلب X-Authenticator إلى الواجهة الخلفية.
2. تقوم واجهة auth:signIn بإعادة توجيه الطلب إلى نوع المصادقة المطابق بناءً على معرف المصادقة في رأس الطلب، حيث تقوم طريقة validate في فئة المصادقة المسجلة لهذا النوع بمعالجة المنطق المناسب.
3. يسترد العميل معلومات المستخدم ورمز المصادقة (token) من استجابة واجهة auth:signIn، ويحفظ الرمز في التخزين المحلي (Local Storage)، ليكمل عملية تسجيل الدخول. يتم التعامل مع هذه الخطوة تلقائيًا بواسطة SDK داخليًا.

#تعتمد على ردود اتصال من طرف ثالث

1. يحصل العميل على عنوان URL لتسجيل الدخول الخاص بالطرف الثالث عبر واجهة مسجلة خاصة به (مثل auth:getAuthUrl)، ويحمل معلومات مثل اسم التطبيق ومعرف المصادقة وفقًا للبروتوكول.
2. يتم إعادة التوجيه إلى عنوان URL الخاص بالطرف الثالث لإكمال تسجيل الدخول. تستدعي خدمة الطرف الثالث واجهة رد الاتصال لتطبيق NocoBase (التي تحتاج إلى تسجيلها بنفسك، مثل auth:redirect)، وتعيد نتيجة المصادقة، بالإضافة إلى اسم التطبيق ومعرف المصادقة ومعلومات أخرى.
3. تقوم طريقة واجهة رد الاتصال بتحليل المعلمات للحصول على معرف المصادقة، ثم تحصل على فئة المصادقة المقابلة عبر AuthManager، وتستدعي طريقة auth.signIn() بشكل مباشر. ستقوم طريقة auth.signIn() باستدعاء طريقة validate() لمعالجة منطق التفويض.
4. بعد أن تحصل طريقة رد الاتصال على رمز المصادقة (token)، يتم إعادة التوجيه (302) إلى صفحة الواجهة الأمامية، مع تمرير token ومعرف المصادقة في معلمات URL، مثل ?authenticator=xxx&token=yyy.

سنتناول لاحقًا كيفية تسجيل واجهات الواجهة الخلفية (الخادم) وواجهات المستخدم للعميل.

#الواجهة الخلفية (الخادم)

#واجهة المصادقة

يوفر جوهر NocoBase تسجيل وإدارة أنواع المصادقة الموسعة. تتطلب معالجة المنطق الأساسي لتوسيع إضافة تسجيل الدخول وراثة الفئة المجردة Auth من الجوهر وتطبيق الواجهات القياسية المقابلة. للاطلاع على واجهة برمجة التطبيقات (API) الكاملة، راجع Auth.

import { Auth } from '@nocobase/auth';

class CustomAuth extends Auth {
  set user(user) {}
  get user() {}

  async check() {}
  async signIn() {}
}

يسجل الجوهر أيضًا عمليات الموارد الأساسية المتعلقة بمصادقة المستخدم.

في معظم الحالات، يمكن لنوع مصادقة المستخدم الموسع أيضًا استخدام منطق مصادقة JWT الحالي لإنشاء بيانات اعتماد وصول المستخدم إلى واجهة برمجة التطبيقات (API). قامت فئة BaseAuth في الجوهر بتطبيق أساسي للفئة المجردة Auth، راجع BaseAuth. يمكن للإضافات وراثة فئة BaseAuth مباشرة لإعادة استخدام جزء من رمز المنطق وتقليل تكاليف التطوير.

import { BaseAuth } from '@nocobase/auth';

class CustomAuth extends BaseAuth {
  constructor(config: AuthConfig) {
    // تعيين مجموعة المستخدمين
    const userCollection = config.ctx.db.getCollection('users');
    super({ ...config, userCollection });
  }

  // تطبيق منطق مصادقة المستخدم
  async validate() {}
}

#بيانات المستخدم

عند تطبيق منطق مصادقة المستخدم، عادةً ما يتضمن ذلك معالجة بيانات المستخدم. في تطبيق NocoBase، يتم تعريف المجموعات ذات الصلة افتراضيًا على النحو التالي:

| مجموعة | الوصف | إضافة | | --------------------- | -------------------------------------------------------------------------------------------------------------------- | إضافة المستخدمين (@nocobase/plugin-users) | | authenticators | تخزين معلومات المصادقة (كيان نوع المصادقة)، بما يتوافق مع نوع المصادقة والتكوين | إضافة مصادقة المستخدم (@nocobase/plugin-auth) | | usersAuthenticators | ربط المستخدمين والمصادقات، وحفظ معلومات المستخدم تحت المصادقة المقابلة | إضافة مصادقة المستخدم (@nocobase/plugin-auth) |

بشكل عام، تستخدم طرق تسجيل الدخول الموسعة users و usersAuthenticators لتخزين بيانات المستخدم المقابلة. فقط في الحالات الخاصة قد تحتاج إلى إضافة مجموعة جديدة بنفسك.

الحقول الرئيسية لـ usersAuthenticators هي:

بالنسبة لعمليات استعلام المستخدم وإنشائه، يقوم نموذج بيانات authenticators المسمى AuthModel أيضًا بتغليف عدة طرق يمكن استخدامها في فئة CustomAuth عبر this.authenticator[اسم_الطريقة]. للاطلاع على واجهة برمجة التطبيقات (API) الكاملة، راجع AuthModel.

import { AuthModel } from '@nocobase/plugin-auth';

class CustomAuth extends BaseAuth {
  async validate() {
    // ...
    const authenticator = this.authenticator as AuthModel;
    this.authenticator.findUser(); // استعلام عن مستخدم
    this.authenticator.newUser(); // إنشاء مستخدم جديد
    this.authenticator.findOrCreateUser(); // استعلام عن مستخدم أو إنشاؤه
    // ...
  }
}

#تسجيل نوع المصادقة

يجب تسجيل طريقة المصادقة الموسعة في وحدة إدارة المصادقة.

class CustomAuthPlugin extends Plugin {
  async load() {
    this.app.authManager.registerTypes('custom-auth-type', {
      auth: CustomAuth,
    });
  }
}

#العميل

يتم تسجيل واجهة المستخدم للعميل عبر واجهة registerType التي يوفرها عميل إضافة مصادقة المستخدم:

import AuthPlugin from '@nocobase/plugin-auth/client';

class CustomAuthPlugin extends Plugin {
  async load() {
    const auth = this.app.pm.get(AuthPlugin);
    auth.registerType('custom-auth-type', {
      components: {
        SignInForm, // نموذج تسجيل الدخول
        SignInButton, // زر تسجيل الدخول (لطرف ثالث)، يمكن اختيار أحدهما بدلاً من الآخر
        SignUpForm, // نموذج التسجيل
        AdminSettingsForm, // نموذج إعدادات المسؤول
      },
    });
  }
}

#نموذج تسجيل الدخول

إذا قامت عدة مصادقات مطابقة لنوع المصادقة بتسجيل نماذج تسجيل الدخول، فسيتم عرضها على شكل علامات تبويب (Tabs). سيكون عنوان علامة التبويب هو عنوان المصادقة الذي تم تكوينه في الواجهة الخلفية.

#زر تسجيل الدخول

عادةً ما يكون هذا زر تسجيل دخول لطرف ثالث، ولكنه في الواقع يمكن أن يكون أي مكون.

#نموذج التسجيل

إذا كنت بحاجة إلى الانتقال من صفحة تسجيل الدخول إلى صفحة التسجيل، فيجب عليك معالجة ذلك بنفسك ضمن مكون تسجيل الدخول.

#نموذج إعدادات المسؤول

الجزء العلوي هو التكوين العام للمصادقة، والجزء السفلي هو جزء نموذج التكوين المخصص الذي يمكن تسجيله.

#طلب واجهات برمجة التطبيقات (APIs)

لبدء طلبات واجهات برمجة التطبيقات المتعلقة بمصادقة المستخدم من جانب العميل، يمكنك استخدام حزمة تطوير البرمجيات (SDK) التي يوفرها NocoBase.

import { useAPIClient } from '@nocobase/client';

// يُستخدم داخل المكون
const api = useAPIClient();
api.auth.signIn(data, authenticator);

للاطلاع على مراجع واجهة برمجة التطبيقات (API) التفصيلية، راجع @nocobase/sdk - Auth.