راهنمای نصب و راه‌اندازی Authentik با Docker Compose

یک ورود برای تمام برنامه‌هایی که میزبانی می‌کنید

Authentik یک سرور SSO (ورود یکپارچه) خودمیزبان است: کاربران شما یک بار وارد می‌شوند و هر برنامه‌ای که پشت آن قرار دارد، به‌جای درخواست رمز عبور جداگانه، همان نشست (session) را می‌پذیرد. نصب آن شامل یک فایل Docker Compose رسمی و دو secret تولیدشده است. بخش اصلی که نیاز به تأمل دارد، پس از نصب است: هدایت یک 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 اکتبر به‌عنوان تگ پیش‌فرض ایمیج در فایل Compose رسمی شده است. این پروژه به میزبانی با حداقل 2 هسته CPU و 2 گیگابایت رم نیاز دارد. این مقدار را به‌عنوان حداقل در نظر بگیرید. PostgreSQL و worker هر دو پس از یک روز فعالیت سرور، حافظه را اشغال می‌کنند.

پیش‌نیازهای شروع کار

شما به Docker Engine به همراه افزونه Compose v2 نیاز دارید که می‌توانید آن را با دستور docker compose version تأیید کنید. اگر این دستور به‌جای نمایش نسخه، خطا داد، پیش از ادامه کار افزونه را نصب کنید؛ اصول اولیه این کار در اجرای برنامه‌ها با Docker Compose روی یک VPS پوشش داده شده است. همچنین به یک رکورد DNS از نوع A نیاز دارید که به سرور اشاره کند (در مثال‌های زیر auth.example.com)، زیرا Authentik آدرس‌های redirect خود را بر اساس نام دامنه‌ای که مرورگر استفاده کرده است، می‌سازد.

این stack را به‌عنوان یک کاربر معمولی در گروه docker اجرا کنید و نه به‌عنوان root. عضویت در این گروه معادل دسترسی root روی میزبان است، بنابراین آن را فقط به یک حساب کاربری مخصوص استقرار (deploy) بدهید و نه هیچ‌کس دیگر، مطابق با دستورالعمل حساب‌های کاربری با حداقل دسترسی روی یک 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 باید سه کانتینر را در وضعیت up نشان دهد و postgresql پس از گذراندن بررسی، healthy را گزارش کند. اولین اجرا، مهاجرت‌های دیتابیس را انجام می‌دهد، بنابراین پیش از آنکه رابط وب پاسخ دهد، یک دقیقه صبر کنید.

هر دو مقدار تولیدشده به دلایل مختلف اهمیت دارند. PG_PASS رمز عبور PostgreSQL است. مستندات نصب Authentik می‌گوید رمزهای عبور طولانی‌تر از 99 کاراکتر پشتیبانی نمی‌شوند، بنابراین هر رمز عبوری که خودتان انتخاب می‌کنید را کوتاه‌تر از این مقدار نگه دارید؛ رمز تولیدشده بسیار کوتاه‌تر است. AUTHENTIK_SECRET_KEY کلیدی است که Authentik برای امضای کوکی‌ها استفاده می‌کند و مستندات پیکربندی آن می‌گوید تغییر آن باعث ابطال نشست‌های فعال می‌شود، بنابراین یک کلید جدید در آینده، تمام کاربران واردشده را خارج (logout) می‌کند. .env را در حالت 600 نگه دارید و یک کپی از آن را در جایی امن همراه با بک‌آپ‌های خود ذخیره کنید تا در صورت بازیابی، سرور با همان کلید قبلی بالا بیاید.

فایل Compose هر دو مقدار را با فرمت ${VAR:?message} به‌عنوان الزامی علامت‌گذاری کرده است: ${PG_PASS:?database password required} در سرویس PostgreSQL و ${AUTHENTIK_SECRET_KEY:?secret key required} در سرور و worker. این یعنی اگر فایل موجود نباشد، 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 token را تنظیم می‌کنند.
• 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 روی پورت 25 تلاش می‌کند به localhost متصل شود؛ بنابراین ایمیل‌های بازنشانی گذرواژه در لاگ worker با خطای اتصال پایان می‌یابند.
• AUTHENTIK_LOG_LEVEL=debug جزئیاتی را فعال می‌کند که هنگام اختلال در login flow به آن نیاز دارید. پس از پایان کار، آن را به info برگردانید.
• AUTHENTIK_ERROR_REPORTING__ENABLED به‌طور پیش‌فرض false است. فقط در صورتی آن را روی true تنظیم کنید که با ارسال گزارش‌های crash به upstream موافق باشید.

این مقادیر در یک فایل متنی ساده و شامل secret هستند؛ بنابراین با این directory مانند هر محل دیگری برای نگهداری credential رفتار کنید. یک password manager مانند نمونه self-hosted از 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 خودمیزبان که به هر فرد agent اختصاصی می‌دهد تنها در صورتی ردپای خوانا باقی می‌گذارد که هویتِ واردشده به آن متعلق به یک انسان باشد، نه یک حساب کاربری که کل تیم به اشتراک می‌گذارند.

احراز هویت Authentik را پشت reverse proxy قرار دهید

انتشار پورت 9000 در اینترنت کار می‌کند، اما به TLS (امنیت لایهٔ انتقال) و یک hostname واقعی نیاز دارید. اگر setup مربوط به Traefik به‌عنوان reverse proxy برای چند برنامه Compose را از قبل اجرا می‌کنید، با استفاده از یک فایل override، 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 فایل override را به‌صورت خودکار ادغام می‌کند؛ بنابراین سرویس server همهٔ تنظیمات فایل رسمی را حفظ می‌کند و labelها را نیز دریافت می‌کند. با curl -I https://auth.example.com/if/user/ بررسی کنید؛ این دستور باید به HTTP/2 200 پاسخ دهد. دریافت 404 page not found از Traefik یعنی هیچ routerی با درخواست مطابقت نداشته است. بررسی کنید labelها به container رسیده باشند، rule مربوط به Host() دقیقاً با hostname مطابقت داشته باشد و درخواست از entry point مربوط به HTTPS وارد شده باشد که router روی آن گوش می‌دهد.

پس از کارکردن hostname، در فایل override پورت‌های publish‌شده را به 127.0.0.1 bind کنید تا تنها مسیر ورود از طریق proxy باشد.

محافظت از یک برنامه با forward auth

ارائه‌دهنده پروکسی Authentik دارای سه حالت است و انتخاب اشتباه آن می‌تواند یک ساعت وقت شما را تلف کند. حالت Proxy به این معناست که خود outpost ترافیک را به برنامه بالادستی (upstream) هدایت می‌کند. حالت Forward auth (single application) به این معناست که reverse proxy شما همچنان ترافیک را جابه‌جا می‌کند و فقط از Authentik می‌پرسد که آیا درخواست، احراز هویت شده است یا خیر. حالت Forward auth (domain level) از تمام برنامه‌های زیرمجموعه یک دامنه اصلی با یک ارائه‌دهنده واحد محافظت می‌کند، اما به قیمت از دست دادن قوانین مجوزدهی برای هر برنامه به‌صورت جداگانه. با وجود Traefik در لایه جلو، شما به حالت forward auth (single application) نیاز دارید. اگر به دنبال یک برنامه مشخص برای تمرین هستید، یک فضای کاری AFFiNE خودمیزبان گزینه مناسبی است، زیرا این نوع ابزارهای داخلی همان‌هایی هستند که می‌خواهید فقط از دستگاه‌های خودتان در دسترس باشند و نه هیچ جای دیگر. این موضوع برای ابزارهای تیمی اهمیت بیشتری دارد: یک میز پشتیبانی Chatwoot خودمیزبان را پشت همان ارائه‌دهنده قرار دهید تا هر کسی که به صندوق ورودی پاسخ می‌دهد، به‌جای اشتراک‌گذاری یک رمز عبور دیگر، یک‌بار در روز وارد سیستم شود.

در رابط کاربری وب، به بخش Applications و سپس Providers بروید، یک Proxy Provider ایجاد کنید، حالت forward auth single application را انتخاب کرده و میزبان خارجی (external host) را روی https://app.example.com تنظیم کنید. یک Application ایجاد کنید که به آن ارائه‌دهنده اشاره کند. سپس به بخش Outposts بروید، authentik Embedded Outpost را ویرایش کنید و برنامه جدید را به لیست برنامه‌های انتخاب‌شده (selected applications) اضافه کنید. 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-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، کاملاً مشهود است؛ جایی که هدرها تفاوت بین یک‌بار و دوبار درخواست ورود برای یک صفحه واحد هستند.

خود برنامه محافظت‌شده به دو روتر نیاز دارد، نه یکی:

    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 رسیده است یا خیر.

خطاهایی که واقعاً با آن‌ها مواجه خواهید شد

حلقه تغییر مسیر (redirect loop) بی‌پایان بین برنامه و صفحه ورود. میزبان خارجی (external host) در ارائه‌دهنده با آنچه مرورگر استفاده می‌کند مطابقت ندارد؛ معمولاً http:// در ارائه‌دهنده در مقابل https:// در نوار آدرس. کوکی نشست (session cookie) برای یک مبدأ متفاوت تنظیم می‌شود، بنابراین هر بار بازگشت، مانند یک درخواست ناشناس جدید به نظر می‌رسد. میزبان خارجی را اصلاح کنید و پیش از تست مجدد، کوکی‌های هر دو دامنه را پاک کنید.

خطای 404 در /outpost.goauthentik.io/start. مسیریاب outpost وجود ندارد یا اولویت آن از مسیریاب catch-all برای آن میزبان کمتر است.

برنامه بدون درخواست ورود بارگذاری می‌شود. برچسب middlewares به یک میان‌افزار (middleware) اشاره دارد که وجود ندارد. Traefik در این مورد هشداری نمی‌دهد، بنابراین یک غلط تایپی در authentik@docker به سادگی به این معنی است که هیچ میان‌افزاری اجرا نمی‌شود. داشبورد Traefik را باز کنید و تأیید کنید که مسیریاب، میان‌افزار مورد نظر را فهرست کرده است.

خطای 403 از Authentik پس از ورود موفق. کاربر احراز هویت شده اما مجوز دسترسی ندارد: برنامه دارای یک binding خط‌مشی (policy binding) یا شرط عضویت در گروه است که این کاربر واجد آن نیست. لاگ Events در رابط کاربری مدیریت، نام خط‌مشی‌ای که دسترسی را رد کرده است، نشان می‌دهد.

وقتی Keycloak انتخاب مناسب‌تری است

Keycloak پروژه‌ای قدیمی‌تر است که Red Hat از آن پشتیبانی می‌کند و برای کارهای کلاسیک هویت سازمانی انتخاب قدرتمندتری به شمار می‌رود: federation گسترده با SAML، واسطه‌گری ورود از چند identity provider خارجی به‌طور هم‌زمان، و export و import کردن realm به‌عنوان یک مسیر مستند برای migration. پشتیبانی تجاری پشت آن نیز برای برخی سازمان‌ها، دست‌کم روی کاغذ، اهمیت دارد. در مقابل، Keycloak proxy اختصاصی ندارد. بنابراین برای محافظت از برنامه‌ای که نه با OIDC (OpenID Connect) و نه با SAML کار می‌کند، باید چیزی مانند oauth2-proxy را در کنار آن اجرا کنید. proxy provider داخلی Authentik همین نقش را ایفا می‌کند و از ابتدا یکپارچه است؛ به همین دلیل بیشتر self-hosterهایی که مجموعه‌ای متنوع از برنامه‌ها دارند، در نهایت Authentik را انتخاب می‌کنند.

بک‌آپ و ارتقا

سه چیز بازیابی را ممکن می‌سازد: دیتابیس PostgreSQL، دایرکتوری ./data و .env.

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

آن دامپ و .env را با هم ذخیره کنید. دامپ هیچ کپی‌ای از AUTHENTIK_SECRET_KEY ندارد و بازیابی با کلیدی متفاوت، تمام نشست‌های فعال را باطل می‌کند، بنابراین نگهداری کلید اصلی باعث می‌شود سرور بازیابی‌شده به همان شکلی که بود به کار خود ادامه دهد.

ارتقاها تغییر تگ هستند. AUTHENTIK_TAG را در .env روی نسخه‌ای که می‌خواهید تنظیم کنید، سپس docker compose pull و به دنبال آن docker compose up -d را اجرا کنید. اگر هرگز AUTHENTIK_TAG را تنظیم نکرده‌اید، نسخه از مقدار پیش‌فرض نوشته‌شده در خود compose.yml می‌آید، بنابراین دانلود یک کپی جدیدتر از آن فایل، همان ارتقا است و این مسیری است که مستندات رسمی ارتقا توصیف می‌کنند. ابتدا یادداشت‌های انتشار را بخوانید. Authentik از نسخه‌های مبتنی بر تاریخ استفاده می‌کند و تا اکتبر 2026 مستندات آن می‌گوید ارتقاها باید توالی نسخه‌های اصلی را دنبال کنند: به آخرین وصله از سری که اجرا می‌کنید بروید، سپس بدون جا انداختن هیچ سری، مرحله‌به‌مرحله به سری‌های بعدی بروید. Authentik از دانگرید (بازگشت به نسخه قدیمی) پشتیبانی نمی‌کند، بنابراین پیش از pull کردن، نه بعد از آن، از دیتابیس دامپ بگیرید.

FAQ

آیا Authentik برای self-hosting رایگان است؟

نسخهٔ متن‌باز رایگان است و همهٔ قابلیت‌های بالا را پوشش می‌دهد: proxy provider، forward auth، OIDC (OpenID Connect)، SAML و flows engine. یک سطح پولی enterprise، پشتیبانی و برخی قابلیت‌های سازمانی را اضافه می‌کند؛ اما هیچ‌یک از موارد اینجا به licence نیاز ندارد.

آیا برای استفاده از Authentik به Traefik نیاز دارم؟

خیر. forward auth از طریق auth_request با nginx و از طریق forward_auth با Caddy کار می‌کند. الگو در همهٔ موارد یکسان است: reverse proxy دربارهٔ هر درخواست از Authentik پرس‌وجو می‌کند و prefix مسیر /outpost.goauthentik.io/ در hostname محافظت‌شده باید به‌جای برنامه به Authentik route شود.

چرا برنامهٔ محافظت‌شدهٔ من دائماً بین صفحهٔ ورود و خطا جابه‌جا می‌شود؟

host خارجی پیکربندی‌شده در proxy provider با URL مورد استفادهٔ مرورگر یکسان نیست؛ در بیشتر موارد، مشکل از http در برابر https ناشی می‌شود. session cookie برای یک origin صادر می‌شود و در origin دیگری خوانده می‌شود؛ بنابراین Authentik هر بار درخواست را anonymous می‌بیند. host خارجی را اصلاح کنید، سپس پیش از آزمایش دوباره، cookieهای هر دو hostname را پاک کنید.

Authentik به چه مقدار RAM نیاز دارد؟

حداقل مستندشده تا اکتبر 2026، 2 هستهٔ CPU و 2 GB RAM است که PostgreSQL، server و worker را به‌صورت مجموع پوشش می‌دهد. در یک سیستم 2 GB، فشار حافظه می‌تواند kernel's OOM killer را فعال کند. این سازوکار پردازشی را خاتمه می‌دهد که بالاترین badness score را دارد: تقریباً سهم حافظهٔ مجاز مورد استفادهٔ آن، به‌علاوهٔ oom_score_adj. اگر این پردازش worker باشد، نشانهٔ آن متوقف‌شدن taskهای پس‌زمینه و email خروجی است، درحالی‌که صفحهٔ ورود همچنان کار می‌کند. اگر همان server برنامه‌هایی را نیز اجرا می‌کند که از آن‌ها محافظت می‌کنید، 4 GB RAM اختصاص دهید.