تثبيت Authentik كـ SSO ذاتي الاستضافة عبر Docker

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

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

يأتي Authentik في صورة ثلاث خدمات ضمن ملف Compose هذا: قاعدة بيانات PostgreSQL، وعملية server، وعملية worker. كما تشغّل حاوية الخادم الـ outpost المضمّن، وهو المكوّن الذي يجيب عن السؤال «هل تم تسجيل الدخول إلى هذا الطلب؟» لكل تطبيق محمي. الإصدار 2026.5 هو الإصدار الحالي اعتبارًا من July 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. يشغّل البدء الأول عمليات ترحيل قاعدة البيانات، لذا انتظر دقيقة قبل أن تستجيب واجهة الويب.

كلتا القيمتين المُنشأتين مهمتان، لكن لأسباب مختلفة. 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 خلف الوكيل العكسي

يعمل نشر المنفذ 9000 على الإنترنت، لكنك تريد استخدام TLS (أمان طبقة النقل) واسم مضيف فعلي. إذا كنت تستخدم الإعداد الوارد في Traefik كوكيل عكسي لتطبيقات Compose متعددة، فأضف Authentik إلى شبكة proxy الخارجية نفسها باستخدام ملف تجاوز. أنشئ 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 ملف التجاوز تلقائيًا، لذلك تحتفظ خدمة server بكل ما هو موجود في الملف الرسمي، وتكتسب التسميات أيضًا. تحقّق باستخدام curl -I https://auth.example.com/if/user/، الذي يجب أن يستجيب بـ HTTP/2 200. تعني 404 page not found من Traefik أن الحاوية ليست متصلة بشبكة proxy، ولا يستطيع Traefik توجيه الطلبات إلى حاوية لا يمكنه الوصول إليها.

بعد أن يعمل اسم المضيف، اربط المنافذ المنشورة بـ 127.0.0.1 في ملف التجاوز، بحيث يكون الدخول ممكنًا فقط عبر الوكيل.

حماية تطبيق واحد باستخدام المصادقة الأمامية

يحتوي موفّر الوكيل في Authentik على ثلاثة أوضاع، واختيار الوضع الخطأ قد يكلّفك ساعة من العمل. يعني Proxy أن الـ outpost نفسه يمرّر حركة الشبكة إلى التطبيق upstream. ويعني Forward auth (single application) أن الوكيل العكسي لديك يمرّر حركة الشبكة، ولا يستعلم من Authentik إلا عمّا إذا كان الطلب قد سجّل الدخول. أما Forward auth (domain level) فيحمي كل تطبيق ضمن نطاق أصل واحد باستخدام موفّر واحد، لكن ذلك يكون على حساب قواعد التفويض الخاصة بكل تطبيق. عند استخدام Traefik أماميًا، استخدم forward auth (single application).

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

عرّف الـ 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 لتسجيل الدخول التلقائي في حالة تسجيل خروج.

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

    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

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

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

حالات الفشل التي ستواجهها فعليًا

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

ظهور 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 بجانبه. أما موفر proxy المدمج في Authentik فيوفر هذه الوظيفة ومتكامل معها مسبقًا. ولهذا يختاره معظم من يديرون خوادمهم بأنفسهم عندما تكون لديهم مجموعة متنوعة من التطبيقات.

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

تجعل 3 أشياء الاستعادة ممكنة: قاعدة بيانات 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 مجاني للاستضافة الذاتية؟

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

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

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

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

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

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

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