Authentik ile Kendi SSO Sunucunuzu Kurma

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

Authentik, kendi sunucunuzda barındırabileceğiniz bir SSO (tek oturum açma) sunucusudur: Kullanıcılarınız bir kez oturum açar ve arkasındaki her uygulama kendi parolasını sormak yerine bu oturumu kabul eder. Kurulum, resmi bir Docker Compose dosyası ve oluşturulan iki gizli anahtardan oluşur. 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 üç hizmet olarak sunulur: bir PostgreSQL veritabanı, bir server işlemi ve bir worker işlemi. Sunucu container'ı, gömülü outpost'u da ç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 geçerli sürümdür ve proje, en az 2 CPU çekirdeğine ve 2 GB RAM'e sahip bir host ister. Bu değerler alt sınır olarak kabul edilmelidir. PostgreSQL ve worker, sistem bir gün çalıştıktan sonra da bellek kullanır.

Başlamadan önce gerekenler

docker compose version ile doğrulayabileceğiniz Compose v2 eklentisine sahip Docker Engine gereklidir. Bu komut bir sürüm yerine hata verirse devam etmeden önce eklentiyi yükleyin; temel bilgiler VPS üzerinde Docker Compose ile uygulama çalıştırma bölümünde ele alınmaktadır. Ayrıca sunucuya yönlenen bir DNS A kaydı gerekir. Aşağıdaki örneklerde bu kayıt auth.example.com değeridir. Bunun nedeni, Authentik'in yönlendirme URL'lerini tarayıcının kullandığı ana bilgisayar adından oluşturmasıdır.

Yığını root olarak değil, docker grubundaki normal bir kullanıcı olarak çalıştırın. Bu gruba üyelik ana bilgisayar üzerinde root yetkisine eşdeğerdir. Bu nedenle grubu VPS üzerinde en az ayrıcalıklı kullanıcı hesapları yaklaşımına uygun olarak yalnızca bir dağıtım hesabına verin.

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 üç container listelemelidir. postgresql, healthy ve server bildirmelidir. worker ise running bildirmelidir. İlk başlatma veritabanı migration işlemlerini çalıştırır. Bu nedenle web arayüzünün yanıt vermesi için bir dakika beklenmelidir.

Oluşturulan iki değer 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ğerin daha sonra değiştirilmesi tüm kullanıcıların oturumunu kapatır ve oluşturulmuş tüm API token'larını geçersiz kılar. .env için mode 600 korunmalı ve bir kopyası güvenli bir yerde saklanmalıdır. Çünkü 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çimiyle 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 çıktısını verir ve işlem durur. Bu ileti bir path sorunudur, config sorunu değildir.

Önemli ortam değerleri

Diğer her şey aynı .env dosyasına eklenir. Authentik, çift 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 uyarı verilmeden yok sayılır. Bir ayarın hiçbir etkisi yokmuş gibi 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 yazmak gerekmez. AUTHENTIK_BOOTSTRAP_EMAIL ve AUTHENTIK_BOOTSTRAP_TOKEN de aynı şekilde bu kullanıcının adresini ve bir API token'ını ayarlar.
• COMPOSE_PORT_HTTP ve COMPOSE_PORT_HTTPS, yayımlanan 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, 25 numaralı portta localhost ile bağlantı kurmayı 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 gereken ayrıntı düzeyini etkinleştirir. İşlem tamamlandıktan sonra değeri yeniden info yapın.
• AUTHENTIK_ERROR_REPORTING__ENABLED varsayılan olarak false değerindedir. Yalnızca kilitlenme raporlarını upstream'e göndermeyi kabul ediyorsanız true olarak ayarlayın.

Bunlar düz metin dosyasında saklanan gizli bilgilerdir. Bu nedenle dizini, diğer tüm kimlik bilgisi depolarında olduğu gibi koruyun. Kendi sunucunuzda barındırılan bir Vaultwarden örneği gibi bir parola yöneticisi, kurtarma kopyası için dizüstü bilgisayardaki bir nottan daha uygun bir konumdur.

İlk oturum açma ve admin hesabı

http://SERVER_IP:9000 adresini bir tarayıcıda açın. Authentik, ilk kurulum akışını gösterir ve varsayılan akadmin kullanıcısı için bir parola belirlemenizi ister. AUTHENTIK_BOOTSTRAP_PASSWORD zaten ayarlandıysa bu adım tamamlanmış olur ve doğrudan oturum açma sayfasına geçilir.

Directory, ardından Users altında kendiniz için normal bir admin 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ışı saklanan bir acil durum hesabı olarak bırakın. Paylaşılan yerleşik hesapla günlük çalışmak denetim günlüğünü kullanılmaz hale getirir; çünkü her olayda akadmin görünür ve işlemi kimin yaptığı anlaşılmaz.

Authentik'i ters proxy arkasına alın

9000 portunun internete açılması çalışır, ancak TLS (aktarım katmanı güvenliği) ve gerçek bir ana bilgisayar adı gerekir. Kurulum birden çok Compose uygulaması için ters proxy olarak Traefik ile zaten çalışıyorsa, bir override dosyası kullanarak Authentik'i 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. Böylece server hizmeti resmi dosyadaki tüm ayarları korur ve etiketleri de alır. curl -I https://auth.example.com/if/user/ ile denetleyin. Bu komut HTTP/2 200 yanıtını vermelidir. Traefik'ten alınan 404 page not found yanıtı, container'ın proxy ağında olmadığı anlamına gelir. Traefik, erişemediği bir container'a trafik yönlendiremez.

Ana bilgisayar adı ç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.

Bir uygulamayı forward auth ile koruma

Authentik proxy provider için 3 mod sunar. Yanlış modu seçmek 1 saatin kaybedilmesine neden olabilir. Proxy, trafiği outpost'un kendisinin upstream uygulamaya iletmesi demektir. Forward auth (single application) modunda trafiği kendi reverse proxy'niz iletmeye devam eder. Yalnızca isteğin oturum açmış bir kullanıcıdan gelip gelmediğini Authentik'e sorar. Forward auth (domain level), tek bir provider ile aynı üst domain 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.

Web arayüzünde Applications ve ardından Providers bölümünü açın. Bir Proxy Provider oluşturun. Forward auth single application modunu seçin. External host değerini https://app.example.com olarak ayarlayın. Bu provider'ı işaret eden bir Application oluşturun. Ardından Outposts bölümünü açın, authentik Embedded Outpost öğesini düzenleyin ve yeni uygulamayı seçili uygulamalarına ekleyin. Outpost yalnızca kendisine atanmış uygulamalar için yanıt verir. Bu son adımın atlanması, doğru yapılandırılmış provider'ın yine de yanıt vermemesinin nedenidir.

Middleware'i Authentik container'ı üzerinde bir kez tanımlayın ve korunan her uygulamada 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 alıp upstream'e gönderdiği isteğe kopyaladığı header'ların listesidir. Bu liste eklenmezse uygulama korunmaya devam eder, ancak kullanıcıyı tanıyamaz. Bu nedenle otomatik oturum açma için X-authentik-username okuyan bileşenler oturum açılmamış durumda kalır.

Korunan uygulama için tek router değil, 2 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 çoğu zaman eklenmez. Oturum açma işleminden sonra Authentik, tarayıcıyı auth.example.com üzerinde değil, uygulamanın hostname'i altında /outpost.goauthentik.io/ ile başlayan bir path'e geri gönderir. Bu path prefix'ini Authentik service'ine gönderen bir router yoksa istek uygulamanıza ulaşır. Uygulama 404 yanıtı verir ve oturum açma işlemi tamamlanmaz. Daha yüksek priority değeri, aynı domain üzerindeki düz Host() kuralına göre belirli path kuralının öncelikli olmasını sağlar.

Özel bir tarayıcı penceresinde test edin. auth.example.com adresine yönlendirilmeniz, oturum açmanız ve uygulamaya geri dönmeniz gerekir. Authentik tarafındaki docker compose logs -f server, her deneme için bir authorization event yazdırır. Bu kayıt, isteğin Authentik'e ulaşıp ulaşmadığını gösterir.

Gerçekte karşılaşılacak hatalar

Uygulama ile oturum açma sayfası arasında sonsuz yönlendirme döngüsü. Sağlayıcıdaki harici ana bilgisayar adı, tarayıcının kullandığı adla eşleşmiyor. Genellikle sağlayıcıda http://, adres çubuğunda ise https:// kullanılır. Bu durumda oturum çerezi farklı bir kaynak için ayarlanır. Bu nedenle her geri dönüş yeni bir anonim istek olarak değerlendirilir. Harici ana bilgisayar adını düzeltin ve yeniden test etmeden önce her iki etki alanına ait çerezleri temizleyin.

/outpost.goauthentik.io/start adresinde 404. Outpost yönlendiricisi eksik olabilir veya bu ana bilgisayar için genel eşleşen yönlendiriciden daha düşük önceliğe sahip olabilir.

Uygulama, hiç oturum açma istemeden yükleniyor. middlewares etiketi mevcut olmayan bir ara yazılımı adlandırıyor. Traefik bu konuda uyarı vermez. Bu nedenle authentik@docker içindeki bir yazım hatası, hiçbir ara yazılımın çalışmaması anlamına gelir. Traefik panosunu açın ve yönlendiricinin ara yazılımı listelediğini doğrulayın.

Başarılı oturum açma sonrasında Authentik tarafından 403 döndürülüyor. Kullanıcının kimliği doğrulanmıştır ancak yetkisi yoktur. Uygulamada bu kullanıcının karşılamadığı bir ilke bağlaması veya grup gereksinimi bulunur. Yönetim arayüzündeki Events günlüğünde isteği reddeden ilke belirtilir.

Keycloak'ın daha uygun olduğu durumlar

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

Yedekler ve yükseltmeler

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ü .env ile birlikte saklayın. Döküm tek başına yeterli değildir, çünkü oturum ve belirteç verilerini koruyan gizli anahtar .env içinde bulunur.

Yükseltmeler, etiket değişikliğinden ibarettir. .env içinde AUTHENTIK_TAG değerini istenen 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, çünkü Authentik tarih tabanlı sürümler kullanır ve bazı sürümlerde önceki sürümden geçiş yapılmasını gerektiren migration işlemleri bulunur. Veritabanı dökümünü pull işleminden önce alın, sonra değil.

FAQ

Authentik'i kendi sunucumda barındırmak ücretsiz mi?

Açık kaynak sürüm ücretsizdir ve yukarıda açıklanan tüm özellikleri kapsar: proxy provider, forward auth, OIDC (OpenID Connect), SAML ve flows engine. Ücretli kurumsal katman destek ve bazı kurumsal özellikler ekler, ancak burada açıklanan hiçbir özellik için lisans gerekmez.

Authentik kullanmak için Traefik gerekli mi?

Hayır. Forward auth, auth_request üzerinden nginx ile ve forward_auth üzerinden Caddy ile çalışır. Her durumda yöntem aynıdır: reverse proxy her isteği Authentik'e sorar ve korunan host üzerindeki /outpost.goauthentik.io/ yol öneki, uygulama yerine Authentik'e yönlendirilmelidir.

Korunan uygulamam neden sürekli oturum açma ve hata arasında dönüyor?

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. Oturum çerezi bir origin için oluşturulur ve başka bir origin üzerinden okunur. Bu nedenle Authentik her isteği anonim olarak görür. Harici host'u düzeltin. Ardından yeniden test etmeden önce her iki host için çerezleri temizleyin.

Authentik ne kadar RAM gerektirir?

Temmuz 2026 itibarıyla belgelenen minimum gereksinim, PostgreSQL, server ve worker birlikte çalışırken 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 işlem worker olur. Belirti, oturum açma 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.