راهنمای نصب Authentik با Docker Compose و Traefik

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

Authentik یک سرور SSO (ورود یکپارچه) است که به‌صورت self-hosted اجرا می‌شود: کاربران شما یک‌بار وارد می‌شوند و تمام برنامه‌های پشت آن، به‌جای درخواست رمز عبور جداگانه، همان نشست (session) را می‌پذیرند. نصب آن شامل یک فایل Docker Compose رسمی و دو secret تولیدشده است. بخشی که نیاز به تأمل جدی دارد، پس از نصب است: هدایت یک reverse proxy به سمت آن و قرار دادن یک برنامهٔ موجود پشت forward auth.

Authentik در آن فایل Compose به‌صورت سه سرویس عرضه می‌شود: یک دیتابیس PostgreSQL، یک پردازش server و یک پردازش worker. کانتینر سرور همچنین outpost تعبیه‌شده را اجرا می‌کند؛ این همان مؤلفه‌ای است که به پرسش «آیا این درخواست احراز هویت شده است؟» برای هر برنامهٔ محافظت‌شده پاسخ می‌دهد. نسخه 2026.5 نسخه فعلی تا ژوئیه 2026 است و پروژه حداقل به میزبانی با 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 باید سه کانتینر را فهرست کند، که در آن 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 استفاده کند، بنابراین ایمیل‌های بازنشانی رمز عبور به عنوان خطای اتصال در لاگ worker ثبت می‌شوند.
• AUTHENTIK_LOG_LEVEL=debug جزئیاتی را که هنگام اختلال در جریان ورود (login flow) نیاز دارید، فعال می‌کند. پس از اتمام کار، آن را به info برگردانید.
• AUTHENTIK_ERROR_REPORTING__ENABLED به‌صورت پیش‌فرض false است. آن را فقط در صورتی روی true تنظیم کنید که با ارسال گزارش‌های خرابی به توسعه‌دهندگان موافق باشید.

این‌ها اسرار موجود در یک فایل متنی ساده هستند، بنابراین با دایرکتوری آن همان‌طور رفتار کنید که با هر مخزن اعتبارنامه دیگری رفتار می‌کنید. یک مدیر رمز عبور مانند یک نمونه Vaultwarden خودمیزبان، مکان بهتری برای نگهداری نسخه بازیابی نسبت به یک یادداشت روی لپ‌تاپ شماست.

اولین ورود و حساب کاربری مدیر

در مرورگر خود http://SERVER_IP:9000 را باز کنید. Authentik روند راه‌اندازی اولیه را نمایش می‌دهد و از شما می‌خواهد برای کاربر پیش‌فرض akadmin یک رمز عبور تعیین کنید. اگر قبلاً AUTHENTIK_BOOTSTRAP_PASSWORD را تنظیم کرده‌اید، این مرحله انجام شده است و مستقیماً به صفحه ورود هدایت می‌شوید.

در بخش Directory و سپس Users، برای خودتان یک کاربر عادی با نقش مدیریتی ایجاد کنید، آن را به گروه authentik Admins اضافه کنید و با همان حساب وارد شوید. حساب akadmin را به‌عنوان حساب break-glass نگه دارید و یک گذرواژه طولانی برای آن به‌صورت آفلاین ذخیره کنید. انجام کارهای روزمره با یک حساب داخلی مشترک، لاگ audit را بی‌اعتبار می‌کند، چون در هر رویداد فقط akadmin ثبت می‌شود و مشخص نیست چه کسی عملیات را انجام داده است. این استدلال درباره Authentik نیز صدق می‌کند: ابزاری مانند یک harness خودمیزبان OneCLI که به هر فرد agent اختصاصی خودش را می‌دهد فقط زمانی trail قابل‌خواندنی ایجاد می‌کند که هویتی که به آن می‌رسد به یک انسان مشخص تعلق داشته باشد، نه به login مشترک کل تیم.

قرار دادن Authentik پشت reverse proxy

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

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

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

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

در رابط کاربری وب، به بخش 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-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 نیاز دارد، در وضعیت خروج (logged out) باقی می‌ماند.

خود برنامه محافظت‌شده به دو 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() در همان دامنه اولویت پیدا کند.

در یک پنجره مرورگر خصوصی (private) تست کنید. شما باید به auth.example.com هدایت شوید، وارد شوید و دوباره به برنامه بازگردید. docker compose logs -f server در سمت Authentik، برای هر تلاش یک رویداد مجوزدهی چاپ می‌کند که به شما می‌گوید آیا درخواست اصلاً به Authentik رسیده است یا خیر.

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

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

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

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

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

چه زمانی Keycloak انتخاب بهتری است

پروژه Keycloak قدیمی‌تر است، توسط Red Hat پشتیبانی می‌شود و برای کارهای هویتی کلاسیک سازمانی انتخاب قدرتمندتری محسوب می‌شود: فدراسیون سنگین SAML، واسطه‌گری ورود از چندین ارائه‌دهنده هویت خارجی به‌طور هم‌زمان، و قابلیت export و import کردن realm به‌عنوان یک مسیر مهاجرت مستند. پشتیبانی تجاری پشت این پروژه برای برخی سازمان‌ها روی کاغذ اهمیت دارد. نقطه ضعف این است که Keycloak پروکسی داخلی ندارد؛ بنابراین برای محافظت از برنامه‌ای که از OIDC (OpenID Connect) پشتیبانی نمی‌کند، باید ابزاری مانند oauth2-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 را با هم ذخیره کنید. فایل dump به‌تنهایی کافی نیست، زیرا کلید امنیتی که از داده‌های نشست (session) و توکن محافظت می‌کند، در .env قرار دارد.

ارتقاها با تغییر تگ انجام می‌شوند. مقدار AUTHENTIK_TAG را در .env روی نسخه مورد نظر خود تنظیم کنید، سپس دستور docker compose pull و به دنبال آن docker compose up -d را اجرا کنید. ابتدا یادداشت‌های انتشار (release notes) را مطالعه کنید، زیرا Authentik از نسخه‌بندی مبتنی بر تاریخ استفاده می‌کند و برخی از نسخه‌ها شامل مهاجرت‌هایی (migrations) هستند که انتظار دارند شما از نسخه قبلی به آن رسیده باشید. پیش از اجرای pull، از پایگاه داده dump تهیه کنید، نه پس از آن.

FAQ

آیا Authentik برای میزبانی شخصی (self-host) رایگان است؟

نسخه متن‌باز (open source) رایگان است و تمام موارد ذکر شده در بالا را پوشش می‌دهد: پروکسی پرووایدر، forward auth، OIDC (OpenID Connect)، SAML و موتور جریان‌ها (flows engine). یک سطح اشتراکی سازمانی (enterprise) برای پشتیبانی و برخی قابلیت‌های خاص وجود دارد، اما هیچ‌کدام از موارد این آموزش نیازی به لایسنس ندارند.

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

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

چرا اپلیکیشن محافظت‌شده من مدام بین صفحه ورود و خطا جابه‌جا می‌شود؟

نام دامنه خارجی (external host) تنظیم‌شده در proxy provider با URL مورد استفاده در مرورگر مطابقت ندارد؛ این مشکل معمولاً ناشی از تفاوت بین http و https است. کوکی نشست (session cookie) برای یک مبدأ صادر شده و در مبدأ دیگری خوانده می‌شود، بنابراین Authentik هر بار درخواست را به عنوان یک کاربر ناشناس می‌بیند. نام دامنه خارجی را اصلاح کنید و پیش از تست مجدد، کوکی‌های هر دو دامنه را پاک کنید.

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

حداقل سخت‌افزار مستندشده تا ژوئیه 2026، شامل 2 هسته CPU و 2 گیگابایت RAM است که مجموعاً PostgreSQL، سرور و worker را پوشش می‌دهد. در یک سرور 2 گیگابایتی، worker اولین فرآیندی است که هسته سیستم‌عامل (kernel) هنگام فشار حافظه آن را می‌کشد (kill می‌کند)؛ نشانه این اتفاق، توقف وظایف پس‌زمینه و ارسال ایمیل است، در حالی که صفحه ورود همچنان کار می‌کند. اگر همان سرور میزبان اپلیکیشن‌هایی است که از آن‌ها محافظت می‌کنید، 4 گیگابایت RAM به آن اختصاص دهید.