Authentik چیست و چگونه SSO را با Docker اجرا کنیم؟

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

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

Authentik در آن فایل Compose به‌صورت 3 سرویس ارائه می‌شود: یک پایگاه داده PostgreSQL، یک فرایند server و یک فرایند worker. کانتینر سرور همچنین outpost داخلی را اجرا می‌کند. این مؤلفه برای هر برنامه محافظت‌شده پاسخ می‌دهد که «آیا این درخواست با ورود کاربر همراه است؟». نسخه 2026.5 تا ژوئیه 2026، نسخه فعلی است و پروژه میزبانی با حداقل 2 هسته CPU و 2 GB RAM را درخواست می‌کند. این مقدار را حداقل موردنیاز در نظر بگیرید. PostgreSQL و worker پس از 1 روز فعال بودن سرور همچنان حافظه مصرف می‌کنند.

پیش‌نیازها

به 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 باید سه container را فهرست کند؛ postgresql باید healthy را گزارش کند و server باید worker را گزارش کند و running را نمایش دهد. اولین راه‌اندازی migrationهای پایگاه‌داده را اجرا می‌کند؛ بنابراین پیش از پاسخ‌گویی رابط وب، یک دقیقه صبر کنید.

هر دو مقدار تولیدشده، به دلایل متفاوت، مهم هستند. PG_PASS گذرواژه PostgreSQL است و حداکثر طول آن 99 نویسه است. AUTHENTIK_SECRET_KEY نشست‌ها و tokenها را امضا می‌کند؛ بنابراین تغییر آن در آینده همه کاربران را از حساب خارج می‌کند و همه API tokenهای صادرشده را بی‌اعتبار می‌سازد. حالت دسترسی .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 نیز به همین روش نشانی آن کاربر و یک 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 ارسال mail خروجی را پیکربندی می‌کنند. بدون این مقادیر، Authentik روی پورت 25 به localhost متصل می‌شود؛ بنابراین mailهای بازنشانی گذرواژه در log مربوط به worker با خطای اتصال پایان می‌یابند.
• AUTHENTIK_LOG_LEVEL=debug جزئیاتی را که هنگام اختلال در flow ورود لازم دارید فعال می‌کند. پس از آن، مقدار را به info برگردانید.
• مقدار پیش‌فرض AUTHENTIK_ERROR_REPORTING__ENABLED، false است. فقط در صورتی آن را روی true تنظیم کنید که با ارسال گزارش‌های crash به upstream موافق باشید.

این موارد secretهایی در یک فایل متنی ساده هستند؛ بنابراین با این directory مانند هر محل نگهداری credential دیگر رفتار کنید. یک password manager مانند نمونه self-hosted از Vaultwarden برای نگهداری نسخه پشتیبان بازیابی، از یادداشتی روی laptop شما مناسب‌تر است.

نخستین ورود و حساب مدیریتی

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

در بخش Directory و سپس Users، یک کاربر مدیریتی عادی برای خودتان ایجاد کنید، آن را به گروه authentik Admins اضافه کنید و با همان حساب وارد شوید. akadmin را به‌عنوان حساب دسترسی اضطراری نگه دارید و یک گذرواژه طولانی برای آن تعیین کنید و به‌صورت آفلاین ذخیره کنید. انجام کارهای روزمره با یک حساب داخلی مشترک، گزارش ممیزی را بی‌اعتبار می‌کند، زیرا در هر رویداد فقط akadmin ثبت می‌شود و مشخص نمی‌کند چه کسی آن عملیات را انجام داده است.

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

انتشار پورت 9000 در اینترنت کار می‌کند، اما به TLS (امنیت لایه انتقال) و یک hostname واقعی نیاز دارید. اگر پیکربندی 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 یعنی کانتینر در شبکه proxy قرار ندارد و Traefik نمی‌تواند درخواست‌ها را به کانتینری هدایت کند که به آن دسترسی ندارد.

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

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

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

در رابط وب، Applications و سپس Providers را باز کنید، یک Proxy Provider ایجاد کنید، حالت forward auth single application را انتخاب کنید و میزبان خارجی را روی https://app.example.com تنظیم کنید. یک Application ایجاد کنید که به آن provider اشاره کند. سپس Outposts را باز کنید، authentik Embedded Outpost را ویرایش کنید و برنامه جدید را به selected applications منتقل کنید. 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 فهرست headerهایی است که Traefik از پاسخ Authentik به درخواستی که برای برنامه بالادستی ارسال می‌کند، کپی می‌کند. اگر آن را حذف کنید، برنامه همچنان محافظت می‌شود، اما هرگز هویت کاربر را دریافت نمی‌کند؛ بنابراین هر چیزی که X-authentik-username را برای ورود خودکار می‌خواند، همچنان در وضعیت خروج از سیستم باقی می‌ماند.

برنامه محافظت‌شده به دو 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/ در hostname برنامه بازمی‌گرداند، نه به auth.example.com. اگر routerی وجود نداشته باشد که این پیشوند مسیر را به سرویس Authentik ارسال کند، درخواست به برنامه شما می‌رسد. برنامه نیز پاسخ 404 می‌دهد و فرایند ورود کامل نمی‌شود. مقدار بالاتر priority باعث می‌شود قانون مسیر مشخص، بر قانون ساده Host() در همان دامنه اولویت داشته باشد.

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

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

حلقه بی‌پایان تغییر مسیر بین برنامه و صفحه ورود. میزبان خارجی در provider با مقداری که مرورگر استفاده می‌کند یکسان نیست؛ معمولاً http:// در provider با https:// در نوار نشانی تفاوت دارد. در نتیجه، کوکی نشست برای مبدأ دیگری تنظیم می‌شود و هر بازگشت مانند یک درخواست ناشناس جدید دیده می‌شود. پیش از آزمایش دوباره، میزبان خارجی را اصلاح کنید و کوکی‌های هر دو دامنه را پاک کنید.

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

برنامه بدون درخواست ورود بارگذاری می‌شود. برچسب middlewares به middlewareای اشاره می‌کند که وجود ندارد. Traefik درباره این وضعیت هشدار نمی‌دهد؛ بنابراین اشتباه تایپی در authentik@docker صرفاً باعث می‌شود هیچ middlewareای اجرا نشود. داشبورد Traefik را باز کنید و بررسی کنید که مسیریاب، middleware را فهرست کرده باشد.

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

وقتی Keycloak گزینه مناسب‌تری است

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

پشتیبان‌گیری و ارتقا

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

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

این dump و `.env را همراه یکدیگر ذخیره کنید. dump به‌تنهایی کافی نیست، زیرا کلید محرمانه‌ای که از داده‌های نشست و token محافظت می‌کند، در .env` قرار دارد.

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

FAQ

آیا Authentik برای میزبانی شخصی رایگان است؟

نسخه متن‌باز رایگان است و همه موارد گفته‌شده در بالا را پوشش می‌دهد: ارائه‌دهنده پراکسی، احراز هویت انتقالی، OIDC (OpenID Connect)، SAML و موتور جریان‌ها. سطح سازمانی پولی، پشتیبانی و برخی قابلیت‌های سازمانی را اضافه می‌کند؛ اما هیچ‌کدام از موارد این راهنما به مجوز نیاز ندارند.

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

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

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

میزبان خارجی پیکربندی‌شده در ارائه‌دهنده پراکسی با نشانی اینترنتی مورد استفاده مرورگر مطابقت ندارد؛ معمولاً http در برابر https. کوکی نشست برای یک مبدأ صادر می‌شود و در مبدأ دیگری خوانده می‌شود؛ بنابراین Authentik هر بار درخواست را ناشناس تشخیص می‌دهد. میزبان خارجی را اصلاح کنید، سپس پیش از آزمایش دوباره، کوکی‌های هر دو نام میزبان را پاک کنید.

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

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