OAuth 2.0 ve JWT ile Web Uygulamalarında Güvenli Kimlik Doğrulama Rehberi

Modern web ve mobil mimarilerinde güvenlik, sistem tasarımlarının merkezinde yer almaktadır. Mikroservis yapılarının, tek sayfalı uygulamaların (SPA) ve mobil istemcilerin yaygınlaşmasıyla birlikte geleneksel oturum (session) tabanlı kimlik doğrulama yöntemleri yetersiz kalmaya başlamıştır. Bu noktada OAuth 2.0 ve JWT standartları, dağıtık sistemlerde güvenli, ölçeklenebilir ve esnek bir kimlik doğrulama ve yetkilendirme altyapısı kurmanın temel taşı haline gelmiştir. Bu rehberde, OAuth 2.0 ve JWT kullanarak endüstri standartlarında güvenli bir mimarinin nasıl tasarlanacağını, kod seviyesinde nasıl uygulanacağını ve sık yapılan güvenlik açıklarının önüne nasıl geçileceğini adım adım inceleyeceğiz.

OAuth 2.0 ve JWT Temelleri: Farklar ve Birlikte Çalışma Mantığı

Geliştiriciler arasında sıklıkla karıştırılan iki kavram olan OAuth 2.0 ve JWT, aslında aynı sistemin iki farklı boyutunu temsil eder. Aralarındaki farkı ve birlikte nasıl çalıştıklarını anlamak, mimari kararları doğru almak için kritik öneme sahiptir.

OAuth 2.0, bir yetkilendirme (authorization) çerçevesidir (framework). Bir uygulamanın, kullanıcının parolasını paylaşmak zorunda kalmadan başka bir servisteki kaynaklara erişmesine izin veren standart bir protokoldür (RFC 6749). Örneğin, bir web uygulamasının kullanıcının Google kişilerine erişmek istemesi veya kullanıcının "Google ile Giriş Yap" butonuna basması OAuth 2.0 akışı üzerinden gerçekleşir. OAuth 2.0 bir jeton (token) biçimi tanımlamaz; jetonların nasıl taşınacağını ve erişim haklarının nasıl yönetileceğini belirler.

JWT (JSON Web Token) ise RFC 7519 ile standartlaştırılmış, taraflar arasında veriyi güvenli bir şekilde JSON formatında taşımaya yarayan bir jeton yapısıdır. Kendinden kapsüllenmiş (self-contained) bir yapıya sahiptir; yani kimlik doğrulama için gerekli tüm verileri (kullanıcı ID, rolleri, son geçerlilik tarihi) kendi içerisinde barındırır.

Özetle; OAuth 2.0 trafiği ve yetkilendirme adımlarını yöneten yol haritasıdır, JWT ise bu yolculukta taşınan güvenli pasaportun kendisidir.

OAuth 2.0 ve JWT Akışları (Grant Types) ve Doğru Akış Seçimi

OAuth 2.0 içerisinde farklı kullanım senaryoları için tanımlanmış yetkilendirme akışları bulunmaktadır. 2026 yılı itibarıyla güvenlik standartlarında ciddi revizyonlar yapılmış ve eski, güvensiz akışlar tamamen terk edilmiştir.

1. Authorization Code Grant (PKCE ile)

İşleyiş adımları şu şekildedir:

• İstemci rastgele bir code_verifier dizisi oluşturur ve bunun SHA-256 özetini alarak code_challenge üretir.
• Kullanıcı yetkilendirme sunucusuna yönlendirilirken code_challenge parametresi gönderilir.
• Kullanıcı giriş yaptıktan sonra istemciye bir authorization_code döner.
• İstemci, bu kodu ve ilk oluşturduğu code_verifier değerini sunucuya göndererek yetkilendirmeyi tamamlar ve JWT erişim jetonunu (Access Token) alır.

2. Client Credentials Grant

Kullanıcı müdahalesi gerektirmeyen, sunucudan sunucuya (machine-to-machine) veya arka plan mikroservislerinin birbiriyle haberleştiği senaryolarda tercih edilir. İstemci kendi kimlik bilgileri (client_id ve client_secret) ile jeton talep eder.

Terk Edilmesi Gereken Eski Akışlar

• Implicit Grant: Jeton doğrudan URL fragment üzerinden döndüğü için yönlendirme geçmişi veya zararlı betikler tarafından kolayca ele geçirilebilir. Kesinlikle kullanılmamalıdır.
• Resource Owner Password Credentials (ROPC): Kullanıcı adı ve parolanın doğrudan istemciye verilmesini gerektirir. Güvenlik prensiplerine aykırıdır.

JWT (JSON Web Token) Anatomisi ve İmzalama Yöntemleri

Bir JWT üç ana parçadan oluşur ve her parça Base64Url algoritması ile kodlanarak noktalarla (.) birleştirilir:

header.payload.signature

Header (Başlık)

Jetonun tipi ve imzalama algoritması bilgilerini içerir:

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload (Veri Alanı)

Sistemdeki iddiaların (claims) bulunduğu kısımdır. Standart ve özel tanımlı veriler yer alabilir:

{
  "sub": "usr_849201",
  "iss": "https://auth.yazilim-sisteminiz.com",
  "aud": "https://api.yazilim-sisteminiz.com",
  "exp": 1773532800,
  "iat": 1773529200,
  "role": "editor"
}

Here, exp (expiration time), iss (issuer), aud (audience) ve sub (subject) alanlarının mutlaka doğrulanması gerekir.

Signature (İmza)

Header ve Payload alanlarının birleştirilip gizli bir anahtar veya özel anahtar (private key) ile imzalanmasıyla elde edilir. Bu imza, verinin yolda değiştirilmediğini (integrity) garanti eder.

HS256 vs. RS256 Seçimi

• HS256 (Symmetric): Tek bir gizli anahtar (secret key) hem imzalama hem doğrulama için kullanılır. Mikroservis mimarilerinde her servise gizli anahtar dağıtmak riskli olduğundan tekil monolithic yapılar için uygundur.
• RS256 (Asymmetric): Yetkilendirme sunucusu bir Private Key ile imzalar, veriyi doğrulayan servisler ise Public Key kullanır. Dağıtık mimariler ve mikroservisler için RS256 veya ES256 kullanımı zorunludur.

Projenizi Next.js 15 ile Web Uygulaması Geliştirme: Başlangıç Rehberi içeriğinde anlattığımız modern mimarilere entegre ederken, API rotalarını doğrularken asimetrik imzalama tercih etmeniz mimari güvenliği artıracaktır.

Uygulamalı Mimari Kurulumu: Güvenli Token Üretimi ve Doğrulaması

Uygulamanızda Python veya Node.js tabanlı bir backend mimarisi kurarken, JWT üretim ve doğrulama mantığını katmanlı bir yapıda kurgulamalısınız. Python ile Programlamaya Başlama Rehberi süreçlerinden tanıdık geleceği üzere, doğru kütüphanelerle standartlara uygun kod yazmak oldukça pratik bir süreçtir.

Aşağıda Python (PyJWT kütüphanesi) kullanarak RS256 algoritması ile güvenli bir Access Token üretimi ve doğrulamasını gösteren somut bir örnek verilmiştir:

import jwt
import datetime

# Private ve Public Key tanımları (Gerçek senaryoda pem dosyalarından okunmalıdır)
PRIVATE_KEY = open("private.pem", "r").read()
PUBLIC_KEY = open("public.pem", "r").read()

def generate_access_token(user_id: str, role: str) -> str:
    now = datetime.datetime.now(datetime.timezone.utc)
    payload = {
        "sub": user_id,
        "role": role,
        "iss": "https://auth.siteniz.com",
        "aud": "https://api.siteniz.com",
        "iat": now,
        "exp": now + datetime.timedelta(minutes=15)
    }
    token = jwt.encode(payload, PRIVATE_KEY, algorithm="RS256")
    return token

def verify_access_token(token: str) -> dict:
    try:
        decoded = jwt.decode(
            token,
            PUBLIC_KEY,
            algorithms=["RS256"],
            audience="https://api.siteniz.com",
            issuer="https://auth.siteniz.com"
        )
        return decoded
    except jwt.ExpiredSignatureError:
        raise ValueError("Erişim jetonunun süresi dolmuş.")
    except jwt.InvalidTokenError:
        raise ValueError("Geçersiz jeton doğrulaması.")

JWT doğrulaması sırasında imzanın yanında exp, iss ve aud kontrolünün eksiksiz yapıldığından emin olunmalıdır. Ayrıca tüm bu trafiğin güvenli kanal üzerinden akması şarttır. Web sunucunuzdaki HTTPS trafiğini yapılandırmak için Let's Encrypt ile Ücretsiz SSL Sertifikası Kurulumu (Certbot Rehberi) yazımızdan yararlanabilirsiniz.

Token Saklama Stratejileri: XSS ve CSRF Saldırılarına Karşı Korumalar

JWT ve OAuth 2.0 kullanırken mimarinin patladığı en kritik nokta, istemci tarafında jetonların nerede saklanacağıdır. İki temel yöntem mevcuttur:

1. localStorage veya sessionStorage (GÜVENSİZ)

Erişim jetonunu JavaScript belleğinde veya localStorage içinde saklamak, uygulamanızı XSS (Cross-Site Scripting) saldırılarına tamamen açık hale getirir. Sayfaya sızan zararlı bir üçüncü taraf script (<script> etiketi veya tahrif edilmiş bir npm paketi) localStorage.getItem('token') komutuyla kullanıcının tüm yetkilerini çalabilir.

2. httpOnly ve SameSite Cookie (GÜVENLİ)

En güvenli yaklaşım, JWT'yi httpOnly, Secure ve SameSite=Strict (veya Lax) bayraklarına sahip bir çerez (cookie) içinde saklamaktır:
• httpOnly: Çerezin JavaScript (document.cookie) üzerinden okunmasını engeller. XSS ile jeton çalınamaz.
• Secure: Çerezin yalnızca HTTPS bağlantıları üzerinden gönderilmesini sağlar.
• SameSite=Strict: Çerezin siteler arası isteklerde (CSRF) gönderilmesini engeller.

Refresh Token Rotasyonu ve Token İptal (Revocation) Mekanizmaları

JWT'nin en büyük avantajı (self-contained olması) aynı zamanda en büyük dezavantajıdır: Bir JWT imzalandıktan sonra, süresi dolana kadar veritabanına bakılmaksızın geçerlidir. Jeton çalındığında saldırgan süresi bitene kadar sisteme erişebilir.

Bu riski minimize etmek için iki aşamalı bir mekanizma kurulmalıdır:

Refresh Token Rotasyonu Senaryosu

İptal edilen Refresh Token'ların takibi için Redis gibi bellek içi (in-memory) veri depolarında kısa süreli bir kara liste (blacklist) tutulması performansı etkilemeden tam güvenlik sağlar.

OAuth 2.0 ve JWT Kullanırken Yapılan 5 Kritik Güvenlik Hatası

Geliştiricilerin sıklıkla düştüğü ve sistemleri zafiyete açık hale getiren hatalar şunlardır: