إعداد موفري تسجيل الدخول
يسجّل الناس الدخول إلى Excubius بحساب مؤسستهم، من Microsoft Entra ID أو Google. ولا يخزّن Excubius كلمة مرور الدليل أبدًا: فهو يتلقى رمزًا مميزًا موقّعًا من الموفر ويتحقق منه، ويحتفظ بالحساب على أنه الموفر مضافًا إليه معرّف الشخص لديه، وليس بعنوان بريد إلكتروني وحده أبدًا. يوضح هذا الدليل كيفية تسجيل Excubius لدى كل موفر وكيفية تحديد من يحصل على حساب.
قبل البدء
- اعرف العنوان العام للخادم،
https://<primary name>. يبدأ كل عنوان إعادة توجيه أدناه به. ويُحوَّل الأشخاص الذين يفتحون Excubius عبر اسم مستعار إلى الاسم الأساسي لتسجيل الدخول، لذلك يكفي عنوان إعادة توجيه واحد لكل موفر. راجع إعداد الأسماء وTLS. - استخدم HTTPS. لا يقبل Microsoft Entra ID البروتوكول
httpإلا معlocalhost. - تحتاج إلى الوصول إلى ملف إعدادات الخادم
/opt/excubius/.env، أو إلى برنامج التثبيت: يسألsudo ./install.sh --reconfigureعن قيم Entra ID من جديد. - لتشغيل تسجيل الدخول عبر Google أو إيقافه تحتاج إلى دور Super admin. ولاختيار من يحصل على حساب على كيان ما تحتاج إلى Entity admin عليه.
كيف يُحسم أول تسجيل دخول
تُمنح الأدوار فقط عند إنشاء الحساب أو قبول دعوة. ويسجّل الحساب الموجود الدخول بالأدوار التي يملكها، ولذلك لا يُعاد منح دور أزاله مسؤول عند تسجيل الدخول التالي.
تسجيل Excubius في Microsoft Entra ID
تسجيل الدخول باستخدام Microsoft Entra ID جزء من خطط Core وPro وEnterprise.
أنشئ تسجيل تطبيق واحدًا لكل تثبيت، لمستأجر واحد. وتسجيلات المستأجرين المتعددين (common أو organizations) غير مدعومة.
- في Microsoft Entra admin center، افتح App registrations وحدد New registration.
- Name: ما سيراه الناس في مطالبة الموافقة، مثل الاسم الذي يعرفون المراقبة به.
- Supported account types: Accounts in this organizational directory only (single tenant).
- Redirect URI: المنصة Web،
https://<primary name>/api/v1/auth/entra/callback.
- في Overview، انسخ Directory (tenant) ID وApplication (client) ID.
- ضمن Certificates & secrets › Client secrets، حدد New client secret وانسخ Value، وليس المعرّف. يظهر مرة واحدة فقط. دوّن تاريخ انتهاء الصلاحية: يتوقف تسجيل الدخول عند انتهاء صلاحية السر، لذا أنشئ السر التالي قبل ذلك واستبدل القيمة.
- ضمن Authentication، أبقِ Access tokens وID tokens للتدفقات الضمنية والمختلطة معطّلة، واترك Front-channel logout URL فارغًا. يستخدم Excubius تدفق رمز التفويض (authorization code flow) مع PKCE.
- ضمن API permissions، أبقِ أذونات Microsoft Graph المفوَّضة
openidوprofileوemail. أماUser.Readالتي تُضاف افتراضيًا فلا ضرر منها. امنح موافقة المسؤول إذا كان المستأجر لديك لا يسمح للمستخدمين بالموافقة بأنفسهم. - ضمن Token configuration، حدد Add optional claim، ونوع الرمز المميز ID، والمطالبة
email، ووافق على المطالبة التي تضيف إذن Graph الخاص بـemail. وبدونه يستخدم Excubiuspreferred_username، وهو مناسب عندما تكون أسماء المستخدمين الأساسية (user principal names) عناوين بريد إلكتروني. - اختياريًا، لمنح أدوار لمجموعات الدليل، حدد Add groups claim ضمن Token configuration:
- اختر Groups assigned to the application، ثم عيّن المجموعات ضمن Enterprise applications › تطبيقك › Users and groups. يُبقي هذا الرموز المميزة صغيرة ولا يحمل إلا المجموعات التي تربطها. ويعمل Security groups أيضًا.
- بالنسبة إلى الرمز المميز ID، اختر Group ID. يطابق Excubius معرّفات كائنات المجموعات؛ ولا تتطابق الأسماء.
- يحمل الرمز المميز 200 مجموعة على الأكثر. وبعد ذلك لا يرسل Entra ID أي مجموعات، ويعامل Excubius الشخص على أنه لا ينتمي إلى أي مجموعات دليل على الإطلاق.
- اختياريًا، ضمن Enterprise applications › تطبيقك › Properties، اضبط Assignment required? على Yes. عندئذٍ لا يستطيع تسجيل الدخول إلا المستخدمون والمجموعات المعيّنون للتطبيق، قبل أن يطبق Excubius قواعده الخاصة.
الآن أعطِ القيم إلى Excubius:
-
اتصل بالخادم، وتحوّل إلى حساب الخدمة باستخدام
sudo -iu excubius، وأضف القيم الثلاث إلى/opt/excubius/.env:ENTRA_TENANT_ID=8f6a1c2e-4b3d-4e5f-9a8b-7c6d5e4f3a2bENTRA_CLIENT_ID=11111111-2222-3333-4444-555555555555ENTRA_CLIENT_SECRET=<the secret value> -
أعد تشغيل المنصة:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
تعرض صفحة تسجيل الدخول Sign in with Microsoft بمجرد ضبط القيم الثلاث كلها. ويُقرأ سر العميل من ملف الإعدادات فقط: فلا يُكتب أبدًا في قاعدة البيانات، ولا تعيده واجهة API أبدًا، ولا يُسجَّل في السجلات أبدًا.
تسجيل Excubius لدى Google
- في Google Cloud console، افتح Google Auth Platform.
- Audience: Internal عندما يملك الجميع حساب Google Workspace تابعًا لمؤسستك؛ وExternal فيما عدا ذلك. انشر التطبيق، أو أضف مستخدمين تجريبيين أثناء الاختبار.
- Data access: الأذونات (scopes)
openidو.../auth/userinfo.emailو.../auth/userinfo.profile.
- ضمن Clients، حدد Create client، والنوع Web application، وأضف عنوان URI المصرّح به لإعادة التوجيه
https://<primary name>/api/v1/auth/google/callback. لا تحتاج إلى أي JavaScript origins. - انسخ Client ID وClient secret إلى
/opt/excubius/.envعلى أنهماGOOGLE_CLIENT_IDوGOOGLE_CLIENT_SECRET، ثم أعد تشغيل المنصة كما في خطوات Entra ID. - تحقق من أن الميزة
access.google_loginمفعّلة في Settings › Instance. وهي مفعّلة افتراضيًا.
تعرض صفحة تسجيل الدخول Sign in with Google. وطالما كان access.google_login معطّلًا، يُرفض تسجيل الدخول عبر Google ولا يقتصر الأمر على إخفائه.
يستطيع أي شخص إنشاء حساب Google شخصي بأي عنوان بريد إلكتروني يتلقى عليه الرسائل. لذلك يُحتسب تسجيل الدخول عبر Google لنطاق مسموح به فقط عندما تكون Google هي الجهة الموثوقة للعنوان: أي حساب Google Workspace تابع للنطاق نفسه تمامًا، بعنوان موثّق. أما حسابات Google الشخصية فتحتاج دائمًا إلى دعوة، وفي حالة الدعوة يجب أن تُبلغ Google بأن العنوان موثّق.
اختيار من يحصل على حساب
لكل كيان وضع تسجيل ينطبق عليه وعلى كل ما تحته، إلى أن يضبط كيان أدنى وضعه الخاص.
| الوضع | أول تسجيل دخول دون دعوة | الدور الممنوح |
|---|---|---|
| By invitation (الافتراضي) | يُرفض | — |
| Allowed domains | يُقبل عندما يكون نطاق عنوان البريد الإلكتروني في القائمة. والمطابقة تامة؛ ولا تُحتسب النطاقات الفرعية | Default role (Viewer ما لم تختر غيره؛ ولا يكون Super admin أبدًا) على الكيان الذي يضبط التسجيل، ويرثه ما تحته مثل أي دور |
لضبطه:
- افتح Settings › Users and roles واختر الكيان في أداة الاختيار، مثل شركة خان الخليلي.
- حدد علامة التبويب Registration. تذكر الصفحة مصدر الإعداد الحالي: هذا الكيان، أو كيان أعلى منه، أو التثبيت.
- اختر By invitation أو Allowed domains.
- بالنسبة إلى Allowed domains، أدخل Domains، مفصولة بفواصل أو مسافات (حتى 50)، مثل
ciguapa.example، واختر Default role. - حدد Save.
لجعل كيان أدنى يتبع أصله مرة أخرى، حدد Inherit from above again.
- الشخص الذي يكون نطاقه مسموحًا به على عدة كيانات يحصل على الدور الافتراضي لكل منها.
- على الكيان الجذر، يسري إعداد التثبيت
ALLOWED_SIGNUP_DOMAINSإلى أن يُحفظ تسجيل هناك. ويعني Allowed domains مع تلك النطاقات ودور Viewer على الجذر. وحفظ تسجيل الجذر، حتى بوضع By invitation، يستبدله. - يتوقف الكيان المضبوط على By invitation عن منح الأدوار بحسب النطاق بنفسه، لكنه لا يستطيع سحب دور موروث من تسجيل كيان أعلى.
- لمنع شخص من الدخول، عطّل حسابه. إزالة النطاق لا تؤثر في الحسابات الموجودة. راجع إدارة المستخدمين والأدوار.
الدعوات وتسجيل الدخول
الدعوة رابط، https://<primary name>/invite/<token>، ينشئه مسؤول كيان لعنوان بريد إلكتروني واحد ودور وكيان؛ راجع دعوة شخص. وعندما يفتحه الشخص:
- تعرض الصفحة الكيان والدور ومن دعاه وعنوانًا مقنّعًا، ثم أزرار تسجيل الدخول. ويُطلب من الموفر تحديد العنوان المدعو مسبقًا.
- يجب أن يكون عنوان الحساب الذي يسجّل به الدخول هو العنوان المدعو، وتتم المقارنة دون اعتبار لحالة الأحرف.
- يُنشأ الحساب، أو يُربط حساب موجود لدى الموفر نفسه، ويُمنح الدور على الكيان المدعو إليه. ويُرفع أي دور أدنى موجود هناك؛ أما الدور الأعلى فيُبقى.
- فتح الرابط مرة أخرى لاحقًا يسجّل دخول الشخص ببساطة.
عند رفض تسجيل الدخول
يعود المتصفح إلى صفحة تسجيل الدخول مع شرح واضح، ويُكتب كل رفض في سجل التدقيق بصيغة login.failed مع سببه.
| الرمز | المعنى | ما الذي تفعله |
|---|---|---|
not_invited | لا توجد دعوة، ولا يقبل أي كيان التسجيل بحسب النطاق؛ أو رابط الدعوة غير معروف | ادعُ الشخص، أو اسمح بنطاقه |
domain_not_allowed | يوجد تسجيل بحسب النطاق، لكن ليس لهذا النطاق، أو أن الموفر ليس الجهة الموثوقة له، كما في حساب Google الشخصي | أضف النطاق، أو ادعُ الشخص |
account_disabled | الحساب موجود وهو معطّل | فعّله في Users and roles |
email_mismatch | عنوان الحساب ليس العنوان المدعو، أو لم تتحقق Google منه | سجّل الدخول بالحساب المدعو، أو ادعُ العنوان الصحيح |
invite_expired | انتهت صلاحية الدعوة، أو استخدمها شخص آخر بالفعل | أرسل دعوة جديدة |
invalid_state | استغرق تسجيل الدخول أكثر من 10 دقائق، أو بدأ في متصفح أو تبويب آخر، أو لم يطابق الرد الطلب | ابدأ من جديد من صفحة تسجيل الدخول |
provider_error | رفض الموفر (رُفضت الموافقة أو أُلغيت)، أو لم يُضبط أو تم إيقافه، أو فشل التحقق من ردّه | تحقق من إعدادات الموفر أعلاه ومن إدخال سجل الواجهة الخلفية auth.login_refused |
تسجيل الخروج من Excubius لا يسجّل خروج الشخص من Microsoft أو Google.