Authentik ile Uygulamalar için Self-Hosted SSO

Barındırdığınız tüm uygulamalar için tek oturum açma

Authentik, self-hosted bir SSO (single sign-on) sunucusudur: Kullanıcılar bir kez oturum açar ve arkasındaki her uygulama kendi parolasını istemek yerine bu oturumu kabul eder. Kurulumda resmi bir Docker Compose dosyası ve oluşturulan iki secret kullanılır. Asıl dikkat gerektiren bölüm bundan sonra başlar: reverse proxy'yi Authentik'e yönlendirmek ve mevcut bir uygulamayı forward auth arkasına almaktır.

Authentik, bu Compose dosyasında üç servis olarak çalışır: PostgreSQL veritabanı, bir server süreci ve bir worker süreci. Server container'ı, gömülü outpost bileşenini de çalıştırır. Bu bileşen, korunan her uygulama için "bu istekle oturum açılmış mı?" sorusunu yanıtlar. 2026.5, Temmuz 2026 itibarıyla güncel sürümdür. Proje, en az 2 CPU çekirdeği ve 2 GB RAM içeren bir host ister. Bu değerler alt sınır olarak değerlendirilmelidir. PostgreSQL ve worker, sunucu bir gün çalıştıktan sonra da bellek kullanmaya devam eder.

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ıyla 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 çıktısında üç container listelenmelidir. postgresql için healthy, server için ise worker ve running bildirilmelidir. İlk başlatma sırasında veritabanı migration işlemleri çalıştırılır. Web arayüzünün yanıt vermesi için bir dakika beklenmelidir.

Oluşturulan iki değer de farklı nedenlerle önemlidir. PG_PASS PostgreSQL parolasıdır ve 99 karakterlik kesin bir sınırı vardır. AUTHENTIK_SECRET_KEY oturumları ve token'ları imzalar. Bu değer daha sonra değiştirilirse tüm kullanıcıların oturumu kapatılır ve oluşturulmuş tüm API token'ları geçersiz kılınır. .env için mode 600 kullanılmalı ve bir kopyası güvenli bir yerde saklanmalıdır. Eşleşen secret key olmadan geri yüklenen bir veritabanında hiçbir kullanıcı oturum açamaz.

Compose dosyası her iki değeri de ${PG_PASS:?database password required} biçimini kullanarak okur. Bu nedenle dosya eksik olduğunda Compose başlatmayı reddeder. docker compose up -d komutunun yanlış dizinden çalıştırılması required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required mesajını yazdırır ve durur. Bu mesaj bir path sorunu olduğunu gösterir; config sorunu olduğunu göstermez.

Önem taşıyan ortam değerleri

Diğer tüm ayarlar aynı .env dosyasına eklenir. Authentik, iki alt çizgiyi iç içe bir yapılandırma anahtarına dönüştürür; bu nedenle AUTHENTIK_EMAIL__HOST, email.host değerini ayarlar. Tek alt çizgi herhangi bir uyarı verilmeden yok sayılır. 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 parola herkese açık bir web formuna girilmez. AUTHENTIK_BOOTSTRAP_EMAIL ve AUTHENTIK_BOOTSTRAP_TOKEN de aynı yöntemle bu kullanıcının adresini ve bir API token'ını 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-postayı yapılandırır. Bu değerler olmadan Authentik, port 25 üzerinden localhost adresine bağlanmayı dener. Bu nedenle parola sıfırlama e-postaları worker log'unda bağlantı hatası olarak görünür.
• AUTHENTIK_LOG_LEVEL=debug, login flow düzgün çalışmadığında ihtiyaç duyulan 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 raporlarını upstream'e göndermeyi kabul ediyorsanız true olarak ayarlayın.

Bunlar düz metin dosyasında tutulan gizli bilgilerdir. Bu nedenle dizin, diğer tüm kimlik bilgisi depolarında olduğu gibi korunmalıdır. 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 parola belirlemenizi ister. AUTHENTIK_BOOTSTRAP_PASSWORD değerini zaten belirlediyseniz bu adım tamamlanmış olur ve doğrudan oturum açma sayfasına geçersiniz.

Directory ve ardından Users altında kendiniz için normal bir yönetici kullanıcısı oluşturun, bu kullanıcıyı authentik Admins grubuna ekleyin ve bu hesapla oturum açın. akadmin hesabını, parolası uzun ve çevrimdışı olarak saklanan bir acil durum hesabı olarak bırakın. Yerleşik ve ortak bir hesapla günlük çalışma, denetim günlüğünü işlevsiz hale getirir; çünkü her olayda akadmin yazarken işlemi kimin gerçekleştirdiği belirtilmez. Bu durum Authentik dışındaki sistemler için de geçerlidir: her kişiye kendi agent'ını veren self-hosted OneCLI harness gibi bir yapı, kendisine ulaşan kimlik tek bir kişiye ait olduğunda okunabilir bir iz bırakır; tüm ekibin ortak kullandığı bir oturum açma hesabına ait olduğunda bırakmaz.

Authenti̇k'i reverse proxy arkasına yerleştirme

9000 portunu internete açmak çalışır; ancak TLS (transport layer security) ve gerçek bir hostname kullanmak istenir. Birden fazla Compose uygulaması için reverse proxy olarak Traefik kurulumunu zaten kullanıyorsanız Authentik'i bir override dosyasıyla aynı harici proxy ağına bağlayın. docker-compose.override.yml dosyasını compose.yml dosyasının yanına 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. Komutun HTTP/2 200 yanıtını vermesi gerekir. Traefik'ten gelen 404 page not found, container'ın proxy ağında olmadığını gösterir. Traefik, erişemediği bir container'a trafik yönlendiremez.

Hostname çalıştıktan sonra yayımlanan portları override dosyasında 127.0.0.1 adresine bağlayın. Böylece erişimin tek yolu proxy üzerinden olur.

Tek bir uygulamayı forward auth ile koruma

Authentik proxy provider üç moda sahiptir ve 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 taşır ve yalnızca isteğin oturum açmış bir kullanıcıdan gelip gelmediğini Authentik'e sorar. Forward auth (domain level) 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 pratik yapmak için somut bir uygulama aranıyorsa self-hosted bir AFFiNE çalışma alanı iyi bir ilk adaydır. Bu tür bir dahili araca yalnızca kendi cihazlarınızdan erişmek istersiniz. Ekip tarafından kullanılan bir araçta bu yaklaşım daha da anlamlıdır: self-hosted bir Chatwoot destek masası aynı provider'ın arkasına alınabilir. Böylece gelen kutusunu yanıtlayan herkes her gün bir kez oturum açar ve bir parolayı daha paylaşmak 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 external host değerini https://app.example.com olarak ayarlayın. Bu provider'ı gösteren 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-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 upstream'e gönderdiği isteğe kopyaladığı header'ların listesidir. Bu liste eklenmezse uygulama korunmaya devam eder, ancak kullanıcı kimliğini öğrenemez. Bu nedenle otomatik oturum açma için X-authentik-username okuyan özellikler oturum kapalı kalır. Bu eksiklik, kendi oturum açma mekanizmasını da kullanan bir uygulamanın önünde daha belirgin hale gelir. Örneğin self-hosted bir openGym egzersiz takip uygulaması ve passkey ile oturum açma özelliğinde header'lar, aynı sayfa için bir istem mi yoksa iki istem mi gösterileceğini belirler.

Korunan uygulamanın kendisi tek bir router yerine iki router gerektirir:

    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 çoğu zaman atlanan kısımdır. Oturum açıldıktan sonra Authentik, tarayıcıyı /outpost.goauthentik.io/ altındaki bir path'e uygulamanın hostname'i üzerinde geri gönderir; bu işlem auth.example.com üzerinde gerçekleşmez. Bu path prefix'ini Authentik servisine gönderen bir router olmazsa istek uygulamanıza ulaşır. Uygulamanız 404 yanıtı verir ve oturum açma işlemi tamamlanmaz. Daha yüksek olan priority değeri, aynı domain üzerindeki düz Host() kuralına kıyasla özel path kuralının öncelikli olmasını sağlar.

Testi private browser window içinde gerçekleştirin. 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 authorization event yazdırır. Böylece isteğin Authentik'e ulaşıp ulaşmadığı görülebilir.

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 olur

Keycloak, Red Hat tarafından desteklenen daha eski bir projedir. Klasik kurumsal kimlik yönetimi için daha güçlü bir seçenektir. Buna yoğun SAML federasyonu, aynı anda birden fazla harici kimlik sağlayıcısından oturum açma işlemlerinin aracılanması ve belgelenmiş bir geçiş yolu olarak realm dışa aktarma ve içe aktarma işlemleri dahildir. Bazı kuruluşlar için arkasındaki ticari destek, kağıt üzerinde önem taşır. Bunun karşılığında Keycloak'ın kendi proxy'si yoktur. OIDC (OpenID Connect) konuşmayan bir uygulamayı korumak için yanında oauth2-proxy benzeri bir çözüm çalıştırılması gerekir. Authentik'in yerleşik proxy provider bileşeni bu işlevi zaten entegre olarak sağlar. Bu nedenle farklı türlerde uygulamalardan oluşan karma bir ortam kullanan self-hosting kullanıcılarının çoğu Authentik'i tercih eder.

Yedekler ve yükseltmeler

Bir geri yüklemeyi mümkün kılan üç unsur vardır: 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 birlikte saklayın. Döküm tek başına yeterli değildir; oturum ve token verilerini koruyan gizli anahtar .env içinde bulunur.

Yükseltmeler bir etiket değişikliğidir. .env içinde AUTHENTIK_TAG değerini istediğiniz sürüme ayarlayın, ardından docker compose pull ve docker compose up -d komutlarını çalıştırın. Önce sürüm notlarını okuyun; Authentik tarih tabanlı sürümler kullanır ve bazı sürümlerde, önceki sürümden geçiş yapılmasını bekleyen migration işlemleri bulunur. Veritabanı dökümünü pull işleminden önce alın, sonra değil.

FAQ

Authentik'i self-host etmek ücretsiz midir?

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

Authentik kullanmak için Traefik gerekli midir?

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 login ve hata arasında gidip geliyor?

Proxy provider üzerinde yapılandırılan harici host, tarayıcının kullandığı URL ile eşleşmiyordur. En yaygın durum http ile https arasındaki uyumsuzluktur. Session cookie bir origin için oluşturulur ve başka bir origin üzerinde okunur. Bu nedenle Authentik her isteği anonim olarak görür. Harici host değerini düzeltin. Ardından yeniden test etmeden önce her iki hostname için cookie'leri temizleyin.

Authentik ne kadar RAM gerektirir?

Temmuz 2026 itibarıyla belgelenen minimum gereksinim, PostgreSQL, server ve worker bileşenlerinin tümü için 2 CPU çekirdeği ve 2 GB RAM'dir. 2 GB RAM bulunan bir sistemde bellek baskısı oluştuğunda kernel'in sonlandırdığı ilk süreç worker olur. Belirti, login sayfası çalışmaya devam ederken arka plan görevlerinin ve giden e-postaların durmasıdır. Aynı sunucuda koruduğunuz uygulamalar da çalışıyorsa 4 GB RAM ayırın.