Laravel İle Apı Kimlik Doğrulama Katmanı Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Bu uygulamayı gerçekleştirmek için sisteminizde PHP 8.4 veya üzeri bir sürümün ve Laravel 11/12 framework'ünün kurulu olması gerekmektedir. Veritabanı yönetimi için MySQL veya PostgreSQL kullanmanız önerilir.

• PHP 8.4+
• Laravel 12.x
• Composer paket yöneticisi
• Postman veya Insomnia (API testleri için)

Projeyi kurduktan sonra terminal üzerinden gerekli paketleri doğrulamak için şu komutu çalıştırın:

php artisan --version

Eğer sürümünüz 11.0'ın altındaysa, güncel güvenlik yamalarından faydalanmak için projenizi yükseltmeniz şiddetle tavsiye edilir.

Laravel Sanctum ile API Yetkilendirme Kurulumu

Laravel Sanctum, SPA (Single Page Application) ve basit API'ler için hafif bir kimlik doğrulama sistemi sunar. Sanctum, her kullanıcıya API tokenları atayarak oturum yönetimi yapmanıza olanak tanır.

Öncelikle Sanctum paketini projenize dahil edin ve yapılandırma dosyalarını yayınlayın:

composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate

Bu işlemler, veritabanınızda personal_access_tokens tablosunu oluşturacaktır. Bu tablo, kullanıcıların API anahtarlarını saklamak için kullanılır.

User Modelinde Yetkilendirme Özelliğini Aktif Etme

Kullanıcı modelinizin token oluşturabilmesi için HasApiTokens trait'ini (özellik kümesini) kullanması gerekir. Bu trait, token oluşturma ve doğrulama metotlarını modele ekler.

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
    // Diğer özellikler...
}

Bu yapılandırma, Laravel'in yerleşik kimlik doğrulama mekanizması ile Sanctum'un birbirine entegre çalışmasını sağlar.

Kullanıcı Girişi ve Token Oluşturma Adımları

Kullanıcıların sisteme giriş yapıp bir token alabilmesi için bir AuthController oluşturmalıyız. Bu kontrolcü, gelen kimlik bilgilerini doğrular ve başarılıysa bir token döndürür.

public function login(Request $request)
{
    $request->validate([
        'email' => 'required|email',
        'password' => 'required',
    ]);

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

    if (!$user || !Hash::check($request->password, $user->password)) {
        return response()->json(['message' => 'Geçersiz bilgiler'], 401);
    }

    $token = $user->createToken('api-token')->plainTextToken;

    return response()->json(['token' => $token], 200);
}

Burada Hash::check metodu, veritabanındaki şifrelenmiş (bcrypt/argon2) veri ile kullanıcının gönderdiği şifreyi güvenli bir şekilde karşılaştırır.

API Rotalarını Koruma Altına Alma

Oluşturduğunuz token'ların geçerli olup olmadığını kontrol etmek için rotalarınızı auth:sanctum ara katmanına (middleware) bağlamalısınız. routes/api.php dosyasını şu şekilde güncelleyin:

use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

Bu rota, sadece geçerli bir Authorization: Bearer {token} başlığı ile gönderilen istekleri kabul eder.

API Kimlik Doğrulama Yöntemlerinin Karşılaştırılması

Projeniz için en uygun yöntemi seçerken aşağıdaki tabloyu referans alabilirsiniz:

Kritik Güvenlik Uyarısı: API tokenlarınızı hiçbir zaman istemci tarafında (localStorage gibi) güvensiz bir şekilde saklamayın. Üretim ortamında (production) mutlaka HTTPS kullanın ve token ömürlerini makul seviyelerde tutun.

Sıkça Sorulan Sorular

API token'ı nasıl iptal edilir?

Kullanıcının mevcut token'ını silmek için $user->tokens()->delete(); metodunu kullanarak tüm oturumları sonlandırabilirsiniz.

Token süresi nasıl ayarlanır?

Sanctum konfigürasyon dosyasında expiration değerini dakika cinsinden belirterek token ömrünü kısıtlayabilirsiniz.

Neden Passport yerine Sanctum tercih etmeliyim?

Eğer uygulamanız sadece kendi mobil uygulamanız veya web arayüzünüz ile konuşuyorsa, Sanctum çok daha hızlı ve kolay yönetilebilir bir yapıdır.

Hatalı token gönderildiğinde ne olur?

Laravel otomatik olarak 401 Unauthorized yanıtı döndürür; bu davranışı bootstrap/app.php üzerinden özelleştirebilirsiniz.

Token'a yetki (ability) nasıl eklenir?

$user->createToken('token-adi', ['server:update'])->plainTextToken; şeklinde kapsamlı yetkilendirme tanımlayabilirsiniz.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Uygulamanızın canlı ortam güvenliğinden geliştirici olarak siz sorumlusunuz. SQL injection ve XSS gibi saldırılara karşı Laravel'in sunduğu ORM ve Blade korumalarını kullanmaya devam edin.

API İsteklerini Rate Limiting ile Sınırlandırma

API güvenliğinin en önemli ayaklarından biri, kötü niyetli kullanıcıların veya botların sisteminizi aşırı yüklemesini engellemektir. Laravel, RouteServiceProvider içerisinde tanımlı olan throttle middleware'i ile bu süreci oldukça kolaylaştırır.

API rotalarınızda belirli bir kullanıcı veya IP adresi için istek sınırını şu şekilde yapılandırabilirsiniz:

use Illuminate\Support\Facades\RateLimiter;

// app/Providers/RouteServiceProvider.php içerisinde
RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

Bu yapılandırma, kimliği doğrulanmış kullanıcılar için kullanıcı ID'sine göre, misafir kullanıcılar için ise IP adresine göre dakikada 60 istek sınırı koyar. Sınır aşıldığında Laravel otomatik olarak 429 Too Many Requests hatasını döndürür.

API Hata Ayıklama ve Loglama Stratejileri

API üzerinde kimlik doğrulama sorunlarını çözmek bazen karmaşık olabilir. Hangi kullanıcının hangi token ile hangi rotaya erişmeye çalıştığını takip etmek için Laravel'in Log facade'ini kullanmak en iyi pratiktir.

Özellikle kimlik doğrulama başarısız olduğunda tetiklenen olayları yakalamak için AuthServiceProvider içerisinde bir listener tanımlayabilirsiniz:

use Illuminate\Support\Facades\Event;
use Illuminate\Auth\Events\Failed;
use Illuminate\Support\Facades\Log;

public function boot()
{
    Event::listen(Failed::class, function ($event) {
        Log::warning('API Kimlik doğrulama başarısız oldu.', [
            'user' => $event->user?->email,
            'ip' => request()->ip(),
            'agent' => request()->userAgent()
        ]);
    });
}

Yaygın Hata Kodları ve Çözümleri

API geliştirirken karşılaşabileceğiniz temel durumlar ve HTTP karşılıkları şöyledir:

• 401 Unauthorized: Token geçersiz veya hiç gönderilmemiş. Authorization header'ını kontrol edin.
• 403 Forbidden: Token geçerli ancak kullanıcının bu kaynağa erişim yetkisi (ability) yok.
• 419 Authentication Timeout: CSRF koruması aktif olan rotalarda oturum süresi dolmuş.

API Deployment ve Güvenlik İpuçları

Uygulamanızı canlı ortama alırken (production), API güvenliğini artırmak için aşağıdaki adımları mutlaka uygulayın:

1. HTTPS Kullanımı: Token'lar düz metin olarak iletilir. SSL sertifikası olmadan API'niz "Man-in-the-Middle" saldırılarına açıktır.
2. Environment Değişkenleri: .env dosyanızda APP_DEBUG=false olduğundan emin olun. Hata ayıklama modu açıkken API hataları veritabanı şemanızı ifşa edebilir.
3. Token Rotasyonu: Kullanıcıların token'larını belirli aralıklarla yenilemelerini zorunlu kılan bir mekanizma geliştirin.
4. Trusted Proxies: Eğer API'niz bir Load Balancer veya Cloudflare arkasındaysa, App\Http\Middleware\TrustProxies dosyasını yapılandırarak gerçek IP adreslerinin doğru loglanmasını sağlayın.

Profesyonel İpucu: API'nizin performansını ölçmek için Laravel Telescope kullanabilirsiniz. Telescope, her bir isteğin ne kadar sürede tamamlandığını ve hangi veritabanı sorgularının çalıştığını görselleştirerek darboğazları tespit etmenize yardımcı olur.

Sonuç

Laravel ile API kimlik doğrulama katmanı oluşturmak, Sanctum sayesinde oldukça standart ve güvenli bir süreç haline gelmiştir. Bu rehberde öğrendiğiniz temel yapıları, uygulamanızın ihtiyaçlarına göre genişletebilirsiniz. Bir sonraki adım olarak, API'nize "Rate Limiting" (istek sınırlama) ekleyerek sisteminizi kötü niyetli botlara karşı korumayı deneyebilirsiniz.