Laravel 11 ile Sanctum Token Tabanlı API Kimlik Doğrulama Nasıl Yapılır?

1. Giriş ve Karşılaşılan Temel Zorluklar

Geleneksel web projelerindeki session ve cookie mekanizmaları, mobil uygulamalar (Flutter, Swift) ve harici SPA istemcileri için stateless API dünyasında yetersiz kalır. OAuth2 standartları gereksiz karmaşık olabildiğinden, Sanctum bu noktada ideal bir köprüdür.

Modern kurumsal yazılım mimarisinde bu adımı doğru tasarlamak; hem uygulamanın bakım maliyetini (maintainability) düşürür hem de gelecekteki ölçekleme (scaling) süreçlerinde refactor ihtiyacını en aza indirir. Bu rehberde, sektörde kabul görmüş standartlar ışığında adım adım uygulamayı ele alıyoruz.

2. Ortam Hazırlığı ve Gerekli Bağımlılıklar

Geliştirmeye başlamadan önce sistem ortamınızın ve ilgili paketlerin hazır olduğundan emin olmalısınız. Terminalinizde aşağıdaki komutları çalıştırarak ilgili yapılandırmayı tamamlayın:

• Adım: Terminalde 'php artisan install:api' çalıştırarak Sanctum ve API rotalarını aktifleştirin.
• Adım: User modeline 'Laravel\Sanctum\HasApiTokens' trait'ini ekleyin.
• Adım: Migrasyonları çalıştırmak için 'php artisan migrate' komutunu yürütün.

3. Uygulama Mimarisi ve Kod Örneği

Aşağıdaki kod bloğunda, temiz kod (Clean Code) prensiplerine ve SOLID standartlarına uygun olarak tasarlanmış örnek implementasyonu inceleyebilirsiniz:

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class AuthController extends Controller
{
    public function login(Request $request)
    {
        $request->validate([
            'email' => 'required|email',
            'password' => 'required',
            'device_name' => 'required|string',
        ]);

        $user = User::where('email', $request->email)->first();

        if (! $user || ! Hash::check($request->password, $user->password)) {
            throw ValidationException::withMessages([
                'email' => ['Geçersiz kimlik bilgileri.'],
            ]);
        }

        $token = $user->createToken($request->device_name)->plainTextToken;

        return response()->json([
            'status' => 'success',
            'token' => $token,
            'user' => $user->only(['id', 'name', 'email']),
        ]);
    }
}

4. Kod Analizi ve Çalışma Mantığı

Bu controller'da istemcinin cihaz adı ile SHA-256 hash'lenmiş güvenli token oluşturulur. Yanıt olarak istemciye bir kez gösterilecek açık token döndürülür.

Yukarıdaki implementasyonda dikkat edilmesi gereken en kritik husus, işlemlerin bağımsız (decoupled) ve test edilebilir şekilde katmanlara ayrılmış olmasıdır. Bu yaklaşım, birim testlerin (Unit Tests) ve entegrasyon testlerinin hızlıca yazılabilmesine olanak tanır.

5. Performans ve Güvenlik İpuçları

Canlı üretim (production) ortamında sistemin kararlı çalışması için aşağıdaki pratikleri mutlaka dikkate almalısınız:

• config/sanctum.php içinde expiration süresini mutlaka sınırlayın.
• Hassas endpoint'ler için token abilities/scopes tanımlayarak yetki alanını daraltın.
• Kullanıcı şifre değişikliklerinde eski tokenleri topluca iptal edin.

6. En Sık Yapılan Hatalar ve Hata Ayıklama (Troubleshooting)

Kullanıcı çıkış yaparken tüm tokenleri silmek yerine sadece 'currentAccessToken()->delete()' metodunu çağırmalısınız; aksi takdirde diğer cihazlar da düşer.

Eğer beklenmedik bir hata ile karşılaşırsanız; öncelikle log dosyalarını incelemeli, ortam değişkenlerinin (.env) doğru tanımlandığını doğrulamalı ve önbellek (cache) mekanizmalarını temizleyerek sistemi yeniden başlatmalısınız.

7. Sonuç ve Mimari Değerlendirme

Sanctum, orta ve büyük ölçekli REST mimarilerinde düşük sunucu yükü ile maksimum güvenlik sağlayan standarttır.

Cengiz Bozdemir olarak 18 yılı aşkın kurumsal yazılım mimarlığı deneyimimle tavsiyem; sistem tasarımında her zaman sürdürülebilirlik, güvenlik ve yüksek eşzamanlılık (high concurrency) hedeflerini ön planda tutmanızdır. Kurumsal projelerinizde özel mimari danışmanlık veya uçtan uca yazılım geliştirme desteği için bizimle iletişime geçebilirsiniz.