Authentik کو Docker Compose پر self-hosted SSO بنائیں

آپ کی میزبان کردہ ہر ایپ کے لیے ایک ہی login

Authentik ایک self-hosted SSO (single sign-on) سرور ہے: آپ کے صارفین ایک بار sign in کرتے ہیں، اور اس کے پیچھے موجود ہر ایپ اپنا الگ password مانگنے کے بجائے اسی session کو قبول کرتی ہے۔ تنصیب کے لیے official Docker Compose file اور دو generated secrets درکار ہیں۔ اصل توجہ اس کے بعد درکار ہوتی ہے: reverse proxy کو اس کی طرف point کرنا اور ایک موجودہ ایپ کو forward auth کے پیچھے رکھنا۔

Authentik اس Compose file میں تین services کے طور پر چلتا ہے: PostgreSQL database، ایک server process، اور ایک worker process۔ Server container میں embedded outpost بھی چلتا ہے۔ یہی component ہر protected app کے لیے یہ جواب دیتا ہے کہ "کیا یہ request sign in ہے؟" Version 2026.8.5، 25 October 2026 تک، موجودہ release ہے۔ یہ 21 October 2026 کو 2026.8 series کے latest patch کے طور پر شائع ہوا۔ اس series کا آغاز 18 August کو 2026.8.0 سے ہوا تھا، اور official Compose file میں default image tag کے طور پر اس نے 14 October کے 2026.8.4 کی جگہ لی ہے۔ Project ایسے host کا تقاضا کرتا ہے جس میں کم از کم 2 CPU cores اور 2 GB RAM ہو۔ اسے کم از کم حد سمجھیں۔ ایک دن چلنے کے بعد PostgreSQL اور worker دونوں memory استعمال کرتے رہتے ہیں۔

شروع کرنے سے پہلے درکار چیزیں

آپ کو Docker Engine کے ساتھ Compose v2 plugin درکار ہے۔ اس کی تصدیق docker compose version سے کریں۔ اگر version کے بجائے error ظاہر ہو تو آگے بڑھنے سے پہلے plugin install کریں۔ بنیادی طریقہ VPS پر Docker Compose کے ساتھ ایپس چلانا میں بیان کیا گیا ہے۔ آپ کو سرور کی طرف اشارہ کرنے والا DNS A record بھی درکار ہے۔ ذیل کی مثالوں میں یہ auth.example.com ہے، کیونکہ Authentik اپنے redirect URLs اس hostname کی بنیاد پر بناتا ہے جسے browser نے استعمال کیا ہو۔

Stack کو root کے بجائے docker group کے عام user کے طور پر چلائیں۔ اس group کی membership host پر root کے برابر اختیار دیتی ہے، اس لیے یہ اختیار صرف ایک deploy account کو دیں، کسی اور کو نہیں۔ یہ طریقہ VPS پر کم سے کم اختیارات والے user accounts کے اصول کے مطابق ہے۔

Official Compose file کے ساتھ تنصیب

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 میں تین containers دکھائی دینے چاہییں، اور سب up ہونے چاہییں۔ Check کامیاب ہونے کے بعد postgresql کو healthy report کرنا چاہیے۔ پہلی start پر database migrations چلتی ہیں، اس لیے web interface کے جواب دینے سے پہلے ایک منٹ انتظار کریں۔

دونوں generated values مختلف وجوہات کی بنا پر اہم ہیں۔ PG_PASS PostgreSQL password ہے۔ Authentik کی install docs کے مطابق 99 characters سے زیادہ لمبے passwords supported نہیں ہیں، اس لیے خود منتخب کیا گیا کوئی بھی password اس حد سے کم رکھیں؛ generated password اس سے کہیں چھوٹا ہوتا ہے۔ AUTHENTIK_SECRET_KEY وہ key ہے جسے Authentik cookies sign کرنے کے لیے استعمال کرتا ہے۔ اس کی configuration docs کے مطابق اسے تبدیل کرنے سے active sessions invalid ہو جاتے ہیں، اس لیے بعد میں نئی key بنانے سے ہر signed-in user logout ہو جاتا ہے۔ .env کو mode 600 پر رکھیں اور اس کی ایک copy backups کے ساتھ محفوظ جگہ پر رکھیں، تاکہ restore کے بعد server وہی key استعمال کرے جس کے ساتھ وہ چل رہا تھا۔

Compose file دونوں values کو ${VAR:?message} form کے ذریعے required قرار دیتی ہے: PostgreSQL service پر ${PG_PASS:?database password required} اور server اور worker پر ${AUTHENTIK_SECRET_KEY:?secret key required}۔ اس کا مطلب ہے کہ file موجود نہ ہونے پر Compose start ہونے سے انکار کر دیتا ہے۔ غلط directory سے docker compose up -d چلانے پر required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required جیسی line دکھائی دیتی ہے اور command رک جاتی ہے۔ یہ message path کا مسئلہ بتاتا ہے، config کا نہیں۔

اہم environment values

باقی تمام values اسی .env file میں شامل ہوں گی۔ Authentik double underscore کو nested configuration key میں map کرتا ہے، اس لیے AUTHENTIK_EMAIL__HOST، email.host set کرتا ہے۔ Single underscore nested key میں map نہیں ہوتا۔ یہی وہ عام وجہ ہے جس کے باعث کوئی setting مؤثر دکھائی نہیں دیتی۔

• AUTHENTIK_BOOTSTRAP_PASSWORD پہلی بار start ہونے پر built-in akadmin user کا password set کرتا ہے، اس لیے آپ کو اسے public web form میں کبھی درج نہیں کرنا پڑتا۔ AUTHENTIK_BOOTSTRAP_EMAIL اور AUTHENTIK_BOOTSTRAP_TOKEN اسی طرح اس user کا address اور API token set کرتے ہیں۔
• COMPOSE_PORT_HTTP اور COMPOSE_PORT_HTTPS published ports کو default ports 9000 اور 9443 سے تبدیل کرتے ہیں۔
• AUTHENTIK_EMAIL__HOST، AUTHENTIK_EMAIL__PORT، AUTHENTIK_EMAIL__USERNAME، AUTHENTIK_EMAIL__PASSWORD، AUTHENTIK_EMAIL__USE_TLS اور AUTHENTIK_EMAIL__FROM outbound mail configure کرتے ہیں۔ ان کے بغیر Authentik port 25 پر localhost سے رابطہ کرنے کی کوشش کرتا ہے، اس لیے password-reset mails کے نتیجے میں worker log میں connection error آتا ہے۔
• AUTHENTIK_LOG_LEVEL=debug اس detail level کو فعال کرتا ہے جس کی آپ کو login flow میں خرابی کے دوران ضرورت ہوتی ہے۔ اس کے بعد اسے واپس info پر set کریں۔
• AUTHENTIK_ERROR_REPORTING__ENABLED default طور پر false ہے۔ اسے صرف true پر set کریں اگر آپ crash reports upstream بھیجنے پر رضامند ہوں۔

یہ secrets ایک plain file میں موجود ہیں، اس لیے directory کے ساتھ اسی طرح برتاؤ کریں جیسے کسی دوسرے credential store کے ساتھ کرتے ہیں۔ self-hosted Vaultwarden instance جیسا password manager، recovery copy رکھنے کے لیے آپ کے laptop پر موجود note سے بہتر جگہ ہے۔

پہلا login اور admin account

Browser میں http://SERVER_IP:9000 کھولیں۔ Authentik initial setup flow دکھاتا ہے اور default akadmin user کے لیے password مقرر کرنے کو کہتا ہے۔ اگر آپ پہلے ہی AUTHENTIK_BOOTSTRAP_PASSWORD مقرر کر چکے ہیں تو یہ مرحلہ مکمل ہو چکا ہے اور آپ براہ راست login page پر پہنچیں گے۔

Directory اور پھر Users کے تحت اپنے لیے ایک عام admin user بنائیں، اسے authentik Admins group میں شامل کریں، اور اس account سے sign in کریں۔ akadmin کو break-glass account کے طور پر رکھیں اور اس کا طویل password offline محفوظ کریں۔ اگر کبھی کسی خراب flow یا stage کی وجہ سے آپ lock out ہو جائیں تو docker compose run --rm server create_recovery_key 10 akadmin، جسے /opt/authentik سے چلایا جائے، ایک ایسا link print کرتا ہے جو آپ کو براہ راست akadmin کے طور پر sign in کرتا ہے۔ جس شخص کے پاس یہ link ہو اسے بھی یہی access حاصل ہوگا، اس لیے اسے password کی طرح محفوظ رکھیں۔ روزمرہ کام کے لیے shared built-in account استعمال کرنے سے audit log ناقابلِ اعتماد ہو جاتا ہے، کیونکہ ہر event میں akadmin لکھا ہوتا ہے اور یہ معلوم نہیں ہوتا کہ کون تھا۔ یہی بات Authentik کے بعد والے حصے پر بھی لاگو ہوتی ہے: مثلاً ایک self-hosted OneCLI harness جو ہر شخص کو اپنا agent دیتا ہے تب ہی قابلِ فہم trail چھوڑتا ہے جب اس تک پہنچنے والی identity کسی ایک انسان سے متعلق ہو، نہ کہ ایسی login سے جسے پوری team share کرتی ہو۔

اپنے reverse proxy کے پیچھے Authentik رکھیں

Port 9000 کو internet پر publish کرنا کام کرتا ہے، لیکن آپ کو TLS (transport layer security) اور ایک حقیقی hostname چاہیے۔ اگر آپ پہلے ہی متعدد Compose ایپس کے لیے Traefik کو reverse proxy کے طور پر استعمال کرنا والا setup چلا رہے ہیں تو override file کے ذریعے Authentik کو اسی external proxy network سے منسلک کریں۔ docker-compose.override.yml کو compose.yml کے ساتھ والی directory میں بنائیں:

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 کے ذریعے apply کریں۔ Compose override کو خودکار طور پر merge کرتا ہے، اس لیے server service official file کی تمام settings برقرار رکھتی ہے اور labels بھی حاصل کرتی ہے۔ curl -I https://auth.example.com/if/user/ کے ذریعے جانچ کریں؛ اسے HTTP/2 200 کا جواب دینا چاہیے۔ Traefik کی طرف سے 404 page not found کا مطلب ہے کہ کسی router نے request match نہیں کی۔ تصدیق کریں کہ labels container تک پہنچ گئے ہیں، Host() rule hostname سے عین match کرتا ہے، اور request اس HTTPS entry point پر پہنچی ہے جس پر router listen کر رہا ہے۔

Hostname کام کرنے لگے تو override میں published ports کو 127.0.0.1 سے bind کریں، تاکہ اندر آنے کا واحد راستہ proxy کے ذریعے ہو۔

ایک ایپ کو forward auth سے محفوظ بنائیں

Authentik کے proxy provider میں تین modes ہوتے ہیں، اور غلط mode منتخب کرنے سے ایک گھنٹہ ضائع ہو سکتا ہے۔ Proxy کا مطلب ہے کہ outpost خود traffic کو upstream app تک forward کرتا ہے۔ Forward auth (single application) کا مطلب ہے کہ آپ کا اپنا reverse proxy traffic منتقل کرتا رہتا ہے اور صرف Authentik سے پوچھتا ہے کہ request پر sign in ہے یا نہیں۔ Forward auth (domain level) ایک ہی parent domain کے تحت تمام ایپس کو ایک provider سے محفوظ بناتا ہے، لیکن ہر ایپ کے لیے authorization rules کی سہولت محدود ہو جاتی ہے۔ اگر سامنے Traefik ہو تو آپ کو forward auth (single application) استعمال کرنا چاہیے۔ اگر آپ عملی مشق کے لیے کوئی مخصوص ایپ چاہتے ہیں تو self-hosted AFFiNE workspace اچھا پہلا انتخاب ہے، کیونکہ یہ ایسی internal tool ہے جسے آپ اپنے devices سے قابل رسائی رکھنا چاہتے ہیں، کسی اور جگہ سے نہیں۔ ٹیم کی tool کے لیے یہ صورت مزید واضح ہو جاتی ہے: self-hosted Chatwoot support desk کو اسی provider کے پیچھے رکھیں، تاکہ inbox کے جواب دینے والا ہر شخص دن میں ایک بار sign in کرے، بجائے اس کے کہ ایک اور password سب کے ساتھ share کیا جائے۔

Web interface میں Applications کھولیں، پھر Providers کھولیں، ایک Proxy Provider بنائیں، forward auth single application mode منتخب کریں، اور external host کو https://app.example.com پر set کریں۔ ایک Application بنائیں جو اس provider کی طرف point کرے۔ پھر Outposts کھولیں، authentik Embedded Outpost کو edit کریں، اور نئی application کو اس کی selected applications میں منتقل کریں۔ outpost صرف انہی applications کے لیے جواب دیتا ہے جو اسے دی گئی ہوں۔ اس لیے آخری step چھوڑنے سے درست طور پر configured provider بھی کوئی response نہیں دیتا۔

Middleware صرف ایک بار، Authentik container پر define کریں، اور ہر protected app سے اس کا reference دیں:

      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 ان headers کی فہرست ہے جنہیں Traefik Authentik کے response سے copy کرکے upstream کو بھیجی جانے والی request میں شامل کرتا ہے۔ اسے omit کرنے پر app محفوظ تو رہتی ہے، لیکن اسے user کی شناخت معلوم نہیں ہوتی۔ اس لیے جو بھی چیز automatic login کے لیے X-authentik-username پڑھتی ہے، وہ signed out رہتی ہے۔ یہ مسئلہ خاص طور پر اس app کے سامنے نمایاں ہوتا ہے جس کا اپنا sign-in بھی ہو، مثلاً self-hosted openGym workout tracker اور اس کا passkey login۔ یہاں headers ایک ہی page کے لیے ایک prompt اور دو prompts کے درمیان فرق پیدا کرتے ہیں۔

Protected app کے لیے ایک نہیں بلکہ دو routers درکار ہوتے ہیں:

    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 وہ حصہ ہے جسے سب چھوڑ دیتے ہیں۔ Sign-in کے بعد Authentik browser کو /outpost.goauthentik.io/ کے تحت موجود path پر app کے hostname کے ذریعے واپس بھیجتا ہے، auth.example.com پر نہیں۔ اگر کوئی router اس path prefix کو Authentik service کی طرف نہ بھیجے تو request آپ کی app تک پہنچتی ہے، app 404 جواب دیتی ہے، اور login مکمل نہیں ہوتا۔ زیادہ priority کی وجہ سے مخصوص path rule اسی domain پر موجود سادہ Host() rule پر ترجیح حاصل کرتا ہے۔

Private browser window میں test کریں۔ آپ کو auth.example.com پر بھیجا جانا چاہیے، sign in کرنا چاہیے، اور پھر app پر واپس آنا چاہیے۔ Authentik side پر docker compose logs -f server ہر کوشش کے لیے authorization event دکھاتا ہے۔ اس سے معلوم ہوتا ہے کہ request Authentik تک پہنچی بھی تھی یا نہیں۔

حقیقت میں پیش آنے والی ناکامیاں

ایپ اور login page کے درمیان endless redirect loop۔ Provider پر external host، browser کے استعمال کردہ host سے مطابقت نہیں رکھتا۔ عموماً provider میں http:// اور address bar میں https:// ہوتا ہے۔ اس کے بعد session cookie مختلف origin کے لیے set ہوتی ہے، اس لیے ہر واپسی نئی anonymous request معلوم ہوتی ہے۔ External host درست کریں اور دوبارہ test کرنے سے پہلے دونوں domains کی cookies clear کریں۔

/outpost.goauthentik.io/start پر 404۔ Outpost router موجود نہیں، یا اس کی priority اسی host کے catch-all router سے کم ہے۔

ایپ load ہو جاتی ہے لیکن login کے لیے کبھی نہیں پوچھتی۔ middlewares label ایسے middleware کا نام بتاتا ہے جو موجود نہیں۔ Traefik اس بارے میں warning نہیں دیتا، اس لیے authentik@docker میں typo ہونے کا مطلب صرف یہ ہے کہ کوئی middleware run نہیں ہوتا۔ Traefik dashboard کھولیں اور تصدیق کریں کہ router میں middleware درج ہے۔

کامیاب login کے بعد Authentik سے 403۔ User authenticated ہے لیکن authorized نہیں۔ Application کے ساتھ ایسی policy binding یا group requirement منسلک ہے جسے یہ user پورا نہیں کرتا۔ Admin interface میں Events log اس policy کا نام دکھاتا ہے جس نے access deny کیا۔

جب Keycloak بہتر انتخاب ہے

Keycloak ایک پرانا project ہے جسے Red Hat کی پشت پناہی حاصل ہے۔ یہ روایتی enterprise identity کام کے لیے زیادہ مضبوط انتخاب ہے، خاص طور پر وسیع SAML federation، بیک وقت کئی بیرونی identity providers سے login بروکر کرنے، اور documented migration path کے طور پر realm export اور import کے لیے۔ کچھ organisations کے لیے اس کے پیچھے موجود commercial support کاغذی طور پر اہم ہوتی ہے۔ اس کے بدلے میں Keycloak کا اپنا proxy نہیں ہے۔ اس لیے ایسی app کو محفوظ بنانے کے لیے جو OIDC (OpenID Connect) یا SAML میں سے کسی کو بھی استعمال نہیں کرتی، اس کے ساتھ oauth2-proxy جیسی چیز چلانی پڑتی ہے۔ Authentik کا built-in proxy provider یہی کام پہلے سے integrated طریقے سے کرتا ہے۔ اسی لیے مختلف نوعیت کی apps چلانے والے زیادہ تر self-hosters بالآخر Authentik اختیار کرتے ہیں۔

Backups اور upgrades

Restore کو ممکن بنانے والی تین چیزیں یہ ہیں: PostgreSQL database، ./data directory، اور .env۔

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

اس dump اور .env کو ایک ساتھ محفوظ کریں۔ Dump میں AUTHENTIK_SECRET_KEY کی copy شامل نہیں ہوتی، اور مختلف key کے تحت restore کرنے سے ہر active session invalid ہو جاتا ہے۔ اس لیے اصل key محفوظ رکھنے سے restored server اسی حالت میں چلتا رہتا ہے۔

Upgrades کے لیے tag تبدیل کیا جاتا ہے۔ .env میں AUTHENTIK_TAG کو مطلوبہ release پر set کریں، پھر docker compose pull اور اس کے بعد docker compose up -d چلائیں۔ اگر آپ نے AUTHENTIK_TAG کبھی set نہ کیا ہو تو version خود compose.yml میں درج default سے آتا ہے۔ اس صورت میں اس file کی نئی copy download کرنا upgrade کے لیے کافی ہے، اور official upgrade docs میں یہی طریقہ بیان کیا گیا ہے۔ پہلے release notes پڑھیں۔ Authentik date-based versions استعمال کرتا ہے، اور October 2026 تک اس کی docs کے مطابق upgrades کو major releases کی sequence پر عمل کرنا چاہیے: پہلے اس series کے latest patch پر جائیں جسے آپ چلا رہے ہیں، پھر ہر بعد والی series سے ترتیب کے ساتھ گزریں اور کوئی series skip نہ کریں۔ Authentik downgrading support نہیں کرتا، اس لیے pull سے پہلے database dump لیں، بعد میں نہیں۔

FAQ

کیا Authentik کو self-host کرنے کے لیے مفت ہے؟

اوپن سورس edition مفت ہے اور اوپر بیان کردہ تمام سہولتیں فراہم کرتی ہے: proxy provider، forward auth، OIDC (OpenID Connect)، SAML، اور flows engine۔ paid enterprise tier میں support اور کچھ enterprise features شامل ہیں، لیکن یہاں بیان کردہ کسی چیز کے لیے licence درکار نہیں۔

کیا Authentik استعمال کرنے کے لیے Traefik ضروری ہے؟

نہیں۔ forward auth، auth_request کے ذریعے nginx کے ساتھ اور forward_auth کے ذریعے Caddy کے ساتھ کام کرتا ہے۔ ہر صورت میں طریقہ ایک جیسا ہے: reverse proxy ہر request کے بارے میں Authentik سے پوچھتا ہے، اور protected hostname پر موجود path prefix /outpost.goauthentik.io/ کو ایپ کے بجائے Authentik کی طرف route ہونا چاہیے۔

میری protected ایپ login اور error کے درمیان مسلسل کیوں گھومتی رہتی ہے؟

proxy provider پر configured external host، browser کے استعمال کردہ URL سے مطابقت نہیں رکھتا۔ عموماً مسئلہ http اور https کے درمیان فرق کا ہوتا ہے۔ session cookie ایک origin کے لیے جاری ہوتی ہے اور دوسرے origin پر پڑھی جاتی ہے، اس لیے Authentik کو ہر بار anonymous request نظر آتی ہے۔ external host درست کریں، پھر دوبارہ test کرنے سے پہلے دونوں hostnames کی cookies صاف کریں۔

Authentik کو کتنی RAM درکار ہے؟

October 2026 تک documented minimum 2 CPU cores اور 2 GB RAM ہے۔ اس میں PostgreSQL، server اور worker تینوں شامل ہیں۔ 2 GB کے server پر memory pressure kernel کے OOM killer کو فعال کر سکتا ہے۔ OOM killer اس process کو ختم کرتا ہے جس کا badness score سب سے زیادہ ہو۔ یہ score تقریباً استعمال شدہ allowed memory کے حصے اور اس کے oom_score_adj پر مبنی ہوتا ہے۔ اگر یہ process worker ہو تو علامت یہ ہوتی ہے کہ background tasks اور outbound email رک جاتے ہیں، جبکہ login page کام کرتی رہتی ہے۔ اگر یہی server protected ایپس بھی چلا رہا ہو تو اسے 4 GB RAM دیں۔