This content is not yet available in 🇺🇸 English. Showing the 🇹🇷 Türkçe version.
NextAuth (Auth.js) v5 ile Güvenli Oturum Yönetimi
Bu rehberde ne öğreneceksiniz?
Bu yazı bir haber özeti değil; adım adım uygulayabileceğiniz bir öğretici makale (tutorial) formatındadır. Her bölümün sonunda pratik çıkarımlar ve üretim ortamında karşılaşacağınız senaryolar yer alır.
- Auth.js v5 yapılandırmasını App Router'a entegre etmek
- Credential ve OAuth provider eklemek
- RBAC ile admin route korumak
- Session hardening uygulamak
Ön koşullar
Rehberi verimli takip etmek için aşağıdaki bilgilere aşina olmanız önerilir. Eksik hissettiğiniz konularda ilgili bölümde ek kaynak ipuçları bulacaksınız.
- HTTP cookie ve session kavramı
- Next.js middleware temelleri
- Prisma User modeli
Güncellik ve teknoloji yığını
Makale 2026 itibarıyla güncellenmiştir. Örnekler ve API referansları şu yığınla uyumludur: next-auth 5.0 beta, Next.js 16 App Router, bcryptjs, Prisma adapter. Eski sürüm dokümantasyonu ile karıştırmamak için major versiyon farklarını özellikle belirttik.
Framework sürümleri hızla değişir; kalıcı olan prensipler (güvenlik, katman ayrımı, ölçüm) bu rehberin omurgasını oluşturur.
Bölüm 1: Auth yapılandırması
auth.ts merkez dosyadır. Providers, callbacks ve session stratejisi burada tanımlanır.
Adım adım uygulama
Aşağıdaki sırayı takip edin. Her adımı tamamlamadan bir sonrakine geçmeyin; özellikle güvenlik ve veri katmanı adımları atlanmamalıdır.
- Prisma adapter ile User modelini bağlayın.
- Credentials provider'da bcrypt ile hash karşılaştırın.
- JWT veya database session stratejisini bilinçli seçin.
export const { handlers, auth, signIn, signOut } = NextAuth({
adapter: PrismaAdapter(prisma),
session: { strategy: 'jwt' },
callbacks: {
jwt({ token, user }) {
if (user) token.role = user.role;
return token;
},
session({ session, token }) {
session.user.role = token.role;
return session;
},
},
});
Bölüm 2: Route koruma
Middleware ile /admin ve /blog/add rotalarını koruyun. Server Action içinde de session kontrolü tekrarlanmalıdır — middleware tek başına yetmez.
isModerator(role) helper'ı merkezi tutun. UI'da buton gizlemek güvenlik değildir; API ve action'da da kontrol şart.
Dikkat: Server Action'lar public endpoint gibidir; her action başında auth() çağırın.
Bölüm 3: Güvenlik checklist
Production öncesi mutlaka tamamlanması gereken maddeler:
- HTTPS ve Secure cookie
- Login rate limiting
- Şifre sıfırlama token'ı tek kullanımlık + TTL
- CSRF: framework varsayılanlarına güven ama custom form'ları denetleyin
- OAuth state parametresi ve redirect URI whitelist
Bölüm 4: Session fixation ve OAuth state
OAuth callback'te state parametresi CSRF içindir; asla atlamayın.
Production ortamında Auth.js ile ilgili en sık görülen sorun, geliştirme ortamındaki varsayımların (küçük veri seti, tek kullanıcı, sıcak cache) canlı trafikte çökmemesidir. Bu yüzden her değişiklikten önce yük testi veya en azından p95 latency ölçümü yapın.
Structured logging (request id, route, süre, kullanıcı id’si — PII olmadan) ve hata oranı alarmları, sorunları kullanıcı şikayetinden önce yakalamanızı sağlar. Log’da stack trace tutun; kullanıcıya generic mesaj gösterin.
Dokümantasyonu kod ile birlikte güncelleyin: README, ADR (Architecture Decision Record) veya ekip wiki’sinde “neden bu kararı aldık?” sorusunun cevabı gelecekteki sizin en büyük yardımcınızdır.
Dikkat: JWT secret rotation planı olmadan production'a çıkmayın.
Sık yapılan hatalar
Aşağıdaki tuzaklar eğitim ortamlarında nadiren, production'da ise pahalıya mal olur. Code review checklist'inize eklemenizi öneririz.
- Yalnızca client-side redirect ile admin korumak
- Role bilgisini client'tan gelen body'ye güvenmek
- Session ömrünü gereksiz uzatmak
Pratik alıştırmalar
Okumak yeterli değildir; öğrenmeyi pekiştirmek için küçük bir side-project veya mevcut kod tabanınızda şu görevleri uygulayın:
- Moderator olmayan kullanıcı ile blog add API'sini 403 alacak şekilde test edin
- Session callback'e role ekleyin ve profile sayfasında gösterin
Özet ve sonraki adımlar
Bu rehberdeki prensipleri tek seferde tüm projeye uygulamaya çalışmayın. Önce tek bir route veya modül seçin, ölçün, sonra yaygınlaştırın.
- Passkey / WebAuthn desteğini araştırın
- OWASP Authentication cheat sheet'i okuyun