Authentik ile Uygulamalar için Self-Hosted SSO

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 değerden oluşur. Asıl dikkat gerektiren kısım ise sonrasıdır: bir reverse proxy'yi ona yönlendirmek ve mevcut bir uygulamayı forward auth arkasına almak.

Authentik, bu 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. 25 Ekim 2026 itibarıyla güncel sürüm 2026.8.5'tir. 21 Ekim 2026'da, 18 Ağustos'ta 2026.8.0 ile başlayan 2026.8 serisinin en son yaması olarak yayınlanmış ve resmi Compose dosyasındaki varsayılan imaj etiketi olarak 14 Ekim tarihli 2026.8.4'ün yerini almıştır. Proje, en az 2 CPU çekirdeği ve 2 GB RAM'e sahip bir sunucu gerektirir. Bunu minimum gereksinim olarak kabul edin. Sunucu bir gün boyunca açık kaldığında PostgreSQL ve worker bellek kullanımını korur.

Başlamadan önce gerekenler

Docker Engine ve Compose v2 eklentisi gerekir. Bunu docker compose version ile doğrulanabilir. Bu komut sürüm yerine hata verirse devam etmeden önce eklenti kurulmalıdır. Temel bilgiler VPS üzerinde Docker Compose ile uygulama çalıştırma bölümünde ele alınır. Ayrıca aşağıdaki örneklerde kullanılan auth.example.com için sunucuyu gösteren bir DNS A kaydı gerekir. Bunun nedeni, Authentik'in yönlendirme URL'lerini tarayıcının kullandığı ana bilgisayar adından oluşturmasıdır.

Stack, root olarak değil, docker grubundaki normal bir kullanıcıyla çalıştırılmalıdır. Bu gruba üyelik, host üzerinde root yetkisine denktir. Bu nedenle grup yalnızca bir deploy hesabına verilmeli, başka hiç kimseye verilmemelidir. Bu yaklaşım VPS üzerinde en az ayrıcalıklı kullanıcı hesapları bölümündeki ilkelere uygundur.

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, tümü çalışır durumda olan üç container'ı listelemeli ve postgresql, kontrolü geçtikten sonra healthy durumunu bildirmelidir. İlk başlatma veritabanı migrasyonlarını çalıştırır, bu nedenle web arayüzü yanıt vermeden önce bir dakika bekleyin.

Oluşturulan her iki değer de farklı nedenlerle önemlidir. PG_PASS, PostgreSQL şifresidir. Authentik kurulum belgeleri, 99 karakterden uzun şifrelerin desteklenmediğini belirtir, bu nedenle kendi belirlediğiniz şifreleri bu sınırın altında tutun; oluşturulan şifre çok daha kısadır. AUTHENTIK_SECRET_KEY, Authentik'in çerezleri imzalamak için kullandığı anahtardır ve yapılandırma belgeleri, bu anahtarı değiştirmenin aktif oturumları geçersiz kıldığını belirtir; bu nedenle daha sonra yeni bir anahtar kullanmak, oturum açmış tüm kullanıcıların çıkış yapmasına neden olur. .env dosyasını 600 modunda tutun ve yedeklerinizle birlikte güvenli bir yerde bir kopyasını saklayın; böylece bir geri yükleme işlemi, sunucunun çalıştığı aynı anahtarla geri dönmesini sağlar.

Compose dosyası, her iki değeri de ${VAR:?message} formuyla zorunlu olarak işaretler: PostgreSQL servisinde ${PG_PASS:?database password required} ve sunucu ile worker üzerinde ${AUTHENTIK_SECRET_KEY:?secret key required}. Bu, dosya eksik olduğunda Compose'un başlamayı 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 gibi bir satır yazdırır ve durur. Bu mesaj bir yapılandırma sorunu değil, bir yol sorunudur.

Önem taşıyan ortam değerleri

Diğer tüm ayarlar aynı .env dosyasına eklenir. Authentik, çift alt çizgiyi iç içe yapılandırma anahtarına dönüştürür; bu nedenle AUTHENTIK_EMAIL__HOST, email.host değerini ayarlar. Tek alt çizgi iç içe anahtara dönüştürülmez. Bir ayarın etkisiz görünmesinin en yaygın nedeni budur.

• AUTHENTIK_BOOTSTRAP_PASSWORD, ilk başlatmada 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 de aynı yöntemle bu kullanıcının adresini ve bir API token değerini ayarlar.
• COMPOSE_PORT_HTTP ve COMPOSE_PORT_HTTPS, yayınlanan portları varsayılan 9000 ve 9443 değerlerinden farklı portlara taşır.
• AUTHENTIK_EMAIL__HOST, AUTHENTIK_EMAIL__PORT, AUTHENTIK_EMAIL__USERNAME, AUTHENTIK_EMAIL__PASSWORD, AUTHENTIK_EMAIL__USE_TLS ve AUTHENTIK_EMAIL__FROM, giden e-postaları yapılandırır. Bunlar olmadan Authentik, port 25 üzerinden localhost adresine bağlanmayı dener. Bu nedenle parola sıfırlama e-postaları worker günlüğünde bağlantı hatasıyla sonuçlanır.
• AUTHENTIK_LOG_LEVEL=debug, bir login flow düzgün çalışmadığında görmek istediğiniz ayrıntı düzeyini etkinleştirir. Daha sonra değeri yeniden info yapın.
• AUTHENTIK_ERROR_REPORTING__ENABLED varsayılan olarak false değerindedir. Yalnızca crash report değerlerini upstream göndermeyi kabul ediyorsanız true olarak ayarlayın.

Bunlar düz metin içeren bir dosyadaki gizli bilgilerdir. Bu nedenle dizini diğer tüm kimlik bilgisi depolarını yönettiğiniz şekilde koruyun. self-hosted Vaultwarden instance gibi bir password manager, kurtarma kopyası için dizüstü bilgisayardaki bir nottan daha uygun bir konumdur.

İlk oturum açma ve yönetici hesabı

Bir tarayıcıda http://SERVER_IP:9000 adresini açın. Authentik, ilk kurulum akışını gösterir ve varsayılan akadmin kullanıcısı için bir şifre belirlemenizi ister. Zaten AUTHENTIK_BOOTSTRAP_PASSWORD değerini ayarladıysanız, bu adım tamamlanmıştır ve doğrudan oturum açma sayfasına yönlendirilirsiniz.

Directory ve ardından Users altında kendiniz için normal bir yönetici kullanıcısı oluşturun, bunu authentik Admins grubuna ekleyin ve bu hesapla oturum açın. akadmin hesabını, çevrimdışı saklanan uzun bir şifreye sahip bir acil durum hesabı olarak bırakın. Bozuk bir akış veya aşama sizi kilitlerse, /opt/authentik dizininden çalıştırılan docker compose run --rm server create_recovery_key 10 akadmin komutu, sizi doğrudan akadmin olarak oturum açtıran bir bağlantı yazdırır. Bu bağlantıya sahip olan herkes aynı erişime sahiptir, bu nedenle onu şifre gibi koruyun. Paylaşılan yerleşik bir hesap altında günlük işleri yürütmek denetim günlüğünü bozar, çünkü her olay akadmin olarak görünür ve kimin yaptığı anlaşılamaz. Bu argüman Authentik'in ötesinde de geçerlidir: her kişiye kendi aracısını veren self-hosted bir OneCLI aracı gibi bir yapı, ancak ona ulaşan kimlik tüm ekibin paylaştığı bir giriş yerine tek bir insana aitse okunabilir bir iz bırakır.

Authentik'i reverse proxy arkasında çalıştırma

9000 numaralı portu internete açmak çalışır, ancak TLS (transport layer security) ve gerçek bir hostname kullanmak istenir. Birden fazla Compose uygulaması için Traefik'i reverse proxy olarak kullanma bölümündeki kurulum zaten çalışıyorsa Authentik'i bir override dosyasıyla aynı harici proxy ağına bağlayın. 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

docker compose up -d ile uygulayın. Compose, override dosyasını otomatik olarak birleştirir. Bu nedenle server servisi resmi dosyadaki tüm ayarları korur ve etiketleri de alır. curl -I https://auth.example.com/if/user/ ile kontrol edin. Yanıt HTTP/2 200 olmalıdır. Traefik'ten gelen 404 page not found, isteği hiçbir router'ın eşleştirmediğini gösterir. Etiketlerin container'a ulaştığını, Host() kuralının hostname ile tam olarak eşleştiğini ve isteğin router'ın dinlediği HTTPS entry point üzerinden geldiğini kontrol edin.

Hostname çalıştıktan sonra proxy üzerinden geçmeyen erişimleri engellemek için override dosyasında yayınlanan portları 127.0.0.1 adresine bağlayın.

Bir uygulamayı forward auth ile koruma

Authentik proxy provider üç moda sahiptir. Yanlış modu seçmek bir saate mal olabilir. Proxy, outpost'un kendisinin trafiği upstream uygulamaya iletmesi anlamına gelir. Forward auth (single application) modunda trafiği yine kendi reverse proxy'niz iletir ve yalnızca isteğin oturum açmış bir kullanıcıdan gelip gelmediğini Authentik'e sorar. Forward auth (domain level) modu ise tek bir provider ile aynı üst alan adı altındaki tüm uygulamaları korur; bunun karşılığında uygulama bazında yetkilendirme kuralları kullanılamaz. Önde Traefik kullanılıyorsa forward auth (single application) seçilmelidir. Üzerinde deneme yapmak için somut bir uygulama gerekiyorsa self-hosted AFFiNE workspace iyi bir ilk adaydır. Bu tür bir iç aracın yalnızca kendi cihazlarınızdan erişilebilir olması gerekir. Ekip tarafından kullanılan bir araçta bu yaklaşım daha da anlamlıdır: self-hosted Chatwoot support desk aynı provider arkasına alınabilir. Böylece gelen kutusunu yanıtlayan herkes her gün bir kez oturum açar ve ek bir parola paylaşılması gerekmez.

Web arayüzünde Applications, ardından Providers bölümünü açın. Bir Proxy Provider oluşturun, forward auth single application modunu seçin ve harici ana bilgisayar olarak https://app.example.com değerini ayarlayın. Bu provider'ı kullanan bir Application oluşturun. Ardından Outposts bölümünü açın, authentik Embedded Outpost öğesini düzenleyin ve yeni uygulamayı selected applications listesine taşıyın. Outpost yalnızca kendisine atanmış uygulamalar için yanıt verir. Bu son adım atlanırsa provider doğru yapılandırılmış olsa bile yanıt alınamaz.

Middleware'i Authentik container'ı üzerinde bir kez tanımlayın ve korunan her uygulamadan buna başvurun:

      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, Traefik'in Authentik yanıtından alıp upstream'e gönderdiği isteğe kopyaladığı header listesidir. Bu liste çıkarılırsa uygulama yine korunur, ancak kullanıcı kimliğini öğrenemez. Bu nedenle X-authentik-username değerini otomatik oturum açma için okuyan bileşenler oturumu kapalı görür. Bu fark, kendi oturum açma mekanizmasını kullanan bir uygulamanın önünde daha belirgin hale gelir. Örneğin self-hosted openGym workout tracker ve passkey ile oturum açma akışında header'lar, aynı sayfa için bir istem ile iki istem arasındaki farkı oluşturur.

Korunan uygulama için tek router 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

Herkesin atladığı bölüm ikinci router'dır. Oturum açıldıktan sonra Authentik, tarayıcıyı auth.example.com üzerinde değil, uygulamanın ana bilgisayarında /outpost.goauthentik.io/ altındaki bir yola geri gönderir. Bu yol ön ekini Authentik servisine yönlendiren bir router yoksa istek uygulamanıza ulaşır, uygulama 404 döndürür ve oturum açma işlemi tamamlanmaz. Daha yüksek olan priority değeri, aynı alan adındaki düz Host() kuralına göre belirli yol kuralının öncelikli olmasını sağlar.

Özel tarayıcı penceresinde test edin. auth.example.com adresine yönlendirilmeniz, oturum açmanız ve ardından uygulamaya geri dönmeniz gerekir. Authentik tarafındaki docker compose logs -f server, her deneme için bir yetkilendirme olayı yazdırır. Böylece isteğin Authentik'e ulaşıp ulaşmadığı anlaşılır.

Gerçekten karşılaşılacak hatalar

Uygulama ile login sayfası arasında sonsuz yönlendirme döngüsü. Provider üzerindeki external host, tarayıcının kullandığı değerle eşleşmiyor. Genellikle provider içinde http://, adres çubuğunda ise https:// kullanılır. Bu durumda session cookie farklı bir origin için ayarlanır ve her geri dönüş yeni bir anonim istek gibi değerlendirilir. Retest işleminden önce external host değerini düzeltin ve her iki domain için cookie'leri temizleyin.

/outpost.goauthentik.io/start adresinde 404. Outpost router eksiktir veya bu host için catch-all router'dan daha düşük önceliğe sahiptir.

Uygulama login istemeden yükleniyor. middlewares etiketi mevcut olmayan bir middleware'i belirtir. Traefik bu konuda uyarı vermez. Bu nedenle authentik@docker içindeki bir yazım hatası, hiçbir middleware'in çalışmaması anlamına gelir. Traefik dashboard'unu açın ve router listesinin middleware'i içerdiğini doğrulayın.

Başarılı login sonrasında Authentik tarafından 403 döndürülmesi. Kullanıcı kimlik doğrulamasından geçmiştir ancak yetkilendirilmemiştir. Uygulamaya, bu kullanıcının karşılamadığı bir policy binding veya grup gereksinimi uygulanmıştır. Admin arayüzündeki Events log, erişimi reddeden policy'yi gösterir.

Keycloak ne zaman daha uygun bir seçimdir

Keycloak, Red Hat tarafından desteklenen daha eski projedir. Klasik kurumsal kimlik işlemleri için daha güçlü bir seçenektir. Buna yoğun SAML federasyonu, aynı anda birden fazla harici kimlik sağlayıcısından gelen oturum açma işlemlerinin aracılanması ve belgelenmiş bir geçiş yöntemi olarak realm dışa aktarma ve içe aktarma işlemleri dahildir. Arkasındaki ticari destek, bazı kuruluşlar için kâğıt üzerinde önem taşır. Bunun karşılığında Keycloak'ın kendi proxy'si yoktur. OIDC (OpenID Connect) veya SAML konuşmayan bir uygulamayı korumak için yanında oauth2-proxy benzeri bir araç çalıştırılması gerekir. Authentik'in yerleşik proxy sağlayıcısı bu işlevi zaten entegre biçimde sunar. Bu nedenle farklı türlerde uygulamalar kullanan self-host kullanıcılarının çoğu Authentik'i tercih eder.

Yedekleme ve yükseltmeler

Geri yüklemeyi mümkün kılan üç şey vardır: PostgreSQL veritabanı, ./data dizini ve .env dosyası.

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. Döküm, AUTHENTIK_SECRET_KEY dosyasının bir kopyasını içermez ve farklı bir anahtarla geri yükleme yapmak tüm aktif oturumları geçersiz kılar; bu nedenle orijinal anahtarı saklamak, geri yüklenen sunucunun kaldığı yerden devam etmesini sağlar.

Yükseltmeler bir etiket değişikliğidir. .env içindeki AUTHENTIK_TAG değerini istediğiniz sürüme ayarlayın, ardından docker compose pull ve ardından docker compose up -d komutlarını çalıştırın. Eğer AUTHENTIK_TAG değerini hiç ayarlamadıysanız, sürüm doğrudan compose.yml içine yazılan varsayılan değerden gelir; bu nedenle o dosyanın daha yeni bir kopyasını indirmek yükseltme işlemidir ve resmi yükseltme belgelerinde açıklanan yöntem budur. Önce sürüm notlarını okuyun. Authentik tarih tabanlı sürümler kullanır ve Ekim 2026 itibarıyla belgeleri, yükseltmelerin ana sürüm sırasını takip etmesi gerektiğini belirtir: çalıştırdığınız serinin en son yamasına geçin, ardından hiçbirini atlamadan sonraki her seriye sırayla ilerleyin. Authentik sürüm düşürmeyi desteklemez, bu nedenle veritabanı dökümünü çekme işleminden sonra değil, önce alın.

FAQ

Authentik'i self-host etmek ücretsiz midir?

Açık kaynak sürümü ücretsizdir ve yukarıdaki tüm bileşenleri kapsar: proxy provider, forward auth, OIDC (OpenID Connect), SAML ve flows engine. Ücretli enterprise katmanı destek ve bazı kurumsal özellikler ekler, ancak burada anlatılanların hiçbiri lisans gerektirmez.

Authentik kullanmak için Traefik gerekir mi?

Hayır. Forward auth, auth_request üzerinden nginx ile ve forward_auth üzerinden Caddy ile çalışır. Her durumda kullanılan yöntem aynıdır: reverse proxy her isteği Authentik'e sorar ve korunan hostname üzerindeki /outpost.goauthentik.io/ path prefix'i uygulamaya değil, Authentik'e yönlendirilmelidir.

Korunan uygulamam neden sürekli giriş ve hata ekranları arasında döngüye giriyor?

Proxy provider üzerinde yapılandırılan external host, tarayıcının kullandığı URL ile eşleşmiyordur; en sık görülen durum http ile https arasındaki uyumsuzluktur. Oturum çerezi bir origin için oluşturuluyor ve başka bir origin üzerinden okunuyor; bu nedenle Authentik her isteği anonim olarak görüyor. External host değerini düzeltin, ardından yeniden test etmeden önce her iki hostname için çerezleri temizleyin.

Authentik ne kadar RAM gerektirir?

Ekim 2026 itibarıyla belgelenen minimum gereksinim, PostgreSQL, server ve worker bileşenlerinin tümünü birlikte çalıştırmak için 2 CPU çekirdeği ve 2 GB RAM'dir. 2 GB RAM bulunan bir sistemde bellek baskısı, kernel'in OOM killer bileşenini devreye sokabilir. Bu bileşen, en yüksek badness score değerine sahip süreci sonlandırır. Bu değer yaklaşık olarak sürecin kullandığı izin verilen bellek payına ve oom_score_adj değerine dayanır. Sonlandırılan süreç worker olduğunda arka plan görevleri ve giden e-posta durur, ancak giriş sayfası çalışmaya devam eder. Aynı sunucuda koruduğunuz uygulamalar da çalışıyorsa 4 GB RAM ayırın.