Authentik Docker Compose ile SSO Kurulumu Rehberi

Barındırdığınız her uygulama için tek bir oturum açma

Authentik, self-hosted bir SSO (tek oturum açma) sunucusudur: kullanıcılarınız bir kez oturum açar ve arkasındaki her uygulama, kendi şifresini sormak yerine bu oturumu kabul eder. Kurulum, resmi bir Docker Compose dosyası ve oluşturulan iki gizli anahtar (secret) ile gerçekleştirilir. Asıl dikkat gerektiren kısım ise kurulum sonrasıdır: bir reverse proxy'yi bu sunucuya yönlendirmek ve mevcut bir uygulamayı forward auth arkasına almak.

Authentik, Compose dosyasında üç servis olarak sunulur: bir PostgreSQL veritabanı, bir server süreci ve bir worker süreci. Sunucu container'ı ayrıca, korunan her uygulama için "bu istek oturum açmış mı?" sorusunu yanıtlayan bileşen olan gömülü outpost'u da çalıştırır. Temmuz 2026 itibarıyla güncel sürüm 2026.5'tir ve proje, en az 2 CPU çekirdeği ve 2 GB RAM'e sahip bir sunucu gerektirmektedir. Bu değerleri minimum gereksinim olarak kabul edin. Sunucu bir gün boyunca açık kaldığında, PostgreSQL ve worker süreçleri bellek kullanımını sabitler.

Başlamadan önce gerekenler

Docker Engine ve Compose v2 eklentisinin kurulu olması gerekir; bunu docker compose version komutu ile doğrulayabilirsiniz. Eğer bu komut bir sürüm bilgisi yerine hata döndürürse, devam etmeden önce eklentiyi kurun; temel bilgiler Docker Compose ile VPS üzerinde uygulama çalıştırma rehberinde yer almaktadır. Ayrıca sunucunuza işaret eden bir DNS A kaydına ihtiyacınız vardır; aşağıdaki örneklerde auth.example.com olarak geçmektedir. Authentik, yönlendirme URL'lerini tarayıcının kullandığı ana makine adına göre oluşturduğu için bu gereklidir.

Stack'i root yerine docker grubundaki sıradan bir kullanıcı olarak çalıştırın. Bu gruba üyelik, ana makine üzerinde root yetkilerine eşdeğerdir; bu nedenle bu yetkiyi yalnızca bir dağıtım hesabına verin ve VPS üzerinde en az yetkili kullanıcı hesapları rehberinde belirtildiği gibi başka kimseye tanımlamayın.

Resmi Compose dosyası ile kurulum

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 komutu üç container listelemeli; postgresql, healthy durumunu, server ve worker ise running durumunu bildirmelidir. İlk başlatma sırasında veritabanı migrasyonları çalıştırılır, bu nedenle web arayüzünün yanıt vermesi için bir dakika bekleyin.

Oluşturulan her iki değer de farklı nedenlerle önem taşır. PG_PASS, PostgreSQL parolasıdır ve 99 karakterlik bir üst sınırı vardır. AUTHENTIK_SECRET_KEY, oturumları ve token'ları imzalar; bu nedenle daha sonra değiştirilmesi tüm kullanıcıların oturumunu kapatır ve yayınladığınız tüm API token'larını geçersiz kılar. .env dosyasını 600 modunda tutun ve güvenli bir yerde yedeğini saklayın; çünkü eşleşen gizli anahtarı olmadan geri yüklenen bir veritabanına hiç kimse giriş yapamaz.

Compose dosyası her iki değeri de ${PG_PASS:?database password required} biçimiyle okur; bu, dosya eksik olduğunda Compose'un başlatmayı reddedeceği anlamına gelir. docker compose up -d komutunu yanlış dizinden çalıştırmak required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required çıktısını verir ve işlemi durdurur. Bu mesaj bir yapılandırma sorunu değil, bir yol (path) sorunudur.

Önemli ortam değişkenleri

Diğer tüm ayarlar aynı .env dosyasında yer alır. Authentik, iç içe geçmiş bir yapılandırma anahtarı oluşturmak için çift alt çizgi kullanır; bu nedenle AUTHENTIK_EMAIL__HOST, email.host değerini ayarlar. Tek alt çizgi herhangi bir uyarı vermeden göz ardı edilir; bu durum, bir ayarın hiçbir işe yaramıyor gibi görünmesinin en yaygın nedenidir.

• AUTHENTIK_BOOTSTRAP_PASSWORD, ilk başlatma sırasında yerleşik akadmin kullanıcısının parolasını ayarlar; böylece parolayı herkese açık bir web formuna girmeniz gerekmez. AUTHENTIK_BOOTSTRAP_EMAIL ve AUTHENTIK_BOOTSTRAP_TOKEN, aynı yöntemle bu kullanıcının e-posta adresini ve bir API anahtarını belirler.
• COMPOSE_PORT_HTTP ve COMPOSE_PORT_HTTPS, yayınlanan portları varsayılan 9000 ve 9443 değerlerinden farklı bir noktaya taşır.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS ve AUTHENTIK_EMAIL__FROM giden posta ayarlarını yapılandırır. Bu ayarlar yapılmadığında Authentik, 25 numaralı port üzerinden localhost kullanmaya çalışır; bu da parola sıfırlama e-postalarının worker günlüğünde bağlantı hatası olarak sonuçlanmasına neden olur.
• AUTHENTIK_LOG_LEVEL=debug, bir giriş akışında sorun yaşandığında ihtiyaç duyduğunuz ayrıntılı kayıtları etkinleştirir. İşlem bittikten sonra tekrar info değerine getirin.
• AUTHENTIK_ERROR_REPORTING__ENABLED varsayılan olarak false değerindedir. Yalnızca hata raporlarını geliştiriciye göndermeyi kabul ediyorsanız true olarak ayarlayın.

Bunlar düz bir dosya içindeki gizli verilerdir; bu nedenle ilgili dizine diğer tüm kimlik bilgisi depolarına gösterdiğiniz özeni gösterin. Kurtarma kopyası için dizüstü bilgisayarınızdaki bir not yerine, self-hosted Vaultwarden instance gibi bir parola yöneticisi çok daha güvenli bir tercihtir.

İlk giriş ve yönetici hesabı

Tarayıcınızda http://SERVER_IP:9000 adresini açın. Authentik, ilk kurulum akışını gösterir ve varsayılan akadmin kullanıcısı için bir parola belirlemenizi ister. Eğer AUTHENTIK_BOOTSTRAP_PASSWORD değerini zaten ayarladıysanız, bu adım tamamlanmıştır ve doğrudan giriş sayfasına yönlendirilirsiniz.

Directory, ardından Users altında kendiniz için normal bir yönetici hesabı oluşturun, bu hesabı authentik Admins grubuna ekleyin ve bu hesapla oturum açın. akadmin hesabını, uzun parolasını çevrimdışı olarak saklayacağınız bir break-glass hesabı olarak bırakın. Günlük işleri yerleşik ve ortak bir hesapla yürütmek denetim günlüğünü kullanılamaz hale getirir; çünkü her olayda akadmin görünür ve bunun arkasında kimin olduğu anlaşılmaz. Bu gerekçe Authentik sonrasında da geçerlidir: her kişiye kendi aracısını sağlayan self-hosted OneCLI altyapısı gibi bir yapı, yalnızca kendisine ulaşan kimlik tüm ekibin paylaştığı bir oturuma değil, tek bir kişiye ait olduğunda okunabilir bir iz bırakır.

Authentik'i reverse proxy arkasına alma

9000 numaralı portu internete açmak çalışır, ancak TLS (transport layer security) ve gerçek bir alan adı istersiniz. Eğer Traefik as a reverse proxy for multiple Compose apps rehberindeki kurulumu zaten çalıştırıyorsanız, bir override dosyası ile Authentik'i aynı harici proxy ağına dahil edin. compose.yml dosyasının yanına docker-compose.override.yml dosyasını oluşturun:

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

Bunu docker compose up -d ile uygulayın. Compose, override dosyasını otomatik olarak birleştirir; böylece server servisi resmi dosyadaki tüm ayarlarını korur ve etiketleri kazanır. HTTP/2 200 yanıtını vermesi gereken curl -I https://auth.example.com/if/user/ komutu ile kontrol edin. Traefik'ten gelen bir 404 page not found hatası, container'ın proxy ağında olmadığını ve Traefik'in ulaşamadığı bir container'a yönlendirme yapamayacağını gösterir.

Alan adı çalışmaya başladığında, yayınlanan portları override dosyasında 127.0.0.1 adresine bağlayın; böylece içeriye giden tek yol proxy üzerinden olur.

Bir uygulamayı forward auth ile koruma

Authentik proxy provider üç moda sahiptir ve yanlış modu seçmek bir saate mal olabilir. Proxy, trafiğin outpost tarafından upstream uygulamaya iletilmesi anlamına gelir. Forward auth (single application) modunda trafiği yine kendi reverse proxy'niz iletir; Authentik'e yalnızca isteğin oturum açmış bir kullanıcıdan gelip gelmediğini sorar. Forward auth (domain level) modu ise tek bir provider kullanarak bir üst alan adı altındaki tüm uygulamaları korur; bunun karşılığında uygulama bazında yetkilendirme kuralları uygulanamaz. Önünde Traefik kullanılıyorsa forward auth (single application) seçilmelidir. Üzerinde pratik yapmak için somut bir uygulama gerekiyorsa self-hosted AFFiNE çalışma alanı iyi bir ilk adaydır. Bu tür bir dahili araca kendi cihazlarınızdan erişilmesi, başka yerlerden ise erişilememesi istenir. Ekip tarafından kullanılan bir araçta bu yaklaşımın avantajı daha belirgin hale gelir: self-hosted Chatwoot destek masası aynı provider arkasına alınabilir. Böylece gelen kutusunu yanıtlayan herkes gün boyunca bir kez oturum açar ve ek bir parolayı ortak kullanmak gerekmez.

Web arayüzünde Applications ve ardından Providers menüsünü açın, bir Proxy Provider oluşturun, forward auth single application modunu seçin ve external host değerini https://app.example.com olarak ayarlayın. Bu sağlayıcıya işaret eden bir Application oluşturun. Ardından Outposts menüsünü açın, authentik Embedded Outpost öğesini düzenleyin ve yeni oluşturduğunuz uygulamayı seçili uygulamalar listesine ekleyin. Outpost yalnızca kendisine atanan uygulamalar için yanıt verir; bu yüzden son adımı atlamak, doğru yapılandırılmış bir sağlayıcının hiçbir sonuç döndürmemesine neden olur.

Middleware tanımını Authentik container'ı üzerinde bir kez yapın ve korunan her uygulamadan bu tanıma referans verin:

      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'in Authentik yanıtından alıp upstream'e gönderdiği isteğe eklediği başlıklar listesidir. Bu kısmı atlarsanız uygulama korunmaya devam eder ancak kullanıcının kim olduğunu öğrenemez; bu nedenle otomatik giriş için X-authentik-username değerini okuyan hiçbir sistem oturum açamaz.

Korunan uygulamanın kendisi için bir değil, iki router gerekir:

    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

İkinci router, herkesin gözden kaçırdığı kısımdır. Oturum açma işleminden sonra Authentik, tarayıcıyı auth.example.com üzerinde değil, uygulamanın kendi alan adı üzerindeki /outpost.goauthentik.io/ altındaki bir yola yönlendirir. Bu yol önekini Authentik servisine gönderen bir router olmazsa, istek doğrudan uygulamanıza ulaşır, uygulama 404 hatası verir ve giriş işlemi tamamlanamaz. Daha yüksek olan priority değeri, aynı alan adı üzerindeki düz Host() kuralına karşı spesifik yol kuralının öncelik kazanmasını sağlar.

Yapılandırmayı gizli bir tarayıcı penceresinde test edin. auth.example.com adresine yönlendirilmeli, oturum açmalı ve uygulamaya geri dönmelisiniz. Authentik tarafındaki docker compose logs -f server, her deneme için bir yetkilendirme olayı kaydeder; bu kayıtlar isteğin Authentik'e ulaşıp ulaşmadığını anlamanızı sağlar.

Karşılaşacağınız gerçek hatalar

Uygulama ile giriş sayfası arasında sonsuz yönlendirme döngüsü. Sağlayıcı üzerindeki harici ana makine (host), tarayıcının kullandığıyla eşleşmiyordur; genellikle sağlayıcıdaki http:// ile adres çubuğundaki https:// uyuşmazlığı yaşanır. Oturum çerezi farklı bir kaynak (origin) için ayarlandığından, her gidiş-dönüş yeni ve anonim bir istek gibi görünür. Harici ana makineyi düzeltin ve yeniden test etmeden önce her iki alan adı için de çerezleri temizleyin.

/outpost.goauthentik.io/start adresinde 404 hatası. Outpost yönlendiricisi eksiktir veya önceliği, ilgili ana makine için tanımlanan genel (catch-all) yönlendiriciden daha düşüktür.

Uygulama giriş sormadan yükleniyor. middlewares etiketi, mevcut olmayan bir ara yazılımı (middleware) işaret ediyordur. Traefik bu konuda uyarı vermez, bu nedenle authentik@docker içindeki bir yazım hatası, hiçbir ara yazılımın çalışmadığı anlamına gelir. Traefik panelini açın ve yönlendiricinin ilgili ara yazılımı listelediğini doğrulayın.

Başarılı bir girişten sonra Authentik üzerinden 403 hatası. Kullanıcının kimliği doğrulanmış ancak yetkilendirilmemiştir: uygulama, bu kullanıcının karşılamadığı bir ilke bağlamına (policy binding) veya grup gereksinimine sahiptir. Yönetim arayüzündeki Events günlüğü, erişimi reddeden ilkenin adını belirtir.

Keycloak ne zaman daha iyi bir tercihtir

Keycloak, Red Hat tarafından desteklenen daha eski bir projedir ve klasik kurumsal kimlik yönetimi işleri için daha güçlü bir seçenektir: yoğun SAML federasyonu, aynı anda birden fazla harici kimlik sağlayıcısından girişleri aracılama ve belgelenmiş bir geçiş yolu olarak realm dışa/içe aktarma işlemleri. Arkasındaki ticari destek, bazı kurumlar için kağıt üzerinde önem taşır. Bunun karşılığında Keycloak'un kendi proxy'si yoktur; bu nedenle OIDC (OpenID Connect) desteklemeyen bir uygulamayı korumak, yanında oauth2-proxy gibi bir araç çalıştırmak anlamına gelir. Authentik'in yerleşik proxy sağlayıcısı, halihazırda entegre edilmiş olan bu parçadır; karmaşık uygulama yığınlarına sahip çoğu self-host kullanıcısının bu aracı tercih etme sebebi de budur.

Yedekleme ve yükseltmeler

Bir geri yüklemenin mümkün olması için üç öğe gereklidir: PostgreSQL veritabanı, ./data dizini ve .env.

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

Bu dökümü ve .env dosyasını birlikte saklayın. Yalnızca veritabanı dökümü yeterli değildir; çünkü oturum ve token verilerini koruyan gizli anahtar .env içinde yer alır.

Yükseltmeler bir etiket değişikliğinden ibarettir. .env içindeki AUTHENTIK_TAG değerini istediğiniz sürüme ayarlayın, ardından docker compose pull ve sonrasında docker compose up -d komutlarını çalıştırın. Authentik tarih tabanlı sürümler kullandığı ve bazı sürümler bir önceki sürümden geçiş yapılmasını gerektiren migrasyonlar içerdiği için öncelikle sürüm notlarını okuyun. Veritabanı dökümünü pull işleminden sonra değil, önce alın.

FAQ

Authentik self-host için ücretsiz mi?

Açık kaynak sürümü ücretsizdir ve yukarıda bahsedilen tüm özellikleri kapsar: proxy sağlayıcısı, forward auth, OIDC (OpenID Connect), SAML ve akış motoru. Ücretli kurumsal sürüm destek ve bazı kurumsal özellikler ekler, ancak burada anlatılan hiçbir şey lisans gerektirmez.

Authentik kullanmak için Traefik gerekli mi?

Hayır. Forward auth, nginx ile auth_request üzerinden ve Caddy ile forward_auth üzerinden çalışır. Model her durumda aynıdır: reverse proxy her istek için Authentik'e danışır ve korunan ana bilgisayar adındaki /outpost.goauthentik.io/ yol ön eki, uygulamaya değil Authentik'e yönlendirilmelidir.

Korunan uygulamam neden sürekli giriş ekranı ile hata sayfası arasında gidip geliyor?

Proxy sağlayıcısında yapılandırılan dış ana bilgisayar, tarayıcının kullandığı URL ile eşleşmiyordur; bu durum genellikle http ile https arasındaki uyumsuzluktan kaynaklanır. Oturum çerezi bir kaynak için oluşturulup diğerinde okunduğundan, Authentik her seferinde anonim bir istek görür. Dış ana bilgisayarı düzeltin ve tekrar test etmeden önce her iki ana bilgisayar adı için de çerezleri temizleyin.

Authentik ne kadar RAM'e ihtiyaç duyar?

Temmuz 2026 itibarıyla belgelenen minimum gereksinim, PostgreSQL, sunucu ve worker süreçlerinin toplamı için 2 CPU çekirdeği ve 2 GB RAM'dir. 2 GB'lık bir sunucuda, bellek baskısı altında çekirdeğin sonlandırdığı ilk süreç worker olur; bu durumun belirtisi, giriş sayfası çalışmaya devam ederken arka plan görevlerinin ve giden e-postaların durmasıdır. Eğer aynı sunucuda koruduğunuz uygulamalar da çalışıyorsa, 4 GB RAM ayırmanız önerilir.