لماذا تختار ZITADEL بدلاً من Authentik أو Keycloak؟
تحتل ZITADEL مكانة محددة بين منصات المصادقة مفتوحة المصدر. على عكس Authelia (وسيط مصادقة بلا إدارة مستخدمين خاصة) أو Authentik (IdP متكامل غني بالميزات)، تستهدف ZITADEL فرق التطوير التي تريد IAM بمستوى المؤسسات منذ اليوم الأول: دعم أصلي لتعدد المستأجرين، وواجهات gRPC وREST كاملة، ومزوّد Terraform رسمي (zitadel/zitadel في سجل Terraform).
احذر من أرقام الذاكرة. تذكر وثائق التشغيل أن ZITADEL نفسها تحتاج إلى نحو 512 ميغابايت من الذاكرة وأقل من نواة معالج واحدة، دون قاعدة البيانات، مع ذروات في المعالج عند تجزئة كلمات المرور. أعلنت النسخة السابقة من هذه المقالة «أقل من 100 ميغابايت»: هذا الرقم غير وارد في الوثائق، فلا تحدد حجم الـVPS بناءً عليه. ولا تُقدَّر هنا مقارنة الموارد مع Keycloak لغياب قياس موثّق.
المتطلبات الأساسية بالأرقام
- الـVPS: معالجان افتراضيان (2 vCPU) و2 غيغابايت من الذاكرة (يطلب دليل Docker Compose الرسمي 2 غيغابايت على الأقل)، وUbuntu 24.04. خطط لموارد أكبر مع نمو القاعدة: يحسب المشروع نحو 4 غيغابايت لكل نواة قاعدة بيانات.
- Docker: الإصدار 24 أو أحدث من Docker Engine مع Compose v2؛ الأداة القديمة
docker-compose(v1) غير مدعومة. - PostgreSQL: الإصدارات من 14 إلى 18 مدعومة. يستخدم قالب ServOrbit الإصدار 16.
- المنافذ: تستمع ZITADEL داخلياً على
8080. يجب أن يكون 443وحده عاماً (مع 80إذا تركت Let's Encrypt تصدر الشهادة). يربط القالب 8080بالعنوان 127.0.0.1ويترك nginx يخدم الخارج. - النطاق: اسم أو نطاق فرعي يشير إلى عنوان IP للـVPS، مثل
auth.your-domain.com، عبر HTTPS. - المفتاح الرئيسي: يجب أن يتكون
ZITADEL_MASTERKEYمن 32 حرفاً بالضبط، ولا يمكن تغييره بعد التهيئة دون فقدان الوصول إلى البيانات المشفرة. يولّده القالب؛ احتفظ بنسخة منه خارج الـVPS.
تثبيت ZITADEL من Marketplace
التثبيت في 3 خطوات
إنشاء الـVPS
من منطقة العميل في ServOrbit، اختر فئة VPS وانقر على تكوين. في حقل التطبيق، اختر ZITADEL. أدخل نطاقك (مثل
auth.your-domain.com).إذا لم يكن لديك نطاق، يتوفر النطاق الفرعي المجاني من ServOrbit فوراً مع HTTPS.
البدء التلقائي
يولّد سكريبت التثبيت
MASTERKEYوكلمة مرور PostgreSQL وكلمة مرور المشرف، ثم يشغّل PostgreSQL 16 وZITADEL عبر Docker Compose. المدة المعتادة: من 2 إلى 4 دقائق.الوصول إلى لوحة التحكم
بعد اكتمال التثبيت تظهر بيانات اعتمادك في منطقة العميل.
- URL: https://<your-domain>/ui/console
- اسم المستخدم: admin. إذا رفضته الصفحة فجرّب admin@zitadel.<your-domain>: تركّب ZITADEL أسماء الدخول على شكل مستخدم@مؤسسة.نطاق، كما في مثال [email protected]في الوثائق الرسمية.
- كلمة المرور: المُولَّدةسجّل الدخول وغيّرها فوراً.
ما الذي ينشره القالب
القالب ملف Docker Compose بخدمتين: db (PostgreSQL 16) وzitadel، تُشغَّل بالأمر start-from-init --tlsMode disabled --masterkeyFromEnv. وبالتالي ينهي nginx اتصال TLS لا ZITADEL. الصورة المتّبعة هي الوسم stable من ghcr.io/zitadel/zitadel، أي أن الإصدار الذي يعمل فعلاً يتوقف على يوم سحب الصورة: تحقق منه بالأمر docker compose images (انظر قسم التحديثات).
يُمرَّر النطاق إلى ZITADEL_EXTERNALDOMAIN مع ZITADEL_EXTERNALPORT=443 وZITADEL_EXTERNALSECURE=true. يعدّ القالب النطاق ثابتاً منذ أول تشغيل: اختر النطاق الصحيح من البداية.
النطاق الخارجي وTLS والوكيل العكسي
- ثلاث قيم يجب أن تتطابق — يجب أن تصف
ZITADEL_EXTERNALDOMAINوZITADEL_EXTERNALPORTوZITADEL_EXTERNALSECUREالعنوان العام الحقيقي. لا تخدم ZITADEL إلا الطلبات المرسلة إلى البروتوكول والمضيف والمنفذ المتوقعة، وإلا ظهرت رسالة «Instance not found». - تغيير النطاق — توثّق الوثائق الرسمية أن هذه الخيارات يمكن تغييرها في أي وقت بشرط إعادة تشغيل مرحلة الإعداد. فهو ليس مستحيلاً كما زعمت النسخة السابقة، لكنه ليس إجراءً هيناً: كل تطبيق عميل يشير إلى العنوان القديم.
- الإبقاء على المضيف — يجب أن ينقل الوكيل العكسي ترويسة
Hostالأصلية وX-Forwarded-Proto: https. ينهي مثال nginx الرسمي اتصال TLS ثم يخاطب ZITADEL عبر HTTP/2 غير مشفر (h2c) باستخدام grpc_pass. - HTTP/2 من الطرف إلى الطرف — تتطلب لوحة التحكم HTTP/2 حتى ZITADEL. الوكلاء الذين اختبرهم المشروع هم Traefik v3 وNGINX 1.x المستقر وCaddy v2 وApache httpd 2.4.
- CDN أو WAF في المقدمة — تنص الوثائق على أن أي وكيل أو WAF أو CDN أمام ZITADEL يجب أن يدعم HTTP/2 أيضاً. اختبر لوحة التحكم بعد أي تحويل لـDNS إلى وضع الوكيل.
إنشاء أول تطبيق OIDC
بعد تسجيل الدخول إلى لوحة تحكم ZITADEL:
1. انتقل إلى Projects ثم Create
2. سمِّ مشروعك (مثل My App)
3. انقر على Add Application
4. اختر النوع: Web (تطبيقات الخادم) أو Native (الجوال/سطح المكتب) أو API (آلة إلى آلة)
5. لتطبيق الويب اختر PKCE (موصى به) وأدخل Redirect URIs
تولّد ZITADEL قيمة Client ID. دوّن نقطة الاكتشاف الخاصة بـOIDC: https://<your-domain>/.well-known/openid-configuration.
ربط ZITADEL بتطبيقاتك المستضافة ذاتياً
يمكن لأي تطبيق يتحدث OIDC أن يعتمد على ZITADEL: يكفي Client ID والسر إن وجد ونقطة الاكتشاف. أمثلة شائعة:
- Gitea: إدارة الموقع، المصادقة، إضافة مصدر OAuth2 من نوع OpenID Connect، ثم إدخال Client ID والسر ونقطة الاكتشاف
- Grafana: قسم
[auth.generic_oauth]في grafana.iniمع عناوين التفويض والرمز ومعلومات المستخدم الخاصة بـZITADEL - Nextcloud: تطبيق
Social Loginأو OpenID Connect user backend - أي تطبيق OIDC آخر: أدخل نقطة الاكتشاف وClient ID وعناوين Redirect URIs المعلنة في المشروع؛ وراجع وثائق التطبيق للإعدادات الدقيقة
إدارة تعدد المستأجرين: المؤسسات والمشاريع
تقوم ZITADEL على نموذج أصلي لتعدد المستأجرين: تنشئ عدة مؤسسات (مثلاً واحدة لكل عميل من عملاء منصتك)، لكل منها مستخدموها وسياسات الدخول الخاصة بها. ويمكن لكل مؤسسة أن تملك مشاريعها وأدوارها.
انتبه: الأدوار لا تُضاف إلى الرموز تلقائياً خلافاً لما زعمته النسخة السابقة. عليك تفعيل Assert Roles on Authentication في المشروع للحصول عليها عبر userinfo، أو User Roles Inside ID Token في التطبيق، وطلب نطاق الأدوار urn:zitadel:iam:org:project:{projectId}:roles. وأضف كذلك urn:zitadel:iam:org:project:id:{projectId}:aud إذا ظهرت رسالة «Invalid audience».
نصيحة: فعّل مفاتيح المرور منذ البداية
في إعدادات المثيل فعّل مصادقة Passkey/WebAuthn. سيتمكن مستخدموك من الدخول دون كلمة مرور من متصفحهم.
اكتشاف النطاق: ما الذي يُفترض أن يعمل
يوجّه اكتشاف النطاق (Domain Discovery) المستخدم إلى المؤسسة الصحيحة بحسب نطاق بريده الإلكتروني. في السيناريو الذي تصفه الوثائق الرسمية يُحوَّل مستخدم [email protected] إلى مزوّد الهوية في شركته، ويرى مستخدم [email protected] صفحة دخول بكلمة مرور وMFA، ويقع النطاق المجهول في المؤسسة الافتراضية.
الشروط الواردة في الدليل الرسمي هي:
- المثيل — خيار «Domain discovery allowed» مفعّل ضمن Login Behavior and Security
- المؤسسة الافتراضية — تستقبل كل المستخدمين الذين لا يطابقهم شيء
- نطاق موثَّق — يُوثَّق كل نطاق في Organization Domains الخاصة بالمؤسسة، عبر سجل DNS من نوع TXT أو تحدٍّ عبر HTTP؛ احتفظ بسجل DNS لأن ZITADEL تعيد التحقق دورياً
- سياسة الدخول في المؤسسة — تفعيل «External IDP allowed»، وللمؤسسة المرتبطة بالكامل بمزوّد خارجي تعطيل «Username Password allowed»
- مزوّد الهوية — مُعدّ ومرتبط بتلك المؤسسة؛ مع مزوّد واحد يكون التحويل تلقائياً، ومع عدة مزوّدين يختار المستخدم
- الدخول بالبريد الإلكتروني — يجب أن يصلح اسم الدخول المُدخَل ليكون بريداً إلكترونياً يطابق نطاقه النطاق الموثَّق
الحدود المعروفة: التذكرة رقم 10662 في zitadel/zitadel
في ZITADEL v4.1.2 المستضافة ذاتياً، لا يعمل اكتشاف النطاق في بعض عمليات النشر رغم وجود مؤسسات بنطاق موثَّق ومزوّد هوية مُعدّ. فُتحت التذكرة رقم 10662 («Domain Discovery doesn't work») في سبتمبر 2025 ولا تزال مفتوحة وقت كتابة هذه المقالة. يفصل الجدول بين ما يثبته الفريق أو الوثائق وما يبلّغ عنه المستخدمون.
التذكرة 10662: المؤكد والمبلَّغ عنه
مرّر الجدول أفقيًا
| البند | مؤكد (الفريق أو الوثائق) | مبلَّغ عنه من المستخدمين دون تأكيد |
|---|---|---|
| العَرَض | التذكرة مفتوحة وبأولوية متوسطة منذ أكتوبر 2026 وعليها الوسوم area/console وarea/loginV1 وng-v4-legacy | رسالة «User not found in the system» لعنوان بريد من النطاق الموثَّق، على v4.1.2، بالنتيجة نفسها على OKD وعلى Docker |
| الإصلاح المعلن | ذكر أحد المشرفين في أكتوبر 2025 أن طلب الدمج رقم 10729 يعالجها، ثم أُعيد فتح التذكرة | يستمر الخلل على v4.3.1، ثم على Login V1 في v4.5.0 وv4.6.3 وv4.7.0 وv4.11.0 |
| السبب | لا يوجد سبب مثبت علناً | لا توجد فرضية متحقَّق منها |
| النطاق | توجد تذاكر فرعية (حالتها في 16 يوليو 2026: واحدة منجزة واثنتان قيد العمل وواحدة لم تبدأ) مرتبطة بالعمل الأم رقم 12337 | أُعيد إنتاجه على Login V2 (البلاغ الأول) ثم على Login V1؛ وحالة عدة نطاقات في مؤسسة واحدة بلا جواب |
| لوحة التحكم | في 27 يوليو 2026 تذكر مساهمة أن لوحة التحكم (Console) ستُهمَل خلال 12 شهراً وأنه لا إصلاح ذا أولوية حتى ذلك الحين؛ وتبقى التذكرة مفتوحة | لا شيء يُذكر |
| حل بديل | لا يوثّق النقاش أي حل بديل | لم يثبت المشاركون أي حل |
عملياً: لا تبنِ بنية SSO مؤسسية على اكتشاف النطاق وحده ما دامت هذه التذكرة مفتوحة. وفّر مساراً ثانياً (رابط دخول لكل مزوّد، انظر أدناه) واختبر التوجيه مع مستخدم حقيقي قبل الإنتاج. في 27 أكتوبر 2026 طلب أحد أعضاء الفريق التحقق من حالة التذكرة: تابع التذكرة نفسها لا هذه المقالة لمعرفة مآلها.
استكشاف أخطاء الدخول عبر SSO والنطاق الموثَّق
التشخيص في 5 خطوات
افحص المثيل
في إعدادات المثيل، قسم Login Behavior and Security، تحقق من أن «Domain discovery allowed» مفعّل. بدونه لا يُرجَع إلى أي قاعدة مؤسسة.
افحص النطاق
في المؤسسة المعنية افتح Organization Domains: يجب أن تكون حالة النطاق موثَّقة. إذا فشل التوثيق فأعد سجل TXT أو تحدي HTTP المطلوب، ولا تحذف السجل بعد ذلك أبداً.
افحص سياسة الدخول
في المؤسسة نفسها يجب تفعيل «External IDP allowed» وأن يكون مزوّد الهوية نشطاً. إذا بقي «Username Password allowed» مفعّلاً فقد يصل المستخدم إلى إدخال كلمة المرور بدل التحويل، وهو عَرَض مذكور في التذكرة.
اختبر اسم الدخول
في نافذة خاصة أدخل عنواناً كاملاً يطابق نطاقه تماماً النطاق الموثَّق. خطأ في النطاق أو نطاق فرعي أو مستخدم موجود أصلاً في مؤسسة أخرى يغيّر النتيجة.
تجاوز الاكتشاف
إذا كان كل شيء مطابقاً وبقيت «User not found in the system»، فالأرجح أنك أمام حالة التذكرة رقم 10662. يحوّل النطاق
urn:zitadel:iam:org:idp:id:<idp_id>المستخدم مباشرة إلى مزوّد الهوية المختار: تصفه الوثائق لكنه لم يُختبر على هذا الخلل.
- «User not found in the system»: طبّق الخطوات الخمس أعلاه؛ فإن كانت مطابقة فهذا هو الخلل المذكور في التذكرة
- «Instance not found» (404): المضيف والمنفذ والبروتوكول المستلمة لا تطابق
ZITADEL_EXTERNALDOMAINوZITADEL_EXTERNALPORTوZITADEL_EXTERNALSECURE؛ تحقق من أن nginx يحافظ على ترويسة Host - لوحة تحكم بيضاء أو فشل استدعاءات API خلف وكيل أو CDN: تحقق من HTTP/2 من الطرف إلى الطرف
- رفض اسم المستخدم
admin: جرّب الصيغة admin@zitadel.<your-domain>المذكورة أعلاه - فشل توثيق النطاق: يشير الدليل الرسمي إلى إمكانية تعطيل تحدي ACME للتوثيق في الإعدادات الافتراضية، لكن لا تفعل ذلك إلا عن علم
التحديثات والأمان
- الإصدار الحالي — وقت الكتابة آخر إصدار مستقر منشور هو v4.20.0 الصادر في أكتوبر 2026؛ اقرأ ملاحظات الإصدار قبل كل ترقية
- النشرة GHSA-jh92-5mrj-p2w2 — استيلاء على الحساب عبر معرّفات جلسات قابلة للتخمين في Login V2 (خطورة عالية ولا معرّف CVE مذكور). تتأثر الإصدارات من 4.0.0 إلى 4.19.1 وأُصلحت في 4.19.2؛ ولا يتأثر النشر الذي يستخدم Login V1 فقط
- سر ملف تعريف الجلسة — يتطلب الإصلاح
ZITADEL_SESSION_COOKIE_SECRET(32 حرفاً على الأقل ومتطابقاً على كل النسخ)؛ ويجب على المستخدمين تسجيل الدخول من جديد بعد الترقية - الفرع 3.x — بلغ نهاية عمره في 31 أغسطس 2026 ولن يتلقى إصلاحاً: انتقل إلى إصدار 4.x حديث
قبل التحديث
انسخ احتياطياً القاعدة بالأمر pg_dump والمفتاح الرئيسي، ثم نفّذ docker compose pull يليه docker compose up -d من مجلد Compose. ولأن القالب يتبع الوسم stable، تحقق بعد ذلك من الإصدار العامل بالأمر docker compose images.
تثبيت ZITADEL عبر Marketplace ServOrbit
يمكنك تثبيت ZITADEL مباشرة من [Marketplace ServOrbit](/marketplace/security/zitadel): VPS مهيأ مسبقاً مع Docker Compose وnginx وHTTPS وأسرار مولَّدة تلقائياً. يُقدَّم القالب نقطة انطلاق، دون دعم لإعدادات الهوية لديك.
