دخول موحد لجميع تطبيقاتك: تثبيت authentik باستخدام Docker Compose

لنفرض أن فريقك يستخدم ثلاث خدمات على نفس السيرفر: Gitea للكود، وMattermost للمحادثات، وOutline للتوثيق، فسوف تجد أن كل خدمة منها تأتي بقاعدة مستخدمين User Database خاصة بها، وبالتالي فلكل موظف حساب في كل خدمة وكلمة مرور مختلفة في كل منها. والحل الأول الذي يخطر على البال هو أن تنشئ الحسابات يدوياً في كل خدمة وتنتهي المشكلة، ولكن هذا الحل يفشل في أول يوم يغادر فيه موظف الشركة، حيث يجب عليك أن تتذكر كل الأماكن التي له فيها حساب وتغلقها واحداً واحداً، وإذا نسيت مكاناً واحداً فسوف يبقى له باب مفتوح إلى بيانات الشركة دون أن تنتبه، وكلما زادت الخدمات زاد احتمال النسيان.

لذلك فالحل الأنسب هو مزود الهوية Identity Provider، وهو نظام واحد يحمل حساب كل شخص ويطبق سياسة واحدة لكلمات المرور ويفرض المصادقة الثنائية 2FA من مكان واحد، ثم يدخل منه الموظف إلى كل التطبيقات بالدخول الموحد Single Sign-On واختصاراً SSO عبر OIDC أو SAML أو LDAP، وأما التطبيقات التي ليس فيها نظام دخول أصلاً فيحميها عبر الـ Reverse Proxy، وبالتالي عندما يغادر الموظف فأنت تعطل حساباً واحداً فقط فيغلق عليه كل الأبواب مرة واحدة.

وauthentik هو مزود هوية مفتوح المصدر Open Source، تثبته باثنين من الـ Containers وقاعدة بيانات Database من نوع PostgreSQL، وفي واجهته الإدارية Admin Interface كل ما يحتاجه فريق صغير أو مؤسسة متوسطة: المستخدمون والمجموعات Groups، والتطبيقات والمزودون Providers من نوع OAuth2/OIDC وSAML وLDAP وProxy، والتدفقات Flows التي تحدد كل خطوة في تسجيل الدخول والتسجيل واستعادة كلمة المرور.

ويناسبك authentik إذا كانت لديك ثلاث خدمات أو أكثر تحتاج إلى دخول موحد، أو أدوات داخلية بلا نظام دخول وتريد حمايتها. وقد يتساءل البعض: لماذا لا أكتفي بـ Basic Auth في الـ Reverse Proxy؟ والإجابة أن Basic Auth يصلح لحماية لوحة واحدة بكلمة مرور واحدة، ولكنه لا يعرف من هو المستخدم ولا يفرض عليه مصادقة ثنائية ولا يسجل من دخل ومتى، فإذا كانت هذه حاجتك فعلاً فقد يكفيك، وإذا كانت مؤسستك تعمل أصلاً على Keycloak أو Active Directory فلا حاجة إلى طبقة جديدة.

وسوف نناقش في هذا المقال ما يلي:

• ما الذي تغير في الإصدارات الحديثة من authentik ويجعل كثيراً من الأدلة القديمة غير دقيقة.
• تثبيت authentik باستخدام Docker Compose وPostgreSQL، مع ملف Compose مبني على الملف الرسمي وأكثر أماناً منه.
• الإعداد الأولي وحساب المدير، ثم إنشاء المستخدمين والمجموعات وإعداد البريد الصادر.
• فرض المصادقة الثنائية TOTP على الجميع دون أن تغلق الباب على نفسك.
• ربط النطاق مع TLS، والنسخ الاحتياطي والاستعادة، والتحديث، وأشهر المشكلات وحلولها.

وهذا الدليل هو أول سلسلة، حيث نستخدم authentik بعده في حماية أي تطبيق عبر Forward Auth، وتسجيل الدخول بحساب Google، وربط Gitea وOutline عبر OIDC.

ما الذي تغير في الإصدارات الحديثة؟

إذا كنت قد ثبت authentik قبل سنة أو أكثر، أو تتبع دليلاً قديماً من الإنترنت، فهناك ثلاثة تغييرات سوف تجعل بعض خطواته غير صحيحة:

• لم يعد يحتاج إلى Redis: نقل authentik المهام الخلفية Tasks إلى PostgreSQL في الإصدار 2025.8، ثم نقل في الإصدار 2025.10 التخزين المؤقت Cache وجلسات Sessions الـ outpost المدمج واتصالات WebSocket، وبالتالي لم يعد يستخدم Redis إطلاقاً، لذلك صار ملف Compose الرسمي يضم ثلاث خدمات فقط هي postgresql وserver وworker، ولاحظ أن عدد اتصالات Connections قاعدة البيانات زاد بنحو 50٪ نتيجة لذلك.
• صار مجلد البيانات /data بدل المجلد القديم /media منذ الإصدار 2025.12، وفيه تحفظ الملفات المرفوعة Uploads مثل الشعارات والأيقونات، فإذا كنت تحدث تثبيتاً قديماً فعليك نقل محتوى المجلد القديم إلى ./data/media قبل التشغيل بالملف الجديد.
• يبدأ الإعداد الأولي Initial Setup من العنوان الرئيسي للموقع Root URL ويطلب عنوان «Base URL» للنسخة، ولم يعد فتح /if/flow/initial-setup/ مباشرة يكفي (انظر قسم المشكلات الشائعة). وفي الإصدار 2026.8 صار authentik لا يثق بالـ Headers من نوع X-Forwarded-* إلا إذا جاءت من شبكة موثوقة Trusted Network يحددها المتغير AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS.

المتطلبات

• سيرفر Linux بمعالجين 2 vCPU وذاكرة RAM بحجم 2 GB على الأقل، و4 GB أفضل إذا كانت على السيرفر تطبيقات أخرى، وتكفي 5 GB من المساحة للبداية لأن الـ Image وحدها نحو 1 GB.
• Docker Engine مع إضافة Plugin Compose v2، وإذا لم يكن مثبتاً فاتبع دليل تثبيت Docker أولاً.
• نطاق فرعي Subdomain يشير إلى السيرفر، وهو في هذا الدليل auth.example.com، وReverse Proxy يصدر شهادة Certificate من نوع TLS مثل Nginx Proxy Manager.
• المنفذان Ports رقم 80 و443 مفتوحان للـ Reverse Proxy فقط، ولا حاجة إلى كشف منافذ authentik الداخلية 9000 و9443 للإنترنت.
• حساب SMTP لإرسال البريد مثل رسائل استعادة كلمة المرور والدعوات، وتستطيع تأجيله أثناء التجربة، ولكن لا تنتقل إلى بيئة الإنتاج Production بدونه، والسبب أن المستخدم الذي ينسى كلمة مروره لن يستطيع استعادتها بنفسه.

التثبيت

هيكل المجلد

سوف نضع كل ما يخص authentik في مجلد واحد، فيسهل نسخه احتياطياً ونقله إلى سيرفر آخر:

sudo mkdir -p /opt/authentik/{data,certs,custom-templates}
cd /opt/authentik

وسيضم المجلد في النهاية الملفات docker-compose.yml و.env، والمجلد data/ للملفات المرفوعة، وcerts/ للشهادات التي تريد استيرادها، وcustom-templates/ لقوالب Templates البريد أو الصفحات المخصصة، أما قاعدة البيانات نفسها فتحفظ في Docker volume اسمه database.

ملف .env والأسرار Secrets

يحتاج authentik إلى سرين: كلمة مرور PostgreSQL، والمفتاح AUTHENTIK_SECRET_KEY الذي يوقع به الكوكيز Cookies والجلسات والتوكنات Tokens. ولا تقم بتغيير هذا المفتاح بعد التشغيل، والسبب أن تغييره يبطل كل الجلسات النشطة وبعض البيانات الموقعة، لذلك احفظه مع نسختك الاحتياطية Backup. والتوثيق الرسمي يولد السرين بصيغة base64، ونحن نستخدم hex لأن ناتجه حروف وأرقام فقط فلا يسبب مشكلة في ملف .env:

echo "PG_PASS=$(openssl rand -hex 32)" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -hex 50)" >> .env
chmod 600 .env

ثم أكمل الملف ببقية الإعدادات، وإعدادات البريد هنا عامة تصلح لأي مزود SMTP، وسوف نعود إليها في قسم البريد:

# نسخة authentik المثبتة (لا تستخدم latest)
AUTHENTIK_TAG=2026.8.3

# المنافذ على الخادم (مربوطة بـ 127.0.0.1 في ملف compose)
COMPOSE_PORT_HTTP=9000
COMPOSE_PORT_HTTPS=9443

# إرسال تقارير الأخطاء إلى مطوري authentik (اختياري)
AUTHENTIK_ERROR_REPORTING__ENABLED=false

# البريد الصادر (SMTP)
AUTHENTIK_EMAIL__HOST=smtp.example.com
AUTHENTIK_EMAIL__PORT=587
[email protected]
AUTHENTIK_EMAIL__PASSWORD=change-me
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__USE_SSL=false
AUTHENTIK_EMAIL__TIMEOUT=10
[email protected]

ملف docker-compose.yml

هذا الملف مبني على الملف الرسمي للإصدار 2026.8 مع ثلاثة تعديلات، وهو كما يلي:

services:
  postgresql:
    image: docker.io/library/postgres:16-alpine
    restart: unless-stopped
    env_file: .env
    environment:
      POSTGRES_DB: authentik
      POSTGRES_USER: authentik
      POSTGRES_PASSWORD: ${PG_PASS:?database password required}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 20s
    volumes:
      - database:/var/lib/postgresql/data

  server:
    image: ghcr.io/goauthentik/server:${AUTHENTIK_TAG:-2026.8.3}
    restart: unless-stopped
    command: server
    env_file: .env
    environment:
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
    shm_size: 512mb
    ports:
      - "127.0.0.1:${COMPOSE_PORT_HTTP:-9000}:9000"
      - "127.0.0.1:${COMPOSE_PORT_HTTPS:-9443}:9443"
    volumes:
      - ./data:/data
      - ./custom-templates:/templates
    depends_on:
      postgresql:
        condition: service_healthy
    networks:
      - default
      - proxy

  worker:
    image: ghcr.io/goauthentik/server:${AUTHENTIK_TAG:-2026.8.3}
    restart: unless-stopped
    command: worker
    env_file: .env
    environment:
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY:?secret key required}
    shm_size: 512mb
    # root يسمح للـ worker بتصحيح صلاحيات المجلدات المربوطة
    user: root
    volumes:
      - ./data:/data
      - ./certs:/certs
      - ./custom-templates:/templates
    depends_on:
      postgresql:
        condition: service_healthy

volumes:
  database:

networks:
  proxy:
    external: true

في الإعداد أعلاه لاحظ التالي:

• ربطنا المنافذ بالعنوان 127.0.0.1 بدل نشرها على كل العناوين كما في الملف الرسمي، والسبب أن Docker يتجاوز جدار الحماية Firewall عند نشر المنافذ، فلا يصل إلى authentik من الخارج إلا الـ Reverse Proxy.
• ضممنا خدمة server إلى شبكة proxy المشتركة مع الـ Reverse Proxy، حتى يصل إليها باسم الـ Container دون منفذ منشور.
• حذفنا تمرير docker.sock إلى الـ worker، والتفصيل في الملاحظة التالية.

التشغيل ومتابعة السجلات Logs

الآن سوف نقوم بإنشاء شبكة proxy مرة واحدة إن لم تكن موجودة من تثبيت الـ Reverse Proxy، ثم نشغل الخدمات ونتابع سجلاتها:

docker network create proxy

docker compose pull
docker compose up -d

docker compose logs -f server worker

وفي التشغيل الأول ينفذ authentik مئات الترحيلات Migrations على قاعدة البيانات، وهذا يستغرق من دقيقتين إلى ربع ساعة بحسب سرعة القرص والمعالج، ويرد السيرفر خلالها بالرمز Status Code رقم 503، ثم يحتاج الـ worker إلى بضع دقائق بعدها حتى يجهز التدفقات الافتراضية، لذلك لا تستعجل وانتظر حتى يظهر كل Container في حالة healthy:

docker compose ps

الإعداد الأولي وحساب المدير Admin Account

ينشئ authentik حساباً إدارياً اسمه akadmin بلا كلمة مرور، وأول من يفتح صفحة الإعداد هو من يحدد كلمة مروره، لذلك نفذ هذه الخطوة فور التشغيل ولا تترك النسخة متاحة على الإنترنت قبلها.

افتح العنوان الرئيسي للموقع، وهو https://auth.example.com/ بعد إعداد الـ Reverse Proxy أو http://127.0.0.1:9000/ عبر نفق SSH Tunnel، وسوف يحولك authentik إلى /if/flow/initial-setup/. أدخل بريد المدير وكلمة مرور قوية، وتأكد أن حقل Base URL فيه العنوان العام الذي سيستخدمه الموظفون دون مسار Path في آخره، والسبب أن authentik يبني منه الروابط التي يرسلها في البريد ويعطيها للتطبيقات.

وبعد الضغط على Continue سوف تصل إلى واجهة المستخدم User interface، وهي الصفحة التي سيراها كل موظف وفيها التطبيقات المسموح له بها وإعدادات حسابه، أما زر Admin interface في أعلاها فلا يظهر إلا للمديرين.

ما الذي تضمه لوحة الإدارة؟

القائمة الجانبية طويلة وقد تبدو مربكة من الوهلة الأولى، ولكنك في الواقع سوف تستخدم يومياً أقساماً قليلة منها، وهي كما يلي:

وأول ما سوف تعدله هو System ← Brands، حيث تغير فيه عنوان النظام Title والشعار إلى هوية شركتك، والسبب أن صفحة الدخول هي أول ما يراه الموظف، وعندما يرى عليها اسم شركته وشعارها فسوف يثق بها ولا يظنها صفحة غريبة.

إنشاء مستخدم ومجموعة

من Directory ← Users اضغط New User، وسوف يسألك authentik أولاً عن نوع الحساب: Internal للموظفين، وExternal للعملاء والمتعاقدين، وService Account للأنظمة الآلية، فاختر Internal ثم أدخل اسم المستخدم والاسم الظاهر والبريد.

والمستخدم الجديد يكون بلا كلمة مرور، وفي صفحته خياران: الأول Set password حيث تعين كلمة المرور بنفسك ثم ترسلها إليه عبر قناة آمنة، والثاني Create recovery link حيث ترسل إليه رابطاً يختار منه كلمة مروره بنفسه. والخيار الثاني هو الأفضل بعد أن تعد البريد وتدفق الاستعادة Recovery Flow، والسبب أن كلمة المرور لا يعرفها أحد غير صاحبها.

وعلى المجموعات سوف تبني الصلاحيات Permissions لاحقاً، مثل من يدخل Gitea ومن يكون مديراً فيه. من Directory ← Groups اضغط New Group وسمها مثلاً engineering، ثم افتحها ومن تبويب Users اضغط Add Existing User.

إعداد البريد الصادر Outgoing Mail

يرسل authentik البريد عند استعادة كلمة المرور، ومع الدعوات، وللتحقق من البريد عند التسجيل، وفي التنبيهات، وإعداداته في ملف .env كما رأينا، وفيما يلي القيم الشائعة بحسب نوع الاتصال:

ولا تقم بتفعيل USE_TLS وUSE_SSL معاً، والسبب أن الأول يبدأ الاتصال عادياً ثم يرقيه إلى TLS والثاني يبدأه مشفراً من أول بايت، فلا يجتمعان على منفذ واحد. وبعد تعديل .env أعد إنشاء الـ Containers حتى تقرأ القيم الجديدة، ثم أرسل رسالة اختبار من داخل الـ worker:

docker compose up -d --force-recreate server worker

docker compose exec worker ak test_email [email protected]

والمخرج سوف يكون السطر Test email sent to [email protected]، وهذا يعني أن سيرفر SMTP قبل الرسالة. ولتجربة البريد قبل ربط مزود حقيقي وجهه إلى Mailpit، وهو سيرفر SMTP وهمي يلتقط الرسائل ويعرضها دون أن يرسلها كما في الصورة التالية، أما وصول الرسائل إلى صناديق بريد Mailboxes حقيقية فيعتمد على مزودك وعلى سجلات SPF وDKIM لنطاقك، وقد شرحناها في شرح SPF وDKIM وDMARC للمبتدئين.

وإذا أردت سيرفر بريد خاصاً بك بدل مزود خارجي فراجع دليل تثبيت mailcow.

فرض المصادقة الثنائية TOTP

حساب مدير authentik هو مفتاح كل تطبيقاتك، فإذا سرقت كلمة مروره وحدها فقد فتحت كل الأبواب مرة واحدة، لذلك يجب ألا تكفي كلمة المرور وحدها للدخول. والترتيب هنا مهم: سجل جهاز المصادقة Authenticator لحسابك أولاً، ثم افرضه على الجميع، والسبب أنك إذا عكست الترتيب فسوف تغلق الباب على نفسك.

تسجيل تطبيق المصادقة لحساب المدير

من واجهة المستخدم افتح الإعدادات من رمز الترس، ثم Credentials، ومن زر Enroll اختر TOTP Device.

امسح رمز QR بأي تطبيق TOTP مثل Microsoft Authenticator أو Google Authenticator أو Aegis أو مدير كلمات مرور يدعم TOTP، ثم أدخل الرمز المكون من ست خانات.

ومن القائمة نفسها أضف Static tokens واحفظها في مكان آمن خارج السيرفر، وهي رموز احتياطية Backup Codes يصلح كل رمز منها لمرة واحدة، وتستخدمها إذا فقدت هاتفك أو تعطل.

جعل المصادقة الثنائية إلزامية

في تدفق الدخول الافتراضي default-authentication-flow خطوة تحقق Validation Stage جاهزة اسمها default-authentication-mfa-validation، ولكنها مضبوطة على تخطي المستخدم الذي لا يملك جهازاً، وبالتالي فالمصادقة الثنائية بعد التثبيت اختيارية لمن يريدها فقط. لذلك سوف نعدل هذه الخطوة من Flows and Stages ← Stages كما يلي:

• Not configured action: اختر Force the user to configure an authenticator.
• Configuration stages: انقل default-authenticator-totp-setup إلى القائمة المختارة، وأضف WebAuthn إن أردت استخدام مفاتيح الأمان Security Keys.
• Device classes: أبق TOTP وStatic وWebAuthn مفعلة.

وبعد الحفظ سوف يطلب authentik من كل مستخدم ليس له جهاز مسجل أن يمسح رمز QR قبل إكمال الدخول، ومن لديه جهاز سيطلب منه الرمز. وللتأكد سجل الدخول بمستخدم عادي مثل sara في نافذة خاصة Private Window، وسوف تجد أن صفحة إعداد TOTP تظهر بعد كلمة المرور مباشرة.

ربط authentik بنطاق Domain وشهادة TLS

في Nginx Proxy Manager أضف Proxy Host جديداً بالإعدادات التالية:

• Domain Names: auth.example.com
• Scheme: http، وForward Hostname: authentik-server-1 أو اسم الـ Container كما يظهر في docker compose ps (بشرط أن يكون NPM على شبكة proxy)، وForward Port: 9000
• فعل Websockets Support وBlock Common Exploits.
• من تبويب SSL اطلب شهادة Let's Encrypt، وفعل Force SSL وHTTP/2.

وإذا كنت تستخدم Caddy فهذا كل ما تحتاجه:

auth.example.com {
    reverse_proxy authentik-server-1:9000
}

يقرأ authentik الـ Headers X-Forwarded-Proto وX-Forwarded-For حتى يعرف أن الطلب جاء عبر HTTPS ومن أي عنوان IP. ومنذ الإصدار 2026.8 لا يقبل هذه الـ Headers افتراضياً إلا من الشبكات الخاصة 127.0.0.0/8 و10.0.0.0/8 و172.16.0.0/12 و192.168.0.0/16 (ومعها عناوين IPv6 المحلية)، وهذا يشمل الـ Reverse Proxy الذي يعمل في Container على السيرفر نفسه، فإذا كان الـ Reverse Proxy على عنوان آخر فأضفه صراحة:

AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS=203.0.113.10/32,172.16.0.0/12

ولاحظ أن هذا المتغير يستبدل القائمة الافتراضية ولا يضيف إليها، لذلك ضع فيه عنوان الـ Reverse Proxy الخارجي ومعه نطاق شبكة Docker التي يصل منها الـ Reverse Proxy المحلي (172.16.0.0/12 في المثال)، وتستطيع معرفة نطاق شبكتك بالأمر docker network inspect proxy. وبعد إعداد النطاق تأكد أن System ← Brands وعنوان Base URL يشيران إلى https://auth.example.com، وخطوات NPM مشروحة بالتفصيل في دليله.

كيف تتأكد أن كل شيء يعمل

• كل الـ Containers في حالة healthy: docker compose ps.
• في لوحة الإدارة بطاقة Version تعرض الإصدار 2026.8.3 مع «Up-to-date»، وبطاقة Workers فيها worker واحد على الأقل، وبطاقة Outpost status باللون الأخضر.
• تسجيل الدخول من نافذة خاصة يطلب رمز TOTP لحساب akadmin.
• الأمر ak test_email يرسل الرسالة دون خطأ، وتصل إلى صندوقك.
• في Events ← Logs تظهر أحداث Login وPassword set بعنوان IP الحقيقي للعميل وليس بعنوان الـ Reverse Proxy، وإذا لم يكن كذلك فراجع قائمة الـ Proxies الموثوقة.

نقاط فحص الصحة Health Checks ترد بالرمز 200، والمخرج سوف يكون 200 لكل منهما:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9000/-/health/live/
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9000/-/health/ready/

النسخ الاحتياطي والاستعادة Restore

حالة authentik كلها في PostgreSQL: المستخدمون، وكلمات المرور بعد الـ Hashing، وأجهزة MFA، والتطبيقات، والتدفقات، والمفاتيح. واحفظ مع قاعدة البيانات ملف .env، والسبب أن النسخة المستعادة لن تعمل كما ينبغي دون المفتاح الأصلي AUTHENTIK_SECRET_KEY، واحفظ كذلك المجلدات data وcerts وcustom-templates:

cd /opt/authentik
mkdir -p backups
docker compose exec -T postgresql pg_dump -U authentik -d authentik -Fc > backups/authentik-$(date +%F).dump
tar czf backups/authentik-files-$(date +%F).tar.gz .env docker-compose.yml data certs custom-templates

ثم جدول النسخ يومياً عبر cron، وانقل الملفات إلى خارج السيرفر، واحذف القديم منها:

0 3 * * * cd /opt/authentik && docker compose exec -T postgresql pg_dump -U authentik -d authentik -Fc > backups/authentik-$(date +\%F).dump && find backups -mtime +14 -delete

وللاستعادة على سيرفر جديد انسخ المجلد والملفات، وشغل قاعدة البيانات وحدها، ثم استعد النسخة قبل تشغيل server وworker:

cd /opt/authentik
tar xzf backups/authentik-files-2026-09-26.tar.gz
docker compose up -d postgresql
docker compose exec -T postgresql pg_restore -U authentik -d authentik --clean --if-exists --no-owner < backups/authentik-2026-09-26.dump
docker compose up -d

والأمر pg_restore على قاعدة بيانات فارغة يعيد كل الحسابات، وعند التشغيل بعده لا يعيد authentik الترحيلات من البداية فيعود خلال دقيقة تقريباً بدل ربع ساعة. ولكن تذكر أن النسخة التي لم تجرب استعادتها لا يعتمد عليها، لذلك جرب الاستعادة على سيرفر تجريبي Staging مرة كل بضعة أشهر.

التحديث إلى إصدار أحدث

قواعد التحديث في authentik صارمة، فالتزم بها:

• لا يدعم authentik الرجوع إلى إصدار أقدم Downgrade، لذلك خذ نسخة من قاعدة البيانات قبل كل تحديث.
• انتقل بين الإصدارات الرئيسية Major Releases بالترتيب، مثلاً 2026.5 ثم 2026.8، ولا تقفز من إصدار قديم جداً إلى أحدث إصدار مباشرة، حتى لو بدا لك ذلك أسرع.
• اقرأ ملاحظات الإصدار Release Notes وقسم Breaking changes قبل التحديث، ففي 2026.8 مثلاً تغيرت طريقة التعامل مع Headers الـ Reverse Proxy.
• إذا كانت لديك outposts منفصلة من نوع Proxy أو LDAP فحدثها إلى الإصدار نفسه في الوقت نفسه، لأن authentik يشترط أن يتطابق إصدار السيرفر وكل الـ outposts.

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik -d authentik -Fc > backups/before-upgrade-$(date +%F).dump
sed -i 's/^AUTHENTIK_TAG=.*/AUTHENTIK_TAG=2026.8.4/' .env
docker compose pull
docker compose up -d
docker compose logs -f server

ضع مكان 2026.8.4 الإصدار الذي تريده من صفحة الإصدارات، وقارن ملف Compose لديك بالملف الرسمي للإصدار الجديد، فقد يضيف المطورون خدمات أو يحذفونها كما حدث مع Redis، وإذا حذفت خدمة فاستخدم docker compose up -d --remove-orphans. ولا تقم بترقية PostgreSQL إلى إصدار رئيسي جديد (من 16 إلى 17 مثلاً) بتغيير الوسم Tag وحده، والسبب أن ملفات البيانات لا تقرأ بين الإصدارات الرئيسية، فهذا يتطلب نسخاً واستعادة، ولاحظ أن الإصدارات الحالية من authentik تدعم PostgreSQL من 14 إلى 18.

مشكلات شائعة وحلولها

الصفحة ترد بالرمز 503 أو لا تفتح بعد التشغيل

السيرفر ما زال ينفذ الترحيلات، أو أن الـ worker لم ينته بعد من تجهيز التدفقات الافتراضية، وعندها تجد في السجل الرسالة Setup flow does not exist yet, waiting for worker to finish. تابع docker compose logs -f server وانتظر حتى تظهر سجلات الطلبات المعتادة. وإذا توقف السيرفر مع خطأ في الاتصال بقاعدة البيانات فتأكد أن PG_PASS لم يتغير بعد إنشاء الـ Volume، والسبب أن PostgreSQL لا يقرأ كلمة المرور من المتغير إلا عند الإنشاء الأول.

رسالة «Request has been denied» عند فتح صفحة الإعداد الأولي

الإصدارات الحديثة ترفض فتح /if/flow/initial-setup/ مباشرة وتعرض رسالة «Access the authentik setup by navigating to…»، والحل أن تفتح العنوان الرئيسي للموقع https://auth.example.com/ فيحولك إلى الإعداد بالشكل الصحيح. وإذا ظهرت الرسالة بعد إكمال الإعداد فهذا طبيعي، لأن الإعداد يعمل مرة واحدة فقط.

خطأ CSRF أو روابط تبدأ بـ http رغم استخدام HTTPS

السبب أن الـ Reverse Proxy لا يمرر X-Forwarded-Proto، أو أن عنوانه ليس ضمن AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS، فأضف عنوانه إلى هذا المتغير ثم أعد إنشاء Container الـ server.

فشل الأمر ak test_email

السبب غالباً إعداد TLS لا يطابق المنفذ، فالصحيح STARTTLS على 587 مع USE_TLS=true وSSL على 465 مع USE_SSL=true، أو أن مزود الاستضافة يحجب المنفذ 25 أو 587 على السيرفرات الجديدة، وتستطيع اختبار الاتصال من السيرفر بالأمر nc -vz smtp.example.com 587.

رمز TOTP مرفوض دائماً

السبب فرق في الوقت بين السيرفر والهاتف Clock Drift، لأن رمز TOTP مبني على الوقت، فتحقق بالأمر timedatectl أن مزامنة الوقت NTP مفعلة على السيرفر.

فقدت جهاز المصادقة أو كلمة مرور المدير

استخدم أحد الرموز الاحتياطية Static tokens، وإذا لم تكن لديك فأنشئ من سطر الأوامر Command Line رابط استعادة صالحاً لعشر دقائق، ثم افتحه وأعد تعيين جهازك:

docker compose exec worker ak create_recovery_key 10 akadmin

والمخرج سوف يكون السطر This recovery token is valid for 10 minutes. ثم مسار يبدأ بـ /recovery/use-token/، فأضفه إلى عنوان النسخة وافتحه في المتصفح.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

• حساب مستقل لكل موظف في كل تطبيق يفشل يوم يغادر الموظف، ومزود الهوية مثل authentik يجعل إغلاق كل الأبواب خطوة واحدة.
• authentik منذ 2025.10 لا يحتاج إلى Redis، وملف Compose فيه PostgreSQL وserver وworker فقط، ومجلد البيانات صار /data.
• اربط منافذ authentik بالعنوان 127.0.0.1، ولا تمرر docker.sock إلى الـ worker إلا عند الحاجة وعبر Docker Socket Proxy.
• أكمل الإعداد الأولي فور التشغيل من العنوان الرئيسي للموقع، ثم سجل جهاز TOTP لحسابك قبل أن تفرض المصادقة الثنائية على الجميع.
• انسخ قاعدة البيانات مع ملف .env ومفتاح AUTHENTIK_SECRET_KEY، وحدث بين الإصدارات الرئيسية بالترتيب وبعد نسخة احتياطية.

سجل التحديثات

• سبتمبر 2026: كتابة الدليل واختباره على authentik 2026.8.3.
• أكتوبر 2026: مراجعة الدليل على authentik 2026.8.3: صححنا تاريخ إزالة Redis (المهام في 2025.8 والباقي في 2025.10)، وأضفنا إصدار انتقال المجلد إلى /data (2025.12) وطريقة نقل الملفات القديمة، ووضحنا أن AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS يستبدل القائمة الافتراضية، وأضفنا انتظار الـ worker قبل صفحة الإعداد.