Laravel Sanctum ve Passport: Doğru API Yetkilendirmesini Seçmek

Laravel ile bir API geliştirirken ilk hafta içinde karşılaşacağınız önemli bir karar: Sanctum mı yoksa Passport mu? Bu seçim, görünüşte küçük bir paket tercihine benziyor ama daha büyük bir soruyu da beraberinde getiriyor—bu API’yi kimler tüketiyor ve onlarla ne kadar güven ilişkisi kurmanız gerekiyor? Yanlış bir seçim yaparsanız, kimsenin istemediği bir OAuth2 sunucusu kurmakla haftalar harcayabilir veya yol haritanızda vaat ettiğiniz üçüncü parti entegrasyonlarını desteklemeyen bir token sistemi ortaya çıkarabilirsiniz. Bu yazıda, broşür özetinden kaçınıp doğrudan üretim kararına odaklanıyoruz: Her paketin ne için kullanıldığını, ekiplerin bu seçimi neden yanlış değerlendirdiğini ve yanlış seçim durumunda nasıl geçiş yapacağınızı ele alıyoruz.

Sanctum Nedir?

Laravel Sanctum, iki senaryo için hafif bir kimlik doğrulama paketidir: “birinci parti” SPA’lar veya mobil uygulamalar – yani hem frontend hem de backend’i kontrol ediyorsanız – ve makine-arası kullanım için basit API tokeni düzenleme. Sanctum OAuth2 uygulamaz: ne yetkilendirme sunucusu, ne onay ekranı, ne de istemci kaydı yoktur. Size iki mekanizma sunar: aynı üst düzey alan adı için cookie tabanlı oturum kimlik doğrulaması ve hashed-at-rest tokenler için personal_access_tokens tablosu.

Bu sadelik tam da mesele. Sanctum, Passport’un çoğu “kendi frontend’imiz kendi API’mizle iletişim kuruyor” durumu için gereksiz olduğu için var. app.yourcompany.com adresinden bir React veya Vue SPA geliştiriyorsanız ve api.yourcompany.com ile iletişim kuruyorsanız veya sadece şirketinizin gönderdiği bir mobil uygulama geliştiriyorsanız, Sanctum size süresiz bir süreç olmadan çözüme ulaştırır.

Passport Nedir?

Laravel Passport, League OAuth2 Server paketine dayalı tam bir OAuth2 sunucusu uygulamasıdır: istemci kaydı, yetkilendirme kodları, yenileme tokenleri, kapsamlar ve token iptali, kendi şemasına dayanır. Passport’un var olma nedeni, kontrol etmediğiniz uygulamaların kullanıcı adına API’nize erişimini sağlamaktır. Bu, “kendi SPA’m giriş yapacak” sorunundan farklıdır. API’niz bir platform olduğunda, değil sadece kendi istemciniz için bir backend.

SPA Cookie Kimlik Doğrulaması ve API Tokenleri: Doğru Sanctum Modunu Seçme

Sanctum, iki kimlik doğrulama şeklini destekler ve yanlış olanı seçmek gerçek sorunlar yaratır. Cookie tabanlı SPA kimlik doğrulaması, SPA ve API’nin aynı üst düzey alan adını paylaştığı durumlar içindir. Laravel, giriş yaptıktan sonra şifrelenmiş, HttpOnly bir oturum cookie’si verir ve Sanctum’un EnsureFrontendRequestsAreStateful middleware’i, yapılandırılmış SPA alanları aracılığıyla isteklere oturum yerine token ile kimlik doğrulaması yapar—bu durum, token’in frontend JavaScript’inize dokunmadığı anlamına gelir, bu da XSS saldırı yüzeyini önemli ölçüde azaltır.

API tokenleri ise diğer her şey içindir: mobil uygulamalar, CLI araçları, sunucu-arası entegrasyonlar ve cookie alan adınızı paylaşmayan herhangi bir istemci. En yaygın hata, ekiplerin kendi birinci parti SPA’ları için gereksiz bir şekilde API tokenleri kullanmasıdır; bu daha fazla kod demektir, bir token’in tarayıcıda bir yerde yaşaması gerekir ve frontend ile backend aynı ise cookie tabanlı kimlik doğrulama yöntemine göre size bir avantaj sağlamaz.

Birinci Parti ve Üçüncü Parti Tüketiciler: Gerçek Karar Noktası

Özellik karşılaştırmalarını bir kenara bırakın ve kararınızı tek bir soruya indirgeyin: API’niz çağrıldığında, onu siz inşa edip dağıttığınız uygulamalar mı var, yoksa başkaları tarafından geliştirilenler mi? Sadece birinci parti uygulamalar varsa, Sanctum neredeyse her zaman doğrudur — bu, gerçek projelerin çoğunu kapsar: bir şirketin kendi web uygulaması ve kendi iOS/Android uygulamaları, dahili bir admin paneli yerel API’ye hitap eden veya tek resmi istemcisi olan bir SaaS ürünü.

Üçüncü parti tüketicilerle karşılaşırsanız, Passport (veya eşdeğeri bir OAuth2 sunucusu) gereklidir. Bu, diğer firmaların entegre olduğu bir platform inşa ettiğinizde, bir kullanıcı adına hareket eden partner uygulamaların bulunduğu bir pazar yeri veya “Hesabınızı bağlayın” gibi gerçek, kararlı bir yol haritası özelliğine sahip her üründe kendini gösterir.

Kod: Sanctum SPA Kimlik Doğrulama Ayarı

// config/sanctum.php
'stateful' => explode(',', env(
    'SANCTUM_STATEFUL_DOMAINS',
    'localhost,localhost:3000,app.yourcompany.com'
)),
'guard' => ['web'],

// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
    $middleware->statefulApi();
})

// routes/api.php
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn (Request $request) => $request->user());
});

SPA, CSRF korumasını etkinleştirmek üzere GET /sanctum/csrf-cookie isteğini gönderir; ardından giriş formunu withCredentials: true (Axios) veya credentials: 'include' (fetch) ile göndererek oturum cookie’sinin otomatik olarak gönderilmesini sağlar.

Kod: Sanctum API Token İhraç Etme

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([=> []]);
    }

    $token = $user->createToken(
        $request->device_name,
        [,,]
    );

    return response()->json([=> $token->plainTextToken]);
}

Dikkat edilmesi gereken nokta, açık metin değerinin yalnızca oluşturma zamanında mevcut olduğudur—Sanctum veritabanında SHA-256 hash’ini saklar, bu nedenle bu yanıtı, istemcinin bunu yakalama şansı olarak değerlendirin.

Kod: Passport İstemci Kimlik Bilgileri İzni Ayarı

Kullanıcı müdahalesi olmadan bir partnerin arka ucunun kimlik doğrulaması yaptığı makine-arası entegrasyonlar için:

// AuthServiceProvider.php
use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::tokensCan([
        => ,
        => ,
    ]);
}

// routes/api.php
Route::middleware([
    ,
    ,
])->get(, [ReportController::class, ]);

Partnerın sunucusu, bir tarayıcı yönlendirmesi olmaksızın doğrudan bir token talep eder ve Passport, bu istemciye ve belirlenen kapsam ayarına bağlı bir token verir; entegrasyon devre dışı bırakıldığında bunu bağımsız olarak iptal edebilirsiniz.

OAuth2 İzin Türleri ve Ne Zaman Gerekli Olduğu

Passport, standart OAuth2 izinlerinin tamamını destekler, ancak çoğu proje sadece bir veya iki tanesine ihtiyaç duyar. Yetkilendirme kodu izni, bir kullanıcının oturum açtığı ve açıkça onay verdiği üçüncü parti uygulamalar için standart akıştır; güvenli bir gizli anahtarı olamayan kamu istemcileri için PKCE varyantını kullanın. Şifre izni, güvenilir bir birinci parti istemcinin doğrudan bir token almak için bir kullanıcı adı ve parolayı değiştirmesi için bir öncül sunar; basitliği ile cezbetse de, istemcinin ham kimlik bilgilerini işlemesini gerektirir – bu, OAuth2’nin temel güvenlik amacını ihlal eder. Eğer bunu kullanma gereği hissediyorsanız, muhtemelen Sanctum’a yönelmelisiniz. İstemci kimlik bilgileri izni, kullanıcının bulunmadığı makine-arası kimlik doğrulama içindir; eğer projeniz sadece bu izni gerektiriyorsa, Passport’a ulaşmadan önce Sanctum’un API tokenlerini düşünün; çünkü bunlar aynı “hizmet hesabı” amacını çok daha az kurulum ile sunar.

Sanctum ve Passport Arasında Geçiş

Her iki paket de kimlik doğrulanmış bir User modelini sergiler ve tokenCan() tarzı kontrolleri destekler, dolayısıyla bu iki paket arasında geçiş yapmak, insanların beklentilerinden daha az kodu etkiler — sıkıntı, neredeyse tamamen kimlik doğrulama katmanındadır, iş mantığınızda değil. Sanctum’dan Passport’a geçiş genellikle Passport’u Sanctum ile birlikte kurmak, passport:install komutunu çalıştırmak, şifreleme anahtarlarını üretmek için ilk OAuth2 istemcilerinizi kaydetmek, mevcut Sanctum yeteneklerinizi yansıtan AuthServiceProvider‘da kapsam tanımlamak ve yeni yüzey için yetkilendirme kodu akışını oluşturmayı içerir. Passport’tan Sanctum’a geçmek ise hangi OAuth2 istemcilerinin gerçekten birinci parti, hangilerinin harici olduğunu denetlemeyi, yetkilendirme kodu akışını Sanctum’un doğrudan token ihraç etmesiyle değiştirmeyi ve Passport’un oauth_* tablolarını, rotalarını ve paketi kaldırmayı gerektirir.

Karar Çerçevesi

Tartışmayı üç soruyla keskinleştirin; bunları gerçek yol haritanız hakkında dürüstçe yanıtlayın: Sizden almayı planladığınız bir uygulama kullanıcı onayına ihtiyaç duyacak mı? Her istemci—web, mobil, CLI—kendi ekibiniz tarafından mı gönderiliyor? Harici geliştiriciler için bir onay ekranına, istemci kaydına veya iptal arayüzüne ihtiyaç var mı? En sık gördüğümüz desen, ekiplerin “OAuth2” terimi doğru cevapmış gibi düşünerek ilk günden Passport’a yönelmesi, ardından birinci parti bir müşteri için yetkilendirme sunucusu sağlamakla haftalar harcamasıdır.

Sanctum ve Passport, aynı özelliğin rakip uygulamaları değildir—farklı güven problemlerini çözerler. Sanctum, her istemciyi güvenilir kabul eder çünkü onu siz inşa ettiniz; Passport, böyle bir güven ilişkisi kurmanın mümkün olmadığı anlar için vardır. Çoğu Laravel API’si, iddialı olanlar da dahil olmak üzere, yalnızca birinci parti uygulamalar içerir ve bu gerçek olduğu sürece Sanctum ile kalmalısınız.