Next.js uygulamasına giriş ve oturum eklemek: kimlik doğrulama yol haritası

Başlamadan önce: kavramları birbirinden ayırın

Kimlik doğrulama işini karıştırmadan kurmak için onu parçalara ayırın. Kimlik doğrulama (authentication), kullanıcının iddia ettiği kişi olduğunu kanıtlamasıdır; kullanıcı adı ve şifre en yaygın örnektir. Oturum yönetimi (session management), kullanıcının doğrulanmış durumunu istekler arasında taşımaktır. Yetkilendirme (authorization) ise doğrulanmış kullanıcının hangi sayfa ve verilere erişebileceğine karar vermektir.

Next.js dokümantasyonu, kendi çözümünüzü yazmanın mümkün olduğunu ama güvenlik ve basitlik için bir kimlik doğrulama kitaplığı önerdiğini söyler. Kitaplıklar giriş, oturum ve yetkilendirmenin yanında sosyal girişler, çok adımlı doğrulama ve rol tabanlı erişim gibi özellikleri de getirir. Dokümanda listelenen seçeneklerden bazıları NextAuth.js (Auth.js), Better Auth, Clerk, Auth0, Supabase, Kinde ve WorkOS'tur.

Bu sayfada mantığı anlamanız için temel akışı elle kuruyoruz. Üretimde hazır bir kitaplık seçecek olsanız bile akışı bilmek, yanlış kurulmuş bir yapılandırmayı fark etmenizi sağlar.

Giriş formu ve sunucuda doğrulama

Giriş ya da kayıt formu, bir Server Action'ı çağıran standart bir form olarak kurulur. Action sunucuda çalıştığı için kimlik bilgilerini işlemek için güvenli bir yerdir.

// app/ui/giris-formu.tsx import { girisYap } from '@/app/actions/auth'

export function GirisFormu() { return ( <form action={girisYap}> <input name="eposta" type="email" /> <input name="sifre" type="password" /> <button type="submit">Giriş yap</button> </form> ) }

Action'da önce alanlar doğrulanır; geçersizse kimlik sağlayıcıya ya da veritabanına gitmeden erken dönülür. Sonra kullanıcı sorgulanır ve şifre doğrulanır. Şifreler asla düz metin saklanmaz; kayıt sırasında karma (hash) değerleri tutulur ve girişte karşılaştırma bu değerlerle yapılır. Başarısız girişte hangi alanın yanlış olduğunu belli etmemek (e-posta mı şifre mi) kullanıcı listeleme saldırılarını zorlaştırır; genel bir mesaj tercih edin.

Başarılı doğrulamanın ardından sıra oturum oluşturmaya ve yönlendirmeye gelir.

Oturumu çerezde tutmak: durumsuz oturum

İstekler arasında kullanıcıyı hatırlamanın yaygın yolları şunlardır. Durumsuz (stateless) oturumda oturum verisi ya da bir belirteç tarayıcının çerezinde saklanır ve her istekle birlikte gelir; sunucu onu doğrulayarak kimin istek yaptığını anlar. Veritabanı oturumunda ise oturum verisi veritabanında durur, tarayıcıya yalnızca şifrelenmiş oturum kimliği verilir. Durumsuz yöntem daha basittir ama yanlış uygulanırsa daha az güvenlidir; veritabanı yöntemi daha güvenlidir ama daha karmaşıktır ve sunucu kaynağı tüketir.

Durumsuz oturum için sıra şudur: bir gizli anahtar üretin ve ortam değişkeni olarak saklayın; oturum verisini imzalayıp doğrulayacak bir kitaplık seçin (dokümanda Jose ve iron-session örnek verilir); çerezi Next.js'in cookies işleviyle sunucuda ayarlayın. Çerezin önerilen seçenekleri şunlardır:

• HttpOnly: İstemci tarafı JavaScript'in çereze erişmesini engeller.
• Secure: Çerezi yalnızca https üzerinden gönderir.
• SameSite: Çerezin siteler arası isteklerle gönderilip gönderilmeyeceğini belirler.
• Expires ya da Max-Age: Çerezin ömrünü sınırlar.
• Path: Çerezin geçerli olduğu yolu belirler.

export async function oturumOlustur(kullaniciId: string) { const bitis = yeniBitisTarihi() const oturum = await sifrele({ kullaniciId, bitis }) const cerezler = await cookies() cerezler.set('oturum', oturum, { httpOnly: true, secure: true, expires: bitis, sameSite: 'lax', path: '/', }) }

Çerezi her zaman sunucuda ayarlayın; istemcide ayarlanan çerez müdahaleye açıktır. Oturum yüküne (payload) yalnızca kullanıcı kimliği ve rol gibi asgari bilgiyi koyun; telefon, e-posta, kart bilgisi ya da şifre koymayın. Çıkış için çerezi silmek yeterlidir, ardından giriş sayfasına yönlendirirsiniz.

Yetkilendirme: korumayı veriye en yakın yerde yapın

Oturum kurulduktan sonra hangi kullanıcının neye erişeceğine karar verirsiniz. Kontroller türlerine ayrılır. İyimser (optimistic) kontrol, çerezdeki oturum verisine bakarak hızlı karar verir; arayüz öğelerini göstermek ya da gizlemek, kullanıcıyı yönlendirmek için uygundur. Güvenli kontrol ise veritabanındaki oturum ve kullanıcı verisine bakar; hassas veri ve işlemler için bu kullanılmalıdır.

Dokümantasyonun önerdiği yapı, kontrolleri tek yerde toplayan bir veri erişim katmanıdır (DAL). Bu katmandaki oturum doğrulama fonksiyonu geçerli bir oturum yoksa kullanıcıyı giriş sayfasına yönlendirir, varsa gerekli kullanıcı bilgisini döndürür:

import 'server-only' import { cache } from 'react'

export const oturumuDogrula = cache(async () => { const cerez = (await cookies()).get('oturum')?.value const oturum = await coz(cerez) if (!oturum?.kullaniciId) { redirect('/giris') } return { girisYapti: true, kullaniciId: oturum.kullaniciId } })

Bu fonksiyonu sayfalarda, Server Action'larda ve Route Handler'larda çağırırsınız. Yetkisiz isteklere Route Handler'da uygun yanıt kodlarıyla (kimliği doğrulanmamış ya da yetkisi olmayan) dönersiniz.

Bir tuzağa dikkat: layout'lar sayfa geçişlerinde yeniden çizilmez; bu yüzden oturum kontrolünü yalnızca layout'ta yapmak her rota değişikliğinde çalışmaz. Kontrolü veriye ve kullanıcıya hassas bileşene yakın yapın. Yine de bunu tek başına yeterli saymayın: SPA'lerde sık görülen 'yetkisizse layout'ta null döndür' kalıbı Next.js'te önerilmez, çünkü iç segmentlere ve Server Action'lara başka yollarla erişilebilir.

Proxy ile iyimser yönlendirme

Tüm rotalarda çalışan Proxy, oturum çerezine bakıp yetkisiz kullanıcıyı giriş sayfasına yönlendirmek için uygundur. Korumalı ve herkese açık yolları tanımlar, çerezdeki oturumu çözer ve gerekirse yönlendirirsiniz. Proxy, ön yüklenen rotalar dahil her rotada çalıştığı için yalnızca çerezi okumalı, veritabanına gitmemelidir; yoksa performans düşer. Dokümantasyona göre Proxy Node.js çalışma zamanını kullanır, kullandığınız kimlik doğrulama ve oturum kitaplıklarının buna uyumlu olduğundan emin olun.

Proxy tek başına savunma hattı olmamalıdır. Güvenlik kontrollerinin çoğu veriye mümkün olduğunca yakın yapılmalıdır; Proxy bir ilk filtredir. Arkasından veri erişim katmanındaki güvenli kontrol gelir.

Veriyi istemciye döndürürken yalnızca gerekli alanları içeren sade nesneler (DTO) kullanın. Kullanıcı kaydının tamamını arayüze geçirmek, şifre karması ya da telefon gibi alanları sızdırma riskini artırır. Yetkiye göre değişen alanlar için küçük bir sunucu fonksiyonu yazın: 'bu görüntüleyen kişi telefonu görebilir mi' sorusunu orada çözün.

Hazır kitaplık mı, elle kurulum mu?

Elle kurulum akışı öğretir, ama üretimde çoğu zaman bakım yükü getirir: şifre sıfırlama, e-posta doğrulama, sosyal giriş, çok adımlı doğrulama, oturum yenileme ve denetim kayıtlarının hepsi sizin sorumluluğunuza girer. Hazır bir kitaplık bu parçaların çoğunu hazır getirir.

Seçerken şu soruları sorun: Kullanıcı verisi nerede tutulacak, kendi veritabanınızda mı yoksa sağlayıcıda mı? Hangi giriş yöntemleri gerekiyor (e-posta-şifre, sosyal hesap, kurumsal tek oturum)? Rol ve izin modeli gerekiyor mu? Kullandığınız Next.js sürümü ve Proxy çalışma zamanı ile uyumlu mu? Sağlayıcı bağımlılığı ve veri taşınabilirliği sizin için ne kadar önemli?

Kitaplık kullansanız bile veri erişim katmanı ve yetki kontrolü kuralları geçerliliğini korur: kitaplık size oturumu verir, hangi kullanıcının hangi kaydı görebileceğini ise uygulamanız belirler. Sürüm uyumluluğu için kitaplığın kendi dokümantasyonunu kontrol edin.

Sık hatalar ve kontrol listesi

• Yetkiyi yalnızca arayüzde gizlemek: Server Action ve Route Handler kendi içinde doğrulama yapmalıdır.
• Çerezi istemcide ayarlamak ya da HttpOnly vermemek: Oturum çalınmaya açık hâle gelir.
• Oturum yüküne hassas veri koymak: Yalnızca asgari kimlik bilgisini taşıyın.
• Kontrolü yalnızca layout'ta yapmak: Geçişlerde yeniden çalışmaz.
• Proxy'de veritabanı sorgusu yapmak: Her rotada çalıştığı için yavaşlatır.
• Tüm kullanıcı nesnesini arayüze geçirmek: Sadece gerekli alanları döndürün.
• Gizli anahtarı koda yazmak: Ortam değişkeni kullanın ve depoya koymayın.

Yayına çıkmadan önce şunu deneyin: oturumu kapatın ve korumalı bir yola doğrudan gidin, giriş sayfasına yönlendiriliyor musunuz? Başka bir kullanıcının kayıt kimliğini adrese yazın, erişim reddediliyor mu? Server Action'ı form dışından tetikleyin, yetki kontrolü çalışıyor mu? Çıkıştan sonra çerez gerçekten siliniyor mu?

Bu beceriyi Mindset programlarında nerede çalışırsınız

Next.js ile Full-Stack Web Uygulamaları programındaki Kimlik Doğrulama ve Yetkilendirme modülü bu konuya ayrılmıştır. Veri değiştirme ve form akışları modülü giriş formunun temelini, App Router mimarisi modülü ise korumalı rotaların kurulacağı yapıyı sağlar.

İç portal, müşteri paneli ya da yönetim aracı geliştiren ekipler için bu sıra, giriş akışını ve yetkilendirme kurallarını ürün ekibinin ortak diline çevirmeye elverişlidir.