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

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

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

يأتي Authentik في صورة 3 خدمات ضمن ملف Compose هذا: قاعدة بيانات PostgreSQL، وعملية server، وعملية worker. تشغّل حاوية الخادم أيضاً outpost المضمّن، وهو المكوّن الذي يجيب عن السؤال: «هل سجّل هذا الطلب الدخول؟» لكل تطبيق محمي. الإصدار 2026.5 هو الإصدار الحالي اعتباراً من يوليو 2026، ويطلب المشروع خادماً يحتوي على نواتي CPU على الأقل و2 GB من RAM. اعتبر ذلك الحد الأدنى. تحتفظ PostgreSQL والعامل بقدر من الذاكرة بعد أن يعمل الخادم لمدة يوم.

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

تحتاج إلى 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، وإبلاغ server عن worker. ويجب أن يبلّغ running عن running. يشغّل البدء الأول عمليات ترحيل قاعدة البيانات، لذلك انتظر دقيقة قبل أن تستجيب واجهة الويب.

كلتا القيمتين المُنشأتين مهمتان، لكن لأسباب مختلفة. PG_PASS هي كلمة مرور PostgreSQL، والحد الأقصى لطولها هو 99 حرفاً. توقّع AUTHENTIK_SECRET_KEY الجلسات والرموز، لذلك يؤدي تغييرها لاحقاً إلى تسجيل خروج جميع المستخدمين وإبطال كل رموز API التي أصدرتها. اضبط نمط صلاحيات .env على 600 واحتفظ بنسخة منها في مكان آمن، لأن قاعدة البيانات التي تُستعاد من دون مفتاحها السري المطابق هي قاعدة بيانات لا يستطيع أحد تسجيل الدخول إليها.

يقرأ ملف Compose القيمتين باستخدام صيغة ${PG_PASS:?database password 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 حسابًا للطوارئ، واحفظ كلمة مرور طويلة له في مكان غير متصل بالإنترنت. يؤدي العمل اليومي باستخدام حساب مضمّن مشترك إلى إتلاف سجل التدقيق، لأن كل حدث سيشير إلى 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 أن الحاوية ليست متصلة بشبكة proxy، ولذلك لا يستطيع Traefik توجيه الطلبات إلى حاوية لا يمكنه الوصول إليها.

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

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

لدى Authentik ثلاثة أوضاع لـ proxy provider، واختيار الوضع الخطأ قد يكلّفك ساعة. يعني وضع Proxy أن outpost نفسه يمرّر حركة الشبكة إلى التطبيق upstream. أما Forward auth (single application) فيعني أن reverse proxy الخاص بك يواصل تمرير حركة الشبكة، ولا يسأل Authentik إلا عمّا إذا كان الطلب قد سجّل الدخول. ويحمي Forward auth (domain level) كل تطبيق تحت نطاق رئيسي واحد باستخدام provider واحد، لكن ذلك يكون على حساب قواعد التفويض الخاصة بكل تطبيق. عند استخدام Traefik أمام Authentik، اختر 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-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)، فعليك تشغيل أداة مثل oauth2-proxy بجانبه. أما Authentik فيوفّر proxy provider مدمجاً لهذه المهمة، وهو متكامل معه مسبقاً. لذلك ينتهي الأمر بمعظم من يستضيفون خدماتهم بأنفسهم، مع مجموعة متنوعة من التطبيقات، إلى اختيار Authentik.

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

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

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

خزّن هذا التفريغ مع .env. لا يكفي التفريغ وحده، لأن المفتاح السري الذي يحمي بيانات الجلسات والرموز موجود في .env.

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

FAQ

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

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

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

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

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

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

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

الحد الأدنى الموثق هو 2 من أنوية CPU و2 GB من RAM اعتباراً من July 2026، ويشمل PostgreSQL والخادم وworker معاً. في خادم بذاكرة 2 GB، تكون عملية worker أول عملية ينهيها kernel عند الضغط على الذاكرة. يتمثل العَرَض في توقف المهام الخلفية والبريد الإلكتروني الصادر، مع استمرار صفحة تسجيل الدخول في العمل. امنحه 4 GB إذا كان الخادم نفسه يشغّل أيضاً التطبيقات التي تحميها.