Node.js İle Çoklu Kullanıcı İçin Jwt Tabanlı Oturum Yönetimi Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Bu rehberde başarılı olabilmek için bilgisayarınızda Node.js (LTS sürümü 22 veya üzeri) kurulu olmalıdır. Projemizi başlatmak için bir klasör oluşturun ve gerekli paketleri yükleyin. Güvenlik için jsonwebtoken, bcryptjs ve dotenv paketlerini kullanacağız.

mkdir jwt-auth-app
cd jwt-auth-app
npm init -y
npm install express jsonwebtoken bcryptjs dotenv

Yukarıdaki komutlar, projenin temel yapısını oluşturur ve gerekli bağımlılıkları yükler. bcryptjs, parolaları güvenli bir şekilde hashlemek (şifrelemek) için kullanılırken, jsonwebtoken token üretimi ve doğrulaması için gereklidir.

Adım 1: Kullanıcı Kaydı ve Parola Güvenliği

Kullanıcı verilerini saklamadan önce parolaları düz metin olarak değil, hashlenmiş bir şekilde saklamalıyız. Bu, veritabanı sızıntısı durumunda kullanıcı hesaplarının korunmasını sağlar.

const bcrypt = require('bcryptjs');

const registerUser = async (email, password) => {
    const saltRounds = 12; // 2026 standartlarında 12 ve üzeri önerilir
    const hashedPassword = await bcrypt.hash(password, saltRounds);
    
    // Kullanıcıyı veritabanına kaydetme mantığı buraya gelecek
    console.log("Hashlenmiş parola:", hashedPassword);
    return hashedPassword;
};

Bu kodda bcrypt.hash fonksiyonu, parolayı rastgele bir 'salt' değeri ile birleştirerek tek yönlü bir şifreleme yapar. saltRounds değerinin 12 olması, brute-force saldırılarına karşı güncel bir güvenlik önlemidir.

Adım 2: JWT Üretimi ve Giriş İşlemleri

Kullanıcı doğru bilgilerle giriş yaptığında, ona benzersiz bir JWT göndeririz. Bu token, kullanıcının kimliğini kanıtlayan dijital bir imza görevi görür.

const jwt = require('jsonwebtoken');
require('dotenv').config();

const generateToken = (user) => {
    return jwt.sign(
        { id: user.id, role: user.role }, 
        process.env.JWT_SECRET, 
        { expiresIn: '1h' }
    );
};

Burada process.env.JWT_SECRET, token imzalarken kullanılan gizli anahtardır. Bu anahtarı asla kod içerisinde paylaşmayın ve mutlaka .env dosyasında tutun. expiresIn özelliği, tokenin geçerlilik süresini 1 saat ile sınırlar.

Adım 3: Middleware ile Yetkilendirme Kontrolü

Korumalı rotalara erişimi kontrol etmek için bir "middleware" (ara yazılım) oluşturmalıyız. Bu fonksiyon, her istekte başlıkları (headers) kontrol ederek tokenin geçerli olup olmadığını denetler.

const verifyToken = (req, res, next) => {
    const token = req.headers['authorization']?.split(' ')[1];

    if (!token) return res.status(403).json({ message: "Token gerekli!" });

    jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
        if (err) return res.status(401).json({ message: "Geçersiz token!" });
        req.user = decoded;
        next();
    });
};

Bu middleware, Authorization: Bearer formatındaki başlığı okur. Eğer token geçersizse veya süresi dolmuşsa, 401 Unauthorized hatası döndürür. Başarılı olursa, kullanıcı bilgilerini req.user nesnesine ekleyerek bir sonraki fonksiyona iletir.

JWT Tabanlı Mimari Karşılaştırması

Kritik Güvenlik Uyarısı: JWT'lerinizi asla tarayıcıda localStorage içerisinde saklamayın; bu XSS saldırılarına davetiye çıkarır. Bunun yerine, tokenleri HttpOnly ve Secure bayrakları ile işaretlenmiş çerezlerde (cookies) tutun.

Adım 4: Çoklu Kullanıcı Rol Yönetimi

Farklı kullanıcı türleri (Admin, Editör, Kullanıcı) için yetkilendirme yaparken, token içerisine gömdüğümüz 'role' bilgisini kullanabiliriz.

const authorizeRole = (role) => {
    return (req, res, next) => {
        if (req.user.role !== role) {
            return res.status(403).json({ message: "Bu işlem için yetkiniz yok." });
        }
        next();
    };
};

// Kullanımı:
app.get('/admin', verifyToken, authorizeRole('admin'), (req, res) => {
    res.send("Admin paneline hoş geldiniz.");
});

Bu yaklaşım, rotalarınızı dinamik olarak korumanıza olanak tanır. authorizeRole fonksiyonu, middleware zincirinde verifyToken'dan sonra çalışarak kullanıcının rolünü doğrular.

Sıkça Sorulan Sorular

JWT süresi dolduğunda ne yapmalıyım?

Kullanıcıyı tekrar giriş yapmaya zorlamak yerine, "Refresh Token" mekanizması kullanmalısınız. Kısa ömürlü bir Access Token ve uzun ömürlü bir Refresh Token ile kullanıcı deneyimini kesintisiz tutabilirsiniz.

Token çalınırsa nasıl iptal edebilirim?

JWT'ler stateless olduğu için anında iptal edilemezler. Bunu aşmak için bir "Blacklist" (kara liste) mekanizması kurarak, çıkış yapan veya şüpheli görülen tokenleri Redis gibi hızlı bir veritabanında saklayıp her istekte kontrol edebilirsiniz.

JWT içeriği şifreli midir?

Hayır, JWT sadece Base64 ile kodlanmıştır. İçerisine asla parola veya hassas kişisel veriler (TCKN, kredi kartı vb.) koymayın. Sadece kullanıcı ID ve rol gibi tanımlayıcı bilgiler ekleyin.

HTTPS kullanımı zorunlu mu?

Evet, tokenlerin ağ üzerinden çalınmasını (man-in-the-middle) önlemek için üretim ortamında mutlaka HTTPS protokolü kullanmalısınız.

Node.js sürümü JWT performansını etkiler mi?

Node.js'in güncel sürümleri, kriptografik işlemler için daha optimize edilmiş kütüphanelerle gelir. 2026 yılı itibarıyla performans darboğazı yaşamamak için güncel LTS sürümünü kullanmanız kritik önem taşır.

JWT Tabanlı Sistemlerde Hata Ayıklama ve Loglama Stratejileri

JWT süreçlerinde yaşanan hatalar genellikle "401 Unauthorized" veya "403 Forbidden" yanıtlarıyla sonuçlanır. Ancak bu hataların kaynağını tespit etmek, özellikle dağıtık sistemlerde karmaşık olabilir. Hata ayıklama sürecini hızlandırmak için merkezi bir loglama mekanizması kurmak hayati önem taşır.

Öncelikle, token doğrulama hatalarını ayırt etmek için özel hata sınıfları tanımlayabilirsiniz:

// customError.js
class AuthError extends Error {
  constructor(message, statusCode) {
    super(message);
    this.statusCode = statusCode;
  }
}

// middleware içinde kullanım
const verifyToken = (req, res, next) => {
  const token = req.headers['authorization']?.split(' ')[1];
  if (!token) return next(new AuthError('Token bulunamadı', 401));
  
  jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
    if (err) {
      if (err.name === 'TokenExpiredError') {
        return next(new AuthError('Oturum süresi doldu', 401));
      }
      return next(new AuthError('Geçersiz token', 403));
    }
    req.user = decoded;
    next();
  });
};

Ayrıca, geliştirme ortamında jsonwebtoken kütüphanesinin sağladığı hata detaylarını loglarken, üretim ortamında kullanıcıya sadece genel hata mesajları dönerek "bilgi sızıntısı" (information disclosure) riskini minimize etmelisiniz.

JWT Performansını Optimize Etme ve Ölçeklendirme

JWT'ler her istekte sunucuya gönderildiği için, token boyutunun küçük tutulması ağ trafiğini ve işlemci yükünü doğrudan etkiler. Performansı artırmak için şu stratejileri uygulayabilirsiniz:

• Payload Boyutunu Küçültün: Token içine sadece gerekli olan userId ve role gibi bilgileri ekleyin. Büyük JSON nesnelerini token içinde taşımaktan kaçının.
• Algoritma Seçimi: HS256 (simetrik) yerine RS256 (asimetrik) kullanarak, token doğrulama işlemini yük dengeleyiciler (load balancer) veya mikroservis katmanlarında, anahtarı ifşa etmeden yapabilirsiniz.
• Önbellekleme (Caching): Token doğrulama işlemi sırasında veritabanına gidip kullanıcı rolünü kontrol ediyorsanız, bu bilgiyi Redis üzerinde önbelleğe alarak veritabanı sorgu sayısını azaltın.

Aşağıdaki tablo, farklı senaryolarda tercih edilmesi gereken JWT stratejilerini özetlemektedir:

Bu optimizasyonlar, özellikle eşzamanlı kullanıcı sayısının arttığı durumlarda uygulamanızın yanıt sürelerini (latency) korumanıza yardımcı olacaktır.

Sonuç

Node.js ile JWT tabanlı oturum yönetimi, doğru yapılandırıldığında oldukça güvenli ve ölçeklenebilir bir yöntemdir. Parola güvenliği, token imzalama süreçleri ve rol tabanlı erişim kontrolü, uygulamanızın temelini oluşturur. Bu adımları izleyerek profesyonel standartlarda bir kimlik doğrulama sistemi kurabilirsiniz.

Yasal Uyarı: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Üretim (production) ortamına geçmeden önce mutlaka kapsamlı güvenlik testleri yapın, bağımlılıklarınızı düzenli güncelleyin ve veri gizliliği yasalarına (KVKK/GDPR) uygunluk sağlayın.

Bir sonraki adımda, Redis kullanarak "Refresh Token" rotasyonunu ve token kara listeleme sistemini projenize entegre etmeyi deneyebilirsiniz.