Laravel Passport ve Sanctum: Hangisine Gerçekten İhtiyacınız Var?

Kaynak: hafiz.dev

Kısa Yanıt

Pek çok Laravel projesi için Sanctum uygun bir seçenektir. SPA, mobil uygulama veya basit API token kimlik doğrulaması için kullanın. Passport, yalnızca üçüncü tarafa geliştiricilerin API’nize OAuth2 erişimi gerektiğinde gereklidir.

Her iki çözümü de kullanarak üretim uygulamaları geliştirdim. StudyLab (500’den fazla okul tarafından kullanılan bir AI quiz oluşturucu) projemde Sanctum’u tercih ettim. API, web uygulamamız ve potansiyel mobil istemcilerimiz için hizmet vermekte. Tüm erişim içsel. Dış geliştiricilerin API erişimi talep etmesi söz konusu değil. Sanctum’u kurmak yaklaşık 5 dakikamı aldı ve o zamandan beri en ufak bir problem yaşamadım.

İşte karar cümlesi: Eğer üçüncü taraf geliştiriciler için halka açık bir API platformu inşa etmiyorsanız, Sanctum kullanın.

Hızlı Karşılaştırma: Sanctum vs Passport

Bu tablo, çoğu hikayeyi anlatıyor. Ama ayrıntılara inelim.

Laravel Sanctum Nedir?

Sanctum, Laravel’in SPAs, mobil uygulamalar ve basit token tabanlı API’ler için hafif kimlik doğrulama paketidir. 8.x sürümünden itibaren Laravel ile varsayılan olarak birlikte gelir ki bu, Laravel ekibinin çoğu proje için neyi önerdiğine dair bir işaret verir.

Sanctum, iki farklı kimlik doğrulama senaryosunu ele alır:

1. Oturum Tabanlı Kimlik Doğrulama (SPAs)

Frontend’iniz Laravel backend’inizle aynı alanda olduğunda, Sanctum Laravel’in yerleşik oturum kimlik doğrulamasını kullanır. SPA’nız /sanctum/csrf-cookie adresine bir istek gönderir, CSRF tokenını alır ve sonra standart giriş uç noktasından kimliğini doğrular. Yönetilecek token yok. LocalStorage güvenlik endişeleri yok. Sadece çerezler.

2. Token Tabanlı Kimlik Doğrulama (Mobil Uygulamalar & API’ler)

Mobil uygulamalar için veya istemcinin çerezleri kullanamaması durumunda, Sanctum kişisel erişim tokenları verir. Bunlar, veritabanınızda saklanan basit, opak dizelerdir. Bunları Authorization başlığında gönderebiliyorsunuz ve Sanctum, bunları personal_access_tokens tablosuna göre doğruluyor.

Kurulumun ne kadar basit olduğunu görelim:

php artisan install:api

// Yetkiler (scopes) ile bir token oluşturma
$token = $user->createToken('mobile-app', ['posts:read', 'posts:write']);
return $token->plainTextToken;

// Rotaları koruma
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/user', fn(Request $request) => $request->user());
    Route::get('/posts', [PostController::class, 'index']);
});

// Kontrolcünüzde yetkileri kontrol etme
if ($request->user()->tokenCan('posts:write')) {
    // Kullanıcı post oluşturabiliyor
}

// Token iptal etme
$user->tokens()->delete(); // Tüm tokenlar
$user->currentAccessToken()->delete(); // Sadece mevcut token

Bu kadar. OAuth istemcileri oluşturma, şifreleme anahtarları yaratma, yetkilendirme türlerini anlama yok.

ReplyGenius Chrome uzantım için, Laravel backend ile kimlik doğrulama yapmak için bu token tabanlı yaklaşım mükemmel oldu. Uzantı tokenı saklıyor, her istekte gönderiyor ve OAuth2 akışları ya da yenileme tokenları hakkında hiç düşünmem gerekmiyor.

Laravel Passport Nedir?

Passport, Laravel’in tam OAuth2 sunucu uygulamasıdır. League OAuth2 Sunucu paketi üzerine inşa edilmiştir ve tam bir OAuth2 yetkilendirme sunucusu çalıştırmak için gereken her şeyi sağlar.

Bu, Twitter API’si veya Stripe API’si gibi bir şey inşa ettiğinizde önemlidir. Dış geliştiriciler uygulamalar oluşturur, kullanıcılar bu uygulamaları yetkilendirir ve tokenlar doğru OAuth2 akışları üzerinden verilir.

Passport, tüm standart OAuth2 yetkilendirme türlerini destekler:

Yetkilendirme Kodu Yetkilendirmesi – Standart OAuth2 akışı. Üçüncü taraf uygulamalar kullanıcıları sitenize yönlendirir, kullanıcılar erişimi onaylar, siteniz kod ile geri döner ve uygulama o kodu tokenlara dönüştürür. Bu, “GitHub ile Giriş Yap” veya “Slack’a Bağlan” tıkladığınızda gördüğünüz şeydir.

İstemci Kimlik Bilgisi Yetkilendirmesi – Makineden makineye kimlik doğrulama. Kullanıcı yok. Bir sunucu diğerine konuşur. Microservisler veya arka uç entegrasyonları için mükemmel.

Şifre Yetkilendirmesi – Kullanıcı, kullanıcı adı ve şifreyi doğrudan istemci uygulamasına sağlar. Genelde önerilmez çünkü üçüncü taraf uygulamanın kullanıcı kimlik bilgilerini yönetmesini gerektirir.

Yenileme Tokenları – Erişim tokenleri süresi doluyor. Yenileme tokenları, istemcilerin kullanıcıyı yeniden yetkilendirmeden yeni erişim tokenları almalarına izin verir.

İşte Passport kurulumu:

// Kurulum
php artisan install:api --passport

// Kullanıcı modelinizde
use Laravel\Passport\Contracts\OAuthenticatable;
use Laravel\Passport\HasApiTokens;
use Carbon\CarbonInterval;

class User extends Authenticatable implements OAuthenticatable
{
    use HasApiTokens, HasFactory, Notifiable;
}

// Token yetkilerini AuthServiceProvider'da tanımlayın
public function boot(): void
{
    Passport::tokensCan([
        'read-posts' => 'Kendi postlarınızı okuyun',
        'write-posts' => 'Post oluşturun ve güncelleyin',
        'delete-posts' => 'Postlarınızı silin',
    ]);

    // Opsiyonel: Token süresini ayarlayın
    Passport::tokensExpireIn(CarbonInterval::days(15));
    Passport::refreshTokensExpireIn(CarbonInterval::days(30));
}

// Kişisel erişim tokenı oluşturma (Sanctum'a benzer)
$token = $user->createToken('My Token', ['read-posts'])->accessToken;

// Rotaları koruma
Route::middleware('auth:api')->group(function () {
    Route::get('/user', fn(Request $request) => $request->user());
});

Farklılıkları dikkatinize sunun? Daha fazla hareketli parça var. Daha fazla yapılandırma. Daha fazla veritabanı tablosu. Passport, OAuth istemcileri oluşturur, token şifreleme anahtarlarını yönetir ve tam OAuth2 akışlarını yürütür.

Ne Zaman Sanctum Kullanmalıyım?

API’nizi tüketen tüm istemcileri kontrol ediyorsanız Sanctum’u kullanın. Bu, anahtar bir içgörü.

SPA’nız Laravel uygulamanızla aynı yerdedir. Aynı ekip, aynı kod tabanı (ya da en azından aynı organizasyon). Rastgele geliştiricilerin üzerinde çalışacakları bir API yayınlamıyorsunuz. Kendinize ait bir ürün inşa ediyorsunuz.

Mobil uygulamanız birinci taraf. Laravel backend’inizle konuşan iOS veya Android uygulamasını geliştiriyorsunuz. Uygulama üçüncü taraf entegrasyonu değil; ürününüzün bir parçasıdır.

Basit API tokenlarına ihtiyacınız var. Belki kullanıcıların kendi verilerine erişmek için API anahtarları oluşturduğu bir servis geliştiriyorsunuz. Kullanıcı kontrolünde otomasyon veya entegrasyonlar için kişisel erişim tokenlarına benzer şekilde düşünün.

Minimum karmaşıklık istiyorsunuz. Sanctum, iki kavramı anlamayı gerektirir: oturum çerezleri ve bearer tokenları. Passport, kendi RFC belgeleri olan bir spesifikasyon olan OAuth2’yi anlamayı gerektirir.

StudyLab’ın API’sini oluşturduğumda, karar belirgindi. Okullar platforma web uygulamamız üzerinden erişiyor. Öğretmenler arayüzümüzü kullanıyor. Öğrenciler arayüzümüzü kullanıyor. Eğer sonra bir mobil uygulama üretirsek, onu da yaparız. Hiçbir okul, sağladığımız API üzerinden StudyLab’ı kendi özel LMS’sine entegre etme talebinde bulunmuyor.

Sanctum. Tamam.

Kurulum yaklaşık 5 dakikamı aldı. OAuth2 akışlarını hatalarını gidererek veya bir token yenilemesinin neden başarısız olduğunu açıklamaya harcadım.

Ne Zaman Passport Kullanmalıyım?

Passport, belirli senaryolarda karmaşıklığını hak kazanır. İşte gerçekten ihtiyaç duyduğunuz durumlar:

Üçüncü taraf geliştiriciler API’niz üzerinden inşa edecekler. Bir platform yaratıyorsunuz. Diğer şirketler veya geliştiriciler, kullanıcılarınızın verilerine erişen uygulamalar oluşturacak. Shopify uygulamaları, Slack entegrasyonları veya GitHub OAuth uygulamaları gibi düşünün.

OAuth2 uyumluluğuna ihtiyacınız var. Bazı kurumsal müşterilerin OAuth2 gereksinimi vardır. Bu, tedarik listesine dahildir. Kimlik doğrulamanız spesifikasyona uymalı, uygun JWT tokenlarını vermeli ve standart OAuth2 son noktalarını desteklemelidir.

Bir kamu API platformu inşa ediyorsunuz. Geliştiricilerin uygulamaları kaydetmelerini, istemci kimlik bilgilerini almalarını ve uygun yetkilendirme akışlarından geçmelerini istiyorsanız. İstemci başına oran sınırlandırması, uygulama özel kapsamlar ve belirli üçüncü taraf uygulamaları için erişimi geri alma yeteneğine ihtiyacınız var.

Makineden makineye kimlik doğrulama. Laravel uygulamanız, kullanıcının dahil olmadığı diğer arka uç hizmetlerinden gelen istekleri kimlik doğrulamak zorundadır. İstemci Kimlik Bilgisi yetkilendirmesi bunun temiz bir şekilde üstesinden gelir.

Somut bir örnek: Eğer StudyLab, okulların özel panolar inşa etmesine veya sınav verilerini mevcut sistemlerine entegre etmesine izin veren bir kamu API’si sunuyorsa, Passport’a ihtiyacım olurdu. Bu entegrasyonlar üçüncü taraf uygulamalardır. Okul yöneticileri adına erişim talep etmek zorunda kalacaklardı. OAuth2 akışları yetkilendirmeyi düzgün bir şekilde yönetecektir.

Fakat StudyLab böyle bir şey sunmuyor. Bu nedenle Passport’u kullanmıyorum.

İkisini Birlikte Kullanabilir Misin?

Evet. Ama muhtemelen buna ihtiyacınız yok.

Bunun mantıklı olduğu senaryo: hem birinci taraf SPA (Sanctum) hem de üçüncü taraf geliştiricilere açık bir API sunuyorsunuz (Passport). Farklı istemciler, farklı kimlik doğrulama mekanizmaları ve farklı rota grupları.

// routes/api.php

// Birinci taraf SPA rotaları - Sanctum
Route::middleware('auth:sanctum')->prefix('v1')->group(function () {
    Route::get('/user', [UserController::class, 'show']);
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

// Üçüncü taraf API rotaları - Passport
Route::middleware('auth:api')->prefix('public/v1')->group(function () {
    Route::get('/user', [PublicApiUserController::class, 'show']);
    Route::get('/posts', [PublicApiPostController::class, 'index']);
});

Pratikte bu tür bir yapılandırmaya hiç ihtiyaç duymadım. Eğer bunu düşünüyorsanız, kendinize sorun: Gerçekten iki farklı API tüketici türüm var mı, yoksa gereksiz karmaşıklık mı yaratıyorum?

Passport’tan Sanctum’a Geçiş

Geliştiricilerin projenin başında Passport’u seçip daha sonra OAuth2’ye ihtiyaç duymadıklarını düşündüklerini sık görüyorum. Eğer yalnızca kişisel erişim tokenları kullanıyorsanız, geçiş oldukça basittir.

Adım 1: Sanctum zaten kurulu

Laravel 8’den itibaren Sanctum varsayılan olarak gelir. config/sanctum.php‘nın var olduğundan emin olun. Değilse:

php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

Adım 2: Kullanıcı modelinizi güncelleyin

// Önce (Passport)
use Laravel\Passport\HasApiTokens;

// Sonra (Sanctum)
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens;
}

Aynı trait adı, farklı ad alanı. Kullanışlı.

Adım 3: Kimlik doğrulama korumanızı güncelleyin

config/auth.php dosyasında:

'guards' => [
    'api' => [
        'driver' => 'sanctum', // 'passport' yerine değiştirildi
        'provider' => 'users',
    ],
],

Adım 4: Rota middleware’ini güncelleyin

// Önce
Route::middleware('auth:api')->group(...);

// Sonra (her ikisini de kullanabilirsiniz)
Route::middleware('auth:sanctum')->group(...); 
// Ya da koruma yapılandırmanızı güncellediyseniz 'auth:api' yı da kullanabilirsiniz.

Adım 5: Token oluşturmayı güncelleyin

// Passport
$token = $user->createToken('name', ['scope'])->accessToken;

// Sanctum 
$token = $user->createToken('name', ['ability'])->plainTextToken;

Farkı dikkate alın: Passport ->accessToken dönerken, Sanctum ->plainTextToken döner.

Adım 6: Passport’u temizleyin

Paketi ve veritabanı tablolarını kaldırın:

composer remove laravel/passport
php artisan migrate:rollback --path=vendor/laravel/passport/database/migrations

Detaylı bir şekilde test edin. Mevcut tokenlarınız artık farklı tablolarda ve farklı formatlarda depolandıkları için çalışmayacaktır. Kullanıcıların tekrar kimlik doğrulaması yapmalarını planlayın.

Kaçınılması Gereken Yaygın Hatalar

1. Sanctum yeterliyken Passport kullanmak

Bu büyük bir sorun. OAuth2 etkileyici geliyor. Ancak çoğu uygulama için gereksiz bir karmaşıklık. Eğer halka açık bir API platformu inşa etmiyorsanız, gereksiz bir mühendislik yapıyorsunuz.

2. Sanctum SPAs ile CSRF korumasını unutmak

Sanctum’un oturum tabanlı kimlik doğrulamasını SPAs ile kullanırken, EnsureFrontendRequestsAreStateful middleware’ını eklemeniz gerekir. Bunun olmaması durumunda, SPA istekleriniz oturum çerezlerini düzgün şekilde dahil etmeyecektir.

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

// Laravel 10 ve öncesi
// 'api' middleware grubuna ekleyin:
\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,

3. Token yetkilerini ayarlamamayı

Tokenlarınızı her zaman kapsamlayın. İç uygulamalar için bile.

// Kötü
$token = $user->createToken('api')->plainTextToken;

// İyi
$token = $user->createToken('api', ['posts:read', 'posts:write'])->plainTextToken;

Eğer bir token ele geçirilirse, sınırlı yetkiler zararı azaltır.

4. Tokenları güvensiz bir şekilde depolamak

SPAs için aynı alanda, Sanctum’un oturum tabanlı kimlik doğrulamasını kullanın. LocalStorage’da token yok. Auth kimlik bilgilerin için XSS riski yok.

Mobil uygulamalar için güvenli depolama kullanın. iOS Keychain. Android Keystore. Plain metin içinde SharedPreferences değil.

5. Çıkışta tokenları iptal etmemek

// Çıkış denetleyicinizde
public function logout(Request $request)
{
    $request->user()->currentAccessToken()->delete();
    return response()->json(['message' => 'Logged out']);
}

Kullanıcılar, çıkışın gerçekten çıkış yapması gerektiğini bekler. Geçerli tokenların etrafta dolaşmasına izin vermeyin.

Sıkça Sorulan Sorular

Sanctum üretim için yeterince güvenli mi?

Evet. Sanctum Laravel çekirdek ekibi tarafından geliştirilmekte ve binlerce üretim uygulamasında kullanılmaktadır. Güvenlik besten pratiklerini takip eder ve tokenlar saklanmadan önce şifrelenir. Oturum tabanlı kimlik doğrulama için Laravel’in test edilmiş oturum sistemini kullanır.

Passport’tan Sanctum’a geçebilir miyim?

Evet. Eğer yalnızca kişisel erişim tokenları kullanıyorsanız ve OAuth2 özellikleri kullanmıyorsanız, geçiş basittir. Yukarıdaki geçiş kılavuzuna bakın. Yapmanız gereken asıl iş, Kullanıcı modelinizi güncellemek ve token oluşturma çağrılarını değiştirmektir.

Mobil uygulamalar için hangisi daha iyi?

Sanctum. Mobil uygulamanızın üçüncü taraf hizmetlerle OAuth2 akışları üzerinden kimlik doğrulaması yapmasına ihtiyacı yoksa, Sanctum’un token tabanlı kimlik doğrulaması daha basit ve tamamen yeterlidir. Mobil uygulama arka uçlarım için hepsinde bunu kullanıyorum.

Passport projem için aşırı mı?

Muhtemelen, eğer bu soruyu soruyorsanız. Passport, OAuth2 sunucu işlevselliği için vardır. Üçüncü taraf uygulamalara OAuth2 tokenları vermeniz gerekmiyorsa, Passport’a ihtiyacınız yok. Sanctum’u kullanın.

JWT hakkında ne düşünüyorsunuz? Tymon/jwt-auth yerine bunu mu kullanmalıyım?

Pek çok Laravel uygulaması için hayır. Sanctum, token kimlik doğrulamasını karmaşıklık olmadan temiz bir şekilde yönetir. JWT’lerin belirli kullanım durumları (durumsuz kimlik doğrulama, çapraz hizmet kimlik doğrulaması) vardır, ancak token yenileme, iptal ve güvenlik etrafında karmaşıklık ekler. Sanctum’un yaklaşımı (veritabanında doğrulanan opak tokenlar), daha basit ve tipik uygulamalar için harika çalışır.

Sanctum birden fazla cihazı yönetebilir mi?

Evet. Her createToken() çağrısı yeni bir token oluşturur. Kullanıcılar, telefon, tablet ve masaüstü cihazlarındaki tokenlara sahip olabilirler. Aynı zamanda tokenları adlandırarak, kullanıcıların erişimi iptal etmesi gerektiğinde cihazları tanımlamalarına yardımcı olabilirsiniz.

Sonuç

Yıllarca Laravel uygulamaları geliştirdikten sonra dürüst değerlendirmem şudur:

Sanctum’u kullanın. %90 proje için doğru seçimdir. SPA’nız kimlik doğrulama gerektiriyor. Mobil uygulamanız tokenlara ihtiyaç duyuyor. İç araçlarınız API erişimine ihtiyaç duyuyor. Sanctum, bunun hepsini minimum kurulumla ve sıfır OAuth2 karmaşasıyla yönetir.

Passport’u yalnızca üçüncü taraf geliştiricilerin kullanıcılarınızın verilerine erişim sağladıkları bir platform oluşturuyorsanız kullanın. Bu belirli bir kullanımdır. Çoğumuz, bir sonraki Stripe veya GitHub’ı inşa etmiyoruz.

Bunu yaşadım. Laravel yolculuğumun başlarında, Passport’a uzanırdım çünkü daha “tam” görünüyor. Daha fazla özellik daha iyi olmalı, değil mi? Yanlış. Kullanmadığınız özellikler, yönettiğiniz karmaşıklıklardır.

Sanctum, Laravel ekibinin çoğu API kimlik doğrulamasının OAuth2 gerektirmediğini fark etmeleri nedeniyle var. Onların yargısına güvenin. Ben yapıyorum.

İhtiyaçlarınız değişirse ve gerçekten OAuth2’ye ihtiyacınız olursa, geçiş mümkündür. Ancak hiç olmayacak bir gelecekten karmaşıklık ödünç almayın.

Basit başlayın. Sanctum kullanın.

İlgili Okuma:

Resmi Dokümantasyon: