Laravel İle Restful Apı İçin Token Tabanlı Kimlik Doğrulama Nasıl Yapılır?

Gereksinimler ve Ön Hazırlık

Uygulamaya başlamadan önce sisteminizde PHP 8.2+ ve Laravel 11+ yüklü olmalıdır. Laravel Sanctum, modern API'ler için hafif ve güvenli bir kimlik doğrulama sistemi sunar. Projenizin kök dizininde terminali açarak gerekli kurulumları yapabilirsiniz.

Öncelikle Laravel projenizi oluşturun ve Sanctum paketini projenize dahil edin. Sanctum, API token'ları ve cookie tabanlı oturum yönetimi için gereken tüm altyapıyı sağlar.

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

Bu komutlar, veritabanınızda token'ların saklanacağı personal_access_tokens tablosunu oluşturacaktır. Ardından, User modelinize HasApiTokens trait'ini eklemeniz gerekir.

User Modeline HasApiTokens Trait'inin Eklenmesi

Laravel Sanctum'un kullanıcı üzerinde token oluşturabilmesi için modelin bu yeteneğe sahip olması gerekir. app/Models/User.php dosyasını açın ve ilgili trait'i içe aktarın.

namespace App\Models;

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

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    protected $fillable = ['name', 'email', 'password'];
}

Bu işlem, kullanıcı nesnesi üzerinden $user->createToken('token-adi') metodunu çağırmanıza olanak tanır. Bu metod, istemciye gönderilecek olan ham token değerini döndürür.

Kayıt ve Giriş İşlemleri İçin Controller Yapılandırması

API üzerinden kullanıcıların sisteme giriş yapabilmesi için bir AuthController oluşturmalıyız. Bu controller, kullanıcının kimlik bilgilerini doğrular ve başarılı ise bir token üretir. Güvenlik için Hash::check metodunu kullanarak şifre doğrulaması yapıyoruz.

namespace App\Http\Controllers\Api;

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

class AuthController extends Controller
{
    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 kimlik bilgileri.'], 401);
        }

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

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

Burada plainTextToken özelliği, veritabanında hash'lenmiş olarak saklanan token'ın ham halini sadece bir kez görmenizi sağlar. Bu, güvenlik açısından kritik bir detaydır.

API Rotalarının Korunması

Oluşturduğumuz token'ın API isteklerinde nasıl kullanılacağını tanımlamamız gerekiyor. routes/api.php dosyasında, auth:sanctum middleware'ini kullanarak rotaları koruma altına alıyoruz.

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\Api\AuthController;

Route::post('/login', [AuthController::class, 'login']);

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

İstemci tarafı, isteği gönderirken Authorization: Bearer {token} başlığını (header) eklemelidir. Sanctum bu başlığı otomatik olarak okur ve ilgili kullanıcıyı doğrular.

Güvenlik Uyarısı: API token'larını hiçbir zaman URL parametresi olarak göndermeyin. Her zaman HTTP Authorization başlıklarını (Header) kullanın. Ayrıca, üretim (production) ortamında HTTPS protokolünü zorunlu tutun.

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

Yaygın Hatalar ve Debug İpuçları

Geliştirme sürecinde en sık karşılaşılan hata 401 Unauthorized yanıtıdır. Bu genellikle Authorization başlığının eksik gönderilmesinden veya yanlış formatta olmasından kaynaklanır. postman veya insomnia gibi araçlarla isteklerinizi test ederken "Authorization" sekmesinden "Bearer Token" seçeneğini seçtiğinizden emin olun.

Eğer token'lar veritabanında göründüğü halde sistem kabul etmiyorsa, config/auth.php dosyasındaki guards ayarlarının varsayılan olarak Sanctum'a işaret ettiğini doğrulayın.

Sıkça Sorulan Sorular

Token'ların süresi nasıl kısıtlanır?

Sanctum token'ları varsayılan olarak süresizdir. config/sanctum.php dosyası içerisindeki expiration değerini dakika cinsinden ayarlayarak otomatik geçersiz kılma süresi belirleyebilirsiniz.

Birden fazla cihazdan giriş yapılabilir mi?

Evet, createToken metodu her çağrıldığında yeni bir kayıt oluşturur. Kullanıcılar farklı cihazlardan giriş yapıp farklı token'lara sahip olabilirler.

Token'ı nasıl iptal ederim?

Kullanıcının mevcut tüm token'larını $user->tokens()->delete(); komutu ile veya belirli bir token'ı $user->currentAccessToken()->delete(); ile silebilirsiniz.

API isteklerinde JSON yanıtı zorunlu mu?

Laravel, API isteklerinde Accept: application/json başlığı mevcutsa otomatik olarak JSON yanıtı döner. Bu başlığı her zaman eklemeniz önerilir.

Kullanıcı kayıt işlemini nasıl yaparım?

Kayıt işlemi için User::create metodunu kullanın ve şifreyi Hash::make ile şifrelediğinizden emin olun. Ardından giriş işlemindeki gibi token oluşturup döndürebilirsiniz.

Sorumluluk Reddi: Bu rehberdeki kod örnekleri eğitim amaçlıdır. Uygulamanızın canlı ortamda güvenliğini sağlamak için veritabanı şifreleme, hız sınırlama (rate limiting) ve giriş denemesi kısıtlamaları (brute-force protection) gibi ek güvenlik önlemlerini mutlaka uygulayın.

API İsteklerinde Hata Yönetimi ve Özel Yanıtlar

API geliştirirken, istemci tarafına sadece veriyi değil, aynı zamanda anlamlı hata mesajlarını da iletmek kritik öneme sahiptir. Laravel'in varsayılan hata yakalama mekanizmasını, API'nizin standartlarına göre özelleştirebilirsiniz. Bu, özellikle 401 Unauthorized hatalarında kullanıcıya neden giriş yapamadığını net bir şekilde bildirmek için gereklidir.

app/Exceptions/Handler.php dosyasını düzenleyerek, kimlik doğrulama hatalarını JSON formatında özelleştirebilirsiniz:

use Illuminate\Auth\AuthenticationException;

protected function unauthenticated($request, AuthenticationException $exception)
{
    return response()->json([
        'message' => 'Bu kaynağa erişmek için geçerli bir token gereklidir.',
        'status' => 401
    ], 401);
}

API Performansını Artırmak İçin İleri İpuçları

Token tabanlı kimlik doğrulama, her istekte veritabanı sorgusu tetikleyebilir. Ölçeklenebilir bir API için bu yükü minimize etmek önemlidir. İşte performans iyileştirmeleri için bazı öneriler:

• Cache Kullanımı: Kullanıcı yetkilendirme bilgilerini veya sık erişilen API yanıtlarını Redis veya Memcached üzerinde önbelleğe alın.
• Eager Loading: Kullanıcı bilgilerini çekerken ilişkili verileri with() metodu ile yükleyerek N+1 sorgu sorunlarını engelleyin.
• Token Önbellekleme: Sanctum token'larını veritabanından her seferinde sorgulamak yerine, kısa süreliğine cache üzerinde tutarak veritabanı üzerindeki yükü azaltabilirsiniz.

Rate Limiting (Hız Sınırlama) Uygulaması

API'nizi brute-force saldırılarına karşı korumak için Laravel'in yerleşik hız sınırlama özelliğini kullanın. RouteServiceProvider içerisinde veya doğrudan rota tanımlamalarında bu kısıtlamaları belirleyebilirsiniz:

use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Http\Request;

RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
});

API Testleri: Postman ve PHPUnit

Geliştirdiğiniz API'nin güvenli çalıştığından emin olmak için test süreçlerini otomatize etmelisiniz. PHPUnit kullanarak, korumalı bir rotaya token'sız erişimi test edebilirsiniz:

public function test_api_requires_token()
{
    $response = $this->getJson('/api/user');

    $response->assertStatus(401);
}

public function test_api_works_with_token()
{
    $user = User::factory()->create();
    $token = $user->createToken('test-token')->plainTextToken;

    $response = $this->withHeader('Authorization', 'Bearer ' . $token)
                     ->getJson('/api/user');

    $response->assertStatus(200);
}

Geliştirme aşamasında ise Postman kullanarak "Authorization" sekmesinden "Bearer Token" seçeneğini işaretleyip, oluşturduğunuz token'ı buraya yapıştırarak isteklerinizi test edebilirsiniz. Bu, gerçek dünya senaryolarını simüle etmek için en hızlı yöntemdir.

Sonuç

Laravel ile token tabanlı kimlik doğrulama, API projelerinizin güvenliğini sağlamak için en etkili yoldur. Sanctum'un sunduğu basit yapı, geliştirme hızınızı artırırken güvenli bir standart sağlar. Bu adımları tamamladıktan sonra, bir sonraki aşama olarak API'nize "Rate Limiting" (hız sınırlama) ekleyerek kötü niyetli istekleri engellemeyi öğrenebilirsiniz.