إعداد Authentik لتسجيل دخول واحد عبر Docker

تسجيل دخول واحد لكل تطبيق تستضيفه

Authentik هو خادم SSO (تسجيل دخول موحد) ذاتي الاستضافة: يسجّل المستخدمون دخولهم مرة واحدة، ويقبل كل تطبيق خلفه هذه الجلسة بدلاً من طلب كلمة مرور خاصة به. يتكون التثبيت من ملف Docker Compose رسمي وسرّين يتم إنشاؤهما. الجزء الذي يتطلب تفكيراً حقيقياً يأتي لاحقاً: توجيه Reverse Proxy إليه، ووضع تطبيق موجود خلف مصادقة أمامية (forward auth).

يصدر Authentik كخدمة من ثلاث خدمات في ملف Compose هذا: قاعدة بيانات PostgreSQL، وعملية server، وعملية worker. تشغّل حاوية الخادم أيضاً الـoutpost المضمن، وهو المكون الذي يجيب على سؤال "هل هذا الطلب مسجّل دخوله؟" لكل تطبيق محمي. الإصدار 2026.8.5 هو الإصدار الحالي اعتباراً من 25 أكتوبر 2026. تم نشره في 21 أكتوبر 2026 كأحدث تصحيح لسلسلة 2026.8، التي بدأت بالإصدار 2026.8.0 في 18 أغسطس، وهو يحل محل 2026.8.4 الصادر في 14 أكتوبر كـ tag للصورة الافتراضية في ملف Compose الرسمي. يطلب المشروع مضيفاً بذاكرة وصول عشوائي (RAM) لا تقل عن 2 جيجابايت ومعالج بـ 2 نواة. اعتبر هذا الحد الأدنى. تستهلك PostgreSQL والعامل (worker) الذاكرة بمجرد عمل الخادم ليوم واحد.

ما تحتاج إليه قبل البدء

تحتاج إلى Docker Engine مع إضافة Compose v2، ويمكنك التأكد من ذلك باستخدام docker compose version. إذا طبع الأمر رسالة خطأ بدلاً من رقم الإصدار، فثبّت الإضافة قبل المتابعة؛ تتناول تشغيل التطبيقات باستخدام Docker Compose على VPS الأساسيات. تحتاج أيضاً إلى سجل DNS من النوع A يشير إلى الخادم، وهو auth.example.com في الأمثلة أدناه، لأن Authentik ينشئ عناوين إعادة التوجيه اعتماداً على اسم المضيف الذي استخدمه المتصفح.

شغّل الحزمة باستخدام مستخدم عادي ينتمي إلى مجموعة docker بدلاً من root. تعادل العضوية في هذه المجموعة صلاحيات root على المضيف، لذلك امنحها لحساب نشر واحد فقط ولا تمنحها لأي شخص آخر، وفقاً لمبدأ حسابات المستخدمين ذات أقل الصلاحيات على VPS.

التثبيت باستخدام ملف Compose الرسمي

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

يجب أن يسرد docker compose ps ثلاث حاويات، جميعها تعمل، مع إبلاغ postgresql عن healthy بمجرد اجتياز الفحص. التشغيل الأول ينفذ عمليات ترحيل قاعدة البيانات، لذا امنحه دقيقة قبل أن يستجيب واجهة الويب.

كلا القيمتين المولدتين مهمتان، لأسباب مختلفة. PG_PASS هي كلمة مرور PostgreSQL. تنص وثائق تثبيت Authentik على أن كلمات المرور التي تتجاوز 99 حرفاً غير مدعومة، لذا اجعل أي كلمة مرور تختارها بنفسك أقل من ذلك؛ القيمة الموّلدة أقصر بكثير. AUTHENTIK_SECRET_KEY هو المفتاح الذي يستخدمه Authentik لتوقيع ملفات تعريف الارتباط (cookies)، وتنص وثائق إعداده على أن تغييره يبطل الجلسات النشطة، لذا فإن أي مفتاح جديد لاحقاً سيقوم بتسجيل خروج كل مستخدم مسجّل دخوله. احتفظ بـ .env بنمط 600 واحتفظ بنسخة في مكان آمن مع نسخك الاحتياطية، حتى تتم عملية الاستعادة بنفس المفتاح الذي كان يعمل به.

يحدد ملف Compose كلتا القيمتين كقيمتين مطلوبتين باستخدام صيغة ${VAR:?message}: ${PG_PASS:?database password required} في خدمة PostgreSQL و${AUTHENTIK_SECRET_KEY:?secret key required} في الخادم والعامل. هذا يعني أن Compose يرفض البدء عند فقدان الملف. تشغيل docker compose up -d من الدليل الخطأ يطبع سطراً مثل required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required ويتوقف. تلك الرسالة هي مشكلة مسار، وليست مشكلة إعداد.

قيم البيئة المهمة

يوضع كل ما تبقى في ملف .env نفسه. يربط Authentik الشرطة السفلية المزدوجة بمفتاح إعدادات متداخل، لذلك يضبط AUTHENTIK_EMAIL__HOST القيمة email.host. أما الشرطة السفلية المفردة فلا تربط بالمفتاح المتداخل، وهذا هو السبب الأكثر شيوعاً لظهور إعداد ما كأنه لا يفعل شيئاً.

• يضبط AUTHENTIK_BOOTSTRAP_PASSWORD كلمة مرور مستخدم akadmin المضمّن عند التشغيل الأول، لذلك لن تكتبها أبداً في نموذج ويب عام. ويضبط AUTHENTIK_BOOTSTRAP_EMAIL وAUTHENTIK_BOOTSTRAP_TOKEN عنوان ذلك المستخدم ورمز API بالطريقة نفسها.
• ينقل COMPOSE_PORT_HTTP وCOMPOSE_PORT_HTTPS المنافذ المنشورة بعيداً عن القيم الافتراضية 9000 و9443.
• يضبط AUTHENTIK_EMAIL__HOST وAUTHENTIK_EMAIL__PORT وAUTHENTIK_EMAIL__USERNAME وAUTHENTIK_EMAIL__PASSWORD وAUTHENTIK_EMAIL__USE_TLS وAUTHENTIK_EMAIL__FROM البريد الصادر. من دون هذه القيم، يحاول Authentik استخدام localhost على المنفذ 25، لذلك تنتهي رسائل إعادة تعيين كلمة المرور بخطأ اتصال في سجل العامل.
• يفعّل AUTHENTIK_LOG_LEVEL=debug مستوى التفاصيل الذي تحتاج إليه أثناء تعطل تدفق تسجيل الدخول. أعده إلى info بعد ذلك.
• تكون قيمة AUTHENTIK_ERROR_REPORTING__ENABLED هي false افتراضياً. اضبطها على true فقط إذا كنت موافقاً على إرسال تقارير الأعطال إلى الجهة المطوِّرة.

هذه أسرار محفوظة في ملف نصي عادي، لذلك تعامل مع الدليل كما تتعامل مع أي مخزن آخر لبيانات الاعتماد. ويكون مدير كلمات مرور مثل مثيل Vaultwarden مستضاف ذاتياً مكاناً أفضل لحفظ نسخة الاسترداد من ملاحظة على حاسوبك المحمول.

تسجيل الدخول الأول وحساب المسؤول

افتح http://SERVER_IP:9000 في متصفح. يعرض Authentik تدفق الإعداد الأولي ويطلب منك تعيين كلمة مرور لمستخدم akadmin الافتراضي. إذا كنت قد قمت بالفعل بتعيين AUTHENTIK_BOOTSTRAP_PASSWORD، فقد تمت هذه الخطوة وتنتقل مباشرة إلى صفحة تسجيل الدخول.

أنشئ مستخدم مسؤول عادي لنفسك ضمن Directory ثم Users، وأضفه إلى مجموعة authentik Admins، وسجّل الدخول بهذا الحساب. اترك akadmin كحساب طوارئ (break-glass) بكلمة مرور طويلة مخزنة دون اتصال. إذا أدى تدفق أو مرحلة معطلة إلى قفل حسابك، فإن docker compose run --rm server create_recovery_key 10 akadmin، عند تشغيله من /opt/authentik، يطبع رابطاً يسجّل دخولك بصفتك akadmin مباشرة. أي شخص يحمل هذا الرابط لديه نفس الوصول، لذا تعامل معه مثل كلمة المرور. العمل اليومي تحت حساب مدمج مشترك يدمر سجل التدقيق، لأن كل حدث يقول akadmin ولا شيء يحدد من هو الفاعل. هذه الحجة تنطبق أيضاً على ما بعد Authentik: شيء مثل أداة OneCLI ذاتية الاستضافة تمنح كل شخص عميلاً خاصاً به لا يترك أثراً قابلاً للقراءة إلا إذا كانت الهوية التي تصل إليه تنتمي إلى إنسان واحد بدلاً من تسجيل دخول يشاركه الفريق بأكمله.

ضع Authentik خلف الـReverse Proxy

يعمل نشر المنفذ 9000 على الإنترنت، لكنك تريد TLS (أمان طبقة النقل) واسم مضيف فعلياً. إذا كنت تشغّل الإعداد الوارد في Traefik كـReverse Proxy لعدة تطبيقات Compose، فأضف Authentik إلى شبكة proxy الخارجية نفسها باستخدام ملف override. أنشئ docker-compose.override.yml بجوار compose.yml:

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

طبّق الملف باستخدام docker compose up -d. يدمج Compose ملف override تلقائياً، لذلك تحتفظ خدمة server بكل ما ورد في الملف الرسمي، وتكتسب labels أيضاً. تحقّق باستخدام curl -I https://auth.example.com/if/user/؛ ويُفترض أن يعرض HTTP/2 200. تعني رسالة 404 page not found من Traefik أنه لم يطابق أي router الطلب. تحقّق من وصول labels إلى الحاوية، ومن أن قاعدة Host() تطابق اسم المضيف تماماً، ومن وصول الطلب إلى نقطة الدخول HTTPS التي يستمع عليها الـrouter.

بعد عمل اسم المضيف، اربط المنافذ المنشورة بـ127.0.0.1 في ملف override، بحيث يصبح المرور عبر الـproxy هو الطريقة الوحيدة للوصول.

حماية تطبيق واحد باستخدام forward auth

يوفّر Proxy Provider في Authentik ثلاثة أوضاع، واختيار الوضع الخاطئ قد يكلّفك ساعة من العمل. يعني Proxy أن outpost نفسه يمرّر حركة الشبكة إلى التطبيق upstream. ويعني Forward auth (single application) أن reverse proxy الخاص بك يمرّر حركة الشبكة، ولا يستعلم من Authentik إلا عمّا إذا كان الطلب قد سجّل الدخول. أما Forward auth (domain level) فيحمي كل تطبيق ضمن نطاق أب واحد باستخدام provider واحد، لكن على حساب قواعد التفويض الخاصة بكل تطبيق. عند استخدام Traefik أمام التطبيقات، اختر forward auth (single application). وإذا أردت تطبيقاً عملياً للتجربة، فإن مساحة عمل AFFiNE مستضافة ذاتياً مرشح جيد للبدء، لأنها من نوع الأدوات الداخلية التي تريد الوصول إليها من أجهزتك فقط ومنع الوصول إليها من أي مكان آخر. ويصبح هذا الخيار أكثر فائدة لأدوات الفريق: ضع مكتب دعم Chatwoot مستضافاً ذاتياً خلف provider نفسه، حتى يسجّل كل من يجيب عن صندوق الوارد الدخول مرة واحدة خلال اليوم بدلاً من مشاركة كلمة مرور إضافية.

في واجهة الويب، افتح Applications ثم Providers، وأنشئ Proxy Provider، واختر وضع forward auth single application، واضبط المضيف الخارجي على https://app.example.com. أنشئ Application يشير إلى ذلك provider. ثم افتح Outposts، وعدّل authentik Embedded Outpost، وانقل التطبيق الجديد إلى قائمة التطبيقات المحددة. لا يستجيب outpost إلا للتطبيقات التي أُضيفت إليه، لذلك فإن تخطي هذه الخطوة الأخيرة هو سبب عدم إرجاع provider مُعدّ إعداداً صحيحاً لأي نتيجة.

عرّف middleware مرة واحدة على حاوية Authentik، ثم أشِر إليه من كل تطبيق محمي:

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders هي قائمة الرؤوس التي ينسخها Traefik من استجابة Authentik إلى الطلب الذي يرسله إلى upstream. إذا حذفتها، فسيظل التطبيق محمياً، لكنه لن يعرف هوية المستخدم. لذلك سيبقى أي مكوّن يقرأ X-authentik-username لتسجيل الدخول التلقائي في حالة عدم تسجيل الدخول. يظهر هذا النقص بوضوح أمام تطبيق يحتفظ بتسجيل دخول خاص به، مثل متتبع تمارين openGym مستضاف ذاتياً مع تسجيل الدخول باستخدام passkey، إذ تحدد هذه الرؤوس ما إذا كانت الصفحة تحتاج إلى مطالبة واحدة أو مطالبتين.

يحتاج التطبيق المحمي نفسه إلى routerين، وليس router واحداً:

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

الـrouter الثاني هو الجزء الذي يغفل عنه الجميع. بعد تسجيل الدخول، يعيد Authentik المتصفح إلى مسار ضمن /outpost.goauthentik.io/ على اسم مضيف التطبيق، وليس على auth.example.com. من دون router يرسل بادئة هذا المسار إلى خدمة Authentik، يصل الطلب إلى تطبيقك، الذي يعيد 404، ولا تكتمل عملية تسجيل الدخول. وتضمن القيمة الأعلى في priority فوز قاعدة المسار المحددة على قاعدة Host() العامة في النطاق نفسه.

اختبر الإعداد في نافذة متصفح خاصة. يجب أن تُنقل إلى auth.example.com، ثم تسجّل الدخول وتعود إلى التطبيق. يعرض docker compose logs -f server على جانب Authentik حدث تفويض لكل محاولة، وهذا يوضح لك ما إذا كان الطلب قد وصل إلى Authentik أصلاً.

الأعطال التي ستواجهها فعلياً

حلقة إعادة توجيه لا تنتهي بين التطبيق وصفحة تسجيل الدخول. لا يطابق المضيف الخارجي لدى موفّر الخدمة ما يستخدمه المتصفح، وعادةً يكون ذلك http:// لدى الموفّر مقابل https:// في شريط العنوان. تُضبط Cookie الجلسة عندها لأصل مختلف، ولذلك تبدو كل عودة كأنها طلب مجهول جديد. أصلح المضيف الخارجي، وامسح ملفات تعريف الارتباط للنطاقين قبل إعادة الاختبار.

ظهور 404 عند /outpost.goauthentik.io/start. موجّه outpost مفقود، أو أن أولويته أقل من أولوية الموجّه الشامل لهذا المضيف.

يُحمّل التطبيق من دون أن يطلب تسجيل الدخول. تسمّي التسمية middlewares وسيطاً برمجياً غير موجود. لا يصدر Traefik تحذيراً بشأن ذلك، ولذلك يعني الخطأ الإملائي في authentik@docker ببساطة عدم تشغيل أي وسيط برمجي. افتح لوحة معلومات Traefik وتأكد من أن الموجّه يسرد الوسيط البرمجي.

ظهور 403 من Authentik بعد نجاح تسجيل الدخول. تمّت مصادقة المستخدم، لكنه غير مخوّل: يحتوي التطبيق على ربط بسياسة، أو على متطلب مجموعة، لا يستوفيه هذا المستخدم. يحدّد سجل Events في واجهة الإدارة السياسة التي رفضت الطلب.

متى يكون Keycloak الخيار الأنسب

يُعد Keycloak المشروع الأقدم، ويحظى بدعم Red Hat، وهو الخيار الأقوى لأعمال الهوية المؤسسية التقليدية: اتحاد SAML واسع النطاق، وتمرير تسجيلات الدخول من عدة موفّري هوية خارجيين في الوقت نفسه، وتصدير realm واستيراده باعتبارهما مساراً موثقاً لترحيل البيانات. كما أن توفر الدعم التجاري له مهم لبعض المؤسسات من الناحية الرسمية. لكن المقابل هو أن Keycloak لا يتضمن proxy خاصاً به. لذلك، إذا كان التطبيق لا يدعم OIDC (OpenID Connect) ولا SAML، فستحتاج إلى تشغيل أداة مثل oauth2-proxy بجانبه. أما موفّر proxy المدمج في Authentik فيوفّر هذه الوظيفة ومتكامل معها مسبقاً، ولذلك يختاره معظم مشغّلي الخدمات ذاتية الاستضافة الذين يديرون مجموعة متنوعة من التطبيقات.

النسخ الاحتياطي والترقيات

ثلاثة أشياء تجعل الاستعادة ممكنة: قاعدة بيانات PostgreSQL، ودليل ./data، و.env.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

خزّن ذلك الملف (dump) و.env معاً. لا يحتوي الملف على نسخة من AUTHENTIK_SECRET_KEY، والاستعادة بمفتاح مختلف تبطل كل جلسة نشطة، لذا فإن الاحتفاظ بالمفتاح الأصلي يعني أن الخادم المستعاد يستمر كما كان.

الترقيات هي تغيير في الـtag. اضبط AUTHENTIK_TAG في .env على الإصدار الذي تريده، ثم شغّل docker compose pull متبوعاً بـ docker compose up -d. إذا لم تقم أبداً بتعيين AUTHENTIK_TAG، فإن الإصدار يأتي من القيمة الافتراضية المكتوبة في compose.yml نفسه، لذا فإن تنزيل نسخة أحدث من ذلك الملف هو الترقية، وهذا هو المسار الذي تصفه وثائق الترقية الرسمية. اقرأ ملاحظات الإصدار أولاً. يستخدم Authentik إصدارات تعتمد على التاريخ، واعتباراً من أكتوبر 2026 تنص وثائقه على أن الترقيات يجب أن تتبع تسلسل الإصدارات الرئيسية: انتقل إلى أحدث تصحيح للسلسلة التي تشغلها، ثم انتقل عبر كل سلسلة لاحقة بالترتيب دون تخطي أي منها. لا يدعم Authentik الرجوع إلى إصدار أقدم، لذا خذ نسخة احتياطية من قاعدة البيانات قبل عملية الـpull، وليس بعدها.

FAQ

هل Authentik مجاني للاستضافة الذاتية؟

إصدار المصدر المفتوح مجاني، ويشمل كل ما سبق: موفّر proxy، وforward auth، وOIDC (OpenID Connect)، وSAML، ومحرّك التدفقات. تضيف طبقة المؤسسات المدفوعة الدعم وبعض الميزات المؤسسية، لكن لا يتطلب أي مما ورد هنا ترخيصاً.

هل أحتاج إلى Traefik لاستخدام Authentik؟

لا. يعمل forward auth مع nginx عبر auth_request، ومع Caddy عبر forward_auth. النمط واحد في جميع الحالات: يطلب الـreverse proxy من Authentik التحقق من كل طلب، ويجب توجيه بادئة المسار /outpost.goauthentik.io/ على اسم المضيف المحمي إلى Authentik بدلاً من التطبيق.

لماذا ينتقل تطبيقي المحمي باستمرار بين تسجيل الدخول ورسالة الخطأ؟

لا يطابق المضيف الخارجي المُعدّ في proxy provider عنوان URL الذي يستخدمه المتصفح، وغالباً ما يكون السبب http مقابل https. تُصدر session cookie لنطاق أصل واحد، ثم تُقرأ من نطاق أصل آخر، لذلك يتعامل Authentik مع كل طلب باعتباره مجهولاً. صحّح المضيف الخارجي، ثم امسح ملفات تعريف الارتباط الخاصة باسمَي المضيف قبل الاختبار مجدداً.

ما مقدار RAM الذي يحتاج إليه Authentik؟

الحد الأدنى الموثّق هو نواتان من CPU و2 GB من RAM اعتباراً من October 2026، ويشمل ذلك PostgreSQL والخادم والعامل معاً. في خادم بسعة 2 GB، قد يؤدي ضغط الذاكرة إلى تشغيل OOM killer في النواة، الذي ينهي العملية الحاصلة على أعلى badness score: أي نسبة الذاكرة المسموح بها التي تستخدمها تقريباً، إضافة إلى oom_score_adj الخاص بها. إذا تبيّن أن العملية هي العامل، فستتوقف المهام الخلفية والبريد الصادر، بينما تستمر صفحة تسجيل الدخول في العمل. خصص 4 GB إذا كان الخادم نفسه يشغّل التطبيقات التي تحميها.