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

ہر hosted ایپ کے لیے ایک login

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

Authentik اس Compose file میں تین services کے طور پر چلتا ہے: PostgreSQL database، ایک server process، اور ایک worker process۔ Server container میں embedded outpost بھی چلتا ہے۔ یہی component ہر protected ایپ کے لیے یہ جانچتا ہے کہ "کیا یہ request signed in ہے؟" Version 2026.5 جولائی 2026 تک موجودہ release ہے، اور project کے مطابق host میں کم از کم 2 CPU cores اور 2 GB RAM ہونی چاہیے۔ اسے کم از کم ضرورت سمجھیں۔ Server ایک دن چلنے کے بعد 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 کے اصول کے مطابق ہے۔

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

دونوں generated values مختلف وجوہات کی بنا پر اہم ہیں۔ PG_PASS PostgreSQL password ہے، اور اس کی زیادہ سے زیادہ حد 99 characters ہے۔ AUTHENTIK_SECRET_KEY sessions اور tokens پر دستخط کرتا ہے، اس لیے اسے بعد میں تبدیل کرنے سے ہر user logout ہو جاتا ہے اور جاری کیے گئے تمام API tokens غیر مؤثر ہو جاتے ہیں۔ .env کو mode 600 پر رکھیں اور اس کی ایک copy محفوظ جگہ پر رکھیں، کیونکہ matching secret key کے بغیر restore کیا گیا database ایسا database ہے جس میں کوئی login نہیں کر سکتا۔

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

اہم environment values

باقی تمام values اسی .env فائل میں شامل کی جاتی ہیں۔ Authentik double underscore کو nested configuration key میں تبدیل کرتا ہے، اس لیے AUTHENTIK_EMAIL__HOST، email.host کو set کرتا ہے۔ single underscore کو بغیر کسی warning کے نظرانداز کر دیا جاتا ہے۔ یہی وہ عام ترین وجہ ہے جس کی بنا پر کوئی setting غیر مؤثر دکھائی دیتی ہے۔

• AUTHENTIK_BOOTSTRAP_PASSWORD پہلے start پر built-in akadmin user کا password set کرتا ہے، اس لیے آپ کو یہ password 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 فعال کرتا ہے جب login flow درست طور پر کام نہ کر رہا ہو۔ بعد میں اسے info پر واپس set کریں۔
• AUTHENTIK_ERROR_REPORTING__ENABLED default طور پر false ہوتا ہے۔ اسے صرف true پر set کریں اگر آپ crash reports upstream بھیجنے پر رضامند ہوں۔

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

پہلا لاگ اِن اور منتظم اکاؤنٹ

براؤزر میں http://SERVER_IP:9000 کھولیں۔ Authentik ابتدائی سیٹ اپ کا عمل دکھاتا ہے اور آپ سے پہلے سے موجود akadmin صارف کے لیے پاس ورڈ مقرر کرنے کو کہتا ہے۔ اگر آپ AUTHENTIK_BOOTSTRAP_PASSWORD پہلے ہی مقرر کر چکے ہیں تو یہ مرحلہ مکمل ہے، اور آپ براہِ راست لاگ اِن صفحے پر پہنچ جائیں گے۔

Directory اور پھر Users کے تحت اپنے لیے ایک عام منتظم صارف بنائیں، اسے authentik Admins گروپ میں شامل کریں، اور اسی اکاؤنٹ سے سائن اِن کریں۔ akadmin کو ہنگامی استعمال کے اکاؤنٹ کے طور پر برقرار رکھیں اور اس کا طویل پاس ورڈ offline محفوظ رکھیں۔ روزمرہ کا کام مشترکہ built-in اکاؤنٹ سے کرنے پر audit log ناقابلِ اعتماد ہو جاتا ہے، کیونکہ ہر event میں akadmin لکھا ہوتا ہے اور یہ معلوم نہیں ہوتا کہ کارروائی کس نے کی۔ یہی اصول Authentik کے بعد آنے والے نظاموں پر بھی لاگو ہوتا ہے: مثال کے طور پر self-hosted OneCLI harness جو ہر شخص کو اپنا agent فراہم کرتا ہے قابلِ فہم ریکارڈ صرف اسی وقت چھوڑتا ہے جب وہاں پہنچنے والی identity ایک فرد سے وابستہ ہو، نہ کہ ایسے login سے جسے پوری ٹیم مشترکہ طور پر استعمال کرتی ہو۔

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

Internet پر port 9000 شائع کرنا کام کرتا ہے، لیکن آپ کو 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 کے ذریعے نافذ کریں۔ 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 کا مطلب ہے کہ container، proxy network پر موجود نہیں، اور Traefik ایسے container تک traffic route نہیں کر سکتا جس تک وہ پہنچ نہیں سکتا۔

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

فارورڈ auth کے ذریعے ایک ایپ محفوظ کریں

Authentik کے proxy provider میں 3 modes ہوتے ہیں، اور غلط mode منتخب کرنے سے ایک گھنٹہ ضائع ہو سکتا ہے۔ Proxy کا مطلب ہے کہ outpost خود upstream ایپ کو traffic بھیجتا ہے۔ Forward auth (single application) کا مطلب ہے کہ آپ کا اپنا reverse proxy traffic آگے بھیجتا رہتا ہے اور صرف Authentik سے پوچھتا ہے کہ request کے ذریعے sign in کیا گیا ہے یا نہیں۔ Forward auth (domain level) ایک ہی parent domain کے تحت تمام ایپس کو ایک provider سے محفوظ کرتا ہے، لیکن اس کے لیے ہر ایپ کی authorization rules الگ سے manage نہیں کی جا سکتیں۔ اگر سامنے 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 بھی کوئی جواب نہیں دیتا۔

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

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

Private browser window میں test کریں۔ آپ کو auth.example.com پر بھیجا جانا چاہیے، وہاں sign in کریں، اور پھر app پر واپس آئیں۔ Authentik کی جانب 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 requests کو broker کرنا، اور documented migration path کے طور پر realm export اور import شامل ہیں۔ کچھ organisations کے لیے دستیاب commercial support بھی اہم ہوتا ہے، کم از کم دستاویزات میں۔ اس کے بدلے میں Keycloak کا اپنا proxy نہیں ہے۔ اس لیے ایسے app کو محفوظ بنانے کے لیے جو OIDC (OpenID Connect) استعمال نہیں کرتی، اس کے ساتھ oauth2-proxy جیسا tool چلانا پڑتا ہے۔ Authentik کا built-in proxy provider یہی کام پہلے سے integrated صورت میں فراہم کرتا ہے۔ اسی وجہ سے مختلف قسم کے apps چلانے والے زیادہ تر self-hosters بالآخر Authentik کا انتخاب کرتے ہیں۔

بیک اپ اور اپ گریڈ

بحالی کے لیے تین چیزیں ضروری ہیں: 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 کافی نہیں، کیونکہ session اور token data کو محفوظ رکھنے والی secret key .env میں موجود ہوتی ہے۔

اپ گریڈ tag تبدیل کرنے کے برابر ہے۔ .env میں AUTHENTIK_TAG کو اپنی مطلوبہ release پر set کریں، پھر docker compose pull کے بعد docker compose up -d چلائیں۔ پہلے release notes پڑھیں، کیونکہ Authentik تاریخ پر مبنی versions استعمال کرتا ہے اور بعض releases میں ایسی migrations شامل ہوتی ہیں جن کے لیے پچھلی release سے upgrade کرنا ضروری ہوتا ہے۔ pull سے پہلے database dump لیں، بعد میں نہیں۔

FAQ

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

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

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

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

میری protected app login اور error کے درمیان مسلسل redirect کیوں ہو رہی ہے؟

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

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

July 2026 تک documented minimum 2 CPU cores اور 2 GB RAM ہے۔ اس میں PostgreSQL، server اور worker تینوں شامل ہیں۔ 2 GB کے server پر memory pressure کی صورت میں kernel سب سے پہلے worker process کو kill کرتا ہے۔ اس کی علامت یہ ہے کہ login page کام کرتی رہتی ہے، لیکن background tasks اور outbound email رک جاتے ہیں۔ اگر اسی server پر protected apps بھی چل رہی ہوں تو 4 GB RAM دیں۔