Laravel Artık Yerel Passkey’lere Sahip: laravel/passkeys için Kapsamlı Bir Rehber

Orijinal makale hafiz.dev adresinde yayımlanmıştır.

Uzun bir süre, Laravel uygulamalarına geçiş anahtarları eklemek, üçüncü taraf bir pakete başvurmayı, WebAuthn törenlerini elle bir araya getirmeyi ya da “relying party ID” nedir bilen birinin olduğunu varsayan bir öğreticiyi montajlamayı gerektiriyordu. Ancak bu süreç artık değişti.

Nisan 2026’nın sonlarında, Laravel laravel/passkeys adlı birinci parti paketi sunarak, kutudan çıkar çıkmaz tam bir geçiş anahtarı hikayesi sağladı. Sunucu paketi, npm istemcisi ve Fortify entegrasyonu. Üç parça bir araya geldiğinde, şifre yoktu kimlik doğrulama işlemini kolayca gerçekleştirmek mümkün, işte güvenlik işlevlerinden tam olarak beklediğiniz şey bu.

Ocak ayında Spatie geçiş anahtarları yaklaşımını inceledim, bu hala geçerli, eğer Livewire ağırlıklı bir uygulama yürütüyorsanız veya zaten bu paketi kullanıyorsanız. Ancak, yerel paket yeni projeler ve Fortify kullanan uygulamalar için doğru seçimdir. İşte tam kurulum için adımlar.

laravel/passkeys ile birlikte gelenler

Geçiş anahtarı yığını, her biri belirgin bir sorunu ele alan üç bileşenden oluşur.

laravel/passkeys, sunucu tarafı Composer paketidir. WebAuthn törenlerini yönetir, passkeys veritabanı tablosunu yönetir, giriş, onay ve kimlik bilgisi yönetimi için rotalar kaydeder ve içine kancanızı takabileceğiniz olaylar tetikler. Özel yetkilendirme mantığına veya kendi rota tanımlamalarınıza ihtiyacınız varsa, kurtulma noktaları hazırdır.

@laravel/passkeys, npm istemcisidir. Tarayıcı tarafında tören koordinasyonunu (kaydetme ve doğrulama) yönetir ve React, Vue ve Svelte için SSR güvende kancalarla birinci sınıf yardımcı programlarla gelir, böylece istemciye özgü API’ler çerçeveden bağımsız mücadele etmez. Yayınlanan API iki yöntem içerir: Passkeys.register() ve Passkeys.verify(). Hepsi bu kadar.

Fortify entegrasyonu, her şeyi uygulamanızın konfigürasyonuyla Features::passkeys() aracılığıyla ve config/fortify.php dosyasındaki passkeys bölümünde bağlar. Fortify uygulamaları, aynı uç noktaları, PasskeyUser ve PasskeyAuthenticatable sözleşmelerini yeniden uygulama zorunluluğu olmadan alır.

Paket v0.1.0 sürümündedir ama bu bir kırmızı bayrak değil. Zaten Laravel’in resmi başlangıç kitlerinin varsayılanıdır ve üretimde Fortify tarafından kullanılmaktadır. Sürüm numarası, kamu API’sinin evrilebileceğini gösterir, paketin kararsız olduğunu değil.

Kurulum

Öncelikle Composer paketini yükleyin:

composer require laravel/passkeys

Ardından, passkeys tablosunu oluşturmak için göçleri yayınlayın ve çalıştırın:

php artisan vendor:publish --tag=passkeys-migrations
php artisan migrate

Sonra, kullanıcı tanıtıcılarını türetmek için PASSKEYS_USER_HANDLE_SECRET için .env dosyanıza bir gizli anahtar ekleyin. Bu, kullanıcı kimlikleriniz ardışık tamsayılar olsa bile, geçiş anahtarı ilişkilerini gizli tutar:

PASSKEYS_USER_HANDLE_SECRET=your-random-secret-here

Bir değer oluşturun:

php artisan key:generate --show

Bu çıktıyı gizli anahtar olarak kullanın. Eğer bunu boş bırakırsanız, paket APP_KEY anahtarına geri döner ama bunları ayrı tutmak daha iyi bir uygulamadır. Uygulama anahtarınızı değiştirdiğinizde, kullanıcılar geçiş anahtarlarını kaybetmezler. Tüm referans için mevcut artisan komutlarının referansını Laravel Artisan Komutları referansında bulabilirsiniz.

Kullanıcı Modelinizi Yapılandırma

Kullanıcı modelinize PasskeyUser sözleşmesini ve PasskeyAuthenticatable trait’ini ekleyin:

Bu trait, users tablosunun name ve email sütunlarına sahip olduğunu varsayar. Kimlik doğrulayıcılar, kayıt sırasında ve hesap seçimi sırasında bu değerleri kullanıcı arayüzünde gösterir. displayName name ve email değerlerine geri döner, kimlik doğrulayıcı için tanımlayıcı oluşturarak. Eğer farklı görünüm değerlerine ihtiyacınız varsa, doğrudan model üzerindeki yöntemleri geçersiz kılabilirsiniz:

public function getPasskeyDisplayName(): string
{
    return $this->full_name ?? $this->email;
}

public function getPasskeyUsername(): string
{
    return $this->email;
}

Bu, modelinizin ihtiyaç duyduğu tek değişikliktir. Ek göçler veya pivot tablolar gerekmez. passkeys tablosu kimlik bilgisi depolama işlemini ele alır ve PasskeyAuthenticatable tarafından sizin için ayarlanan standart bir ilişkide kullanıcınıza bağlanır.

Fortify Entegrasyonu

Eğer Laravel Fortify kullanıyorsanız, geçiş anahtarlarını etkinleştirmek için sadece özellikler dizisinde bir satır eklemek yeterli:

use Laravel\Fortify\Features;

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
    Features::passkeys(), // Bunu ekleyin
],

Fortify otomatik olarak geçiş anahtarı rotalarını kaydeder ve sözleşmeleri bağlar. Sunucu tarafında hiçbir şey değişmez. Mevcut yetkilendirme yapılandırmanız politikalarda ve kapılarda aynı kalır; geçiş anahtarları yalnızca kimlik doğrulama adımını değiştirir, sonraki adımları etkilemez.

Konfigürasyon Dosyası

Özelleştirmeye ihtiyaç duyuyorsanız konfigürasyonu yayınlayın:

php artisan vendor:publish --tag="passkeys-config"

config/passkeys.php dosyasında varsayılanlar mantıklıdır:

return [
    'relying_party_id' => parse_url(config('app.url'), PHP_URL_HOST),
    'allowed_origins' => [config('app.url')],
    'user_handle_secret' => env('PASSKEYS_USER_HANDLE_SECRET', config('app.key')),
    'timeout' => 60000,
    'guard' => 'web',
    'middleware' => ['web'],
    'management_middleware' => ['password.confirm'],
    'throttle' => 'throttle:6,1',
    'redirect' => "https://dev.to/",
];

Hangi değişiklikleri yapmadan önce anlamanız gereken birkaç şey var.

relying_party_id, APP_URL'dan türetilen alan adınızdır. Geçiş anahtarları bu değere kriptografik olarak bağlıdır. Tarayıcının eriştiği alan adı eşleşmediğinde, tören başarısız olur. APP_URL'nin, özellikle yerel geliştirmede sunma işleminizi yansıttığından emin olun.

management_middleware varsayılan olarak password.confirm ile ayarlanmıştır, bu, kullanıcıların geçiş anahtarları eklemek veya iptal etmek için yeniden şifrelerini doğrulamalarını gerektirir. Bunu devre dışı bırakmayın. Bu, güvenlik açısından kritik bir eylem için doğru bir friksiyondur. Aynı ilke, duyarlı jeton işlemlerinde de geçerlidir.

throttle, geçiş anahtarı denemelerini dakikada 6 ile sınırlayarak üretim için mantıklıdır. Eğer alışılmadık trafik desenleriniz varsa ayarlarını değiştirebilirsiniz, ama bunu tamamen kaldırmayın.

Paketin Kaydettiği Rotalar

Herhangi bir rotayı siz tanımlamazsınız. Sunucu paketi bu rotaları otomatik olarak kaydeder:

POST   /passkeys/register/options   (kaydetme için seçenek oluştur)
POST   /passkeys/register           (yeni kimlik bilgisi kaydet)
POST   /passkeys/verify/options     (kimlik doğrulama için seçenek oluştur)
POST   /passkeys/verify             (geçiş anahtarı ile kimlik doğrula)
DELETE /passkeys/{passkey}          (belirli bir geçiş anahtarını iptal et)

Eğer özel rota tanımlamaları (farklı ara yazılımlar, ön ekler veya özel denetleyiciler) gerekiyorsanız, yapılandırmada otomatik kaydı devre dışı bırakabilir ve kendi rotalarınızı tanımlayabilirsiniz. Temel eylem sınıflarının hepsi halka açık ve içe aktarılabilir, bu nedenle manuel kontrol aldığınızda herhangi bir işlevselliği kaybetmezsiniz.

WebAuthn Akışının İşleyişi

Ön yüz kodunu yazmadan önce töreni görmek faydalıdır:

Hafiz.dev'deki etkileşimli diyagramı görüntüleyin

Kayıt aynı şekil izler: tarayıcı seçenekleri talep eder, kimlik doğrulayıcı bir anahtar çifti oluşturur, genel anahtar sunucunuzda saklanır. Hassas veriler asla cihazdan ayrılmaz. Özel anahtar ağ üzerinden hiç yolculuk etmez, bu da şifreler üzerindeki temel güvenlik avantajıdır. Veritabanı ihlalinde çalınacak kimlik bilgisi yoktur.

Ön Yüz Entegrasyonu (Vue)

npm istemcisini yükleyin:

npm install @laravel/passkeys
npm run build

İşte hem kayıt (yetkilendirilmiş kullanıcıların geçiş anahtarı eklemesi) hem de giriş (giriş sayfasında) işlemlerini yöneten bir Vue 3 bileşeni:

script setup>
import { ref } from 'vue'
import { Passkeys } from '@laravel/passkeys'

const registering = ref(false)
const verifying = ref(false)
const error = ref(null)

async function registerPasskey() {
    registering.value = true
    error.value = null

    try {
        await Passkeys.register({ name: 'My Device' })
        // Geçiş anahtarı kaydedildi, listeyi yenileyin veya başarıyla ilgili bir bildirim gösterin
    } catch (e) {
        error.value = e.message
    } finally {
        registering.value = false
    }
}

async function loginWithPasskey() {
    verifying.value = true
    error.value = null

    try {
        await Passkeys.verify()
        // Başarıyla yönlendirilir
    } catch (e) {
        error.value = e.message
    } finally {
        verifying.value = false
    }
}
script>

template>
    
 class="space-y-4">
        
         @click="registerPasskey" :disabled="registering" class="btn">
            {{ registering ? 'Kayıt Oluyor...' : 'Geçiş Anahtarı Ekle' }}
        

        
         @click="loginWithPasskey" :disabled="verifying" class="btn">
            {{ verifying ? 'Doğrulanıyor...' : 'Geçiş Anahtarı İle Giriş Yap' }}
        

        
 v-if="error" class="text-red-500 text-sm">{{ error }}
    
template>

Passkeys.register() tarayıcı töreninin tamamını yürütür: /passkeys/register/options adresinden zorluğu alır, kimlik doğrulayıcıyı uyarır ve sonucu sunucuya POST eder. Passkeys.verify() de oturum açma için aynısını yapar ve ardından başarılı olduğunda config/passkeys.php → redirect dosyasında tanımlı yola yönlendirir.

React için, içe aktarma ve API aynıdır. Svelte yardımcı programları da aynı deseni izler. Paket, @simplewebauthn/browser tören karmaşasını temiz iki yöntemli bir arayüz etrafında soyutlar; bu, WebAuthn uzmanı olma niyetinde olmadığınızda istediğiniz şeydir.

Kayıtlı Geçiş Anahtarlarını Yönetme

Kullanıcıların geçiş anahtarlarını görme ve iptal etme yeteneğine sahip olmaları gerekir. Bu, insanların beklediğinden daha fazla önem taşır. Kullanıcılar dizüstü bilgisayarlarında, telefonlarında ve iş makinelerinde kayıtlıdır, sonra neden üç giriş olduğunu merak ederler. Onlara düzenleme yapma araçlarını vermek önemlidir.

Temel bir kontrolör bunun gibi görünür:

// PasskeyController.php
use Illuminate\Http\Request;
use Laravel\Passkeys\Models\Passkey;

class PasskeyController extends Controller
{
    public function index(Request $request)
    {
        $passkeys = $request->user()->passkeys()->latest()->get();

        return view('passkeys.index', compact('passkeys'));
    }

    public function destroy(Request $request, Passkey $passkey)
    {
        $this->authorize('delete', $passkey);

        $passkey->delete();

        return back()->with('status', 'Geçiş anahtarı kaldırıldı.');
    }
}

passkeys() ilişkisi PasskeyAuthenticatable trait'i tarafından tanımlanmıştır. Her Passkey kaydı name, created_at ve last_used_at sütunlarına sahiptir. Kullanıcıların hangi cihazın ne olduğunu ayırt edebilmesi ve hiç tanımadıkları cihazları görebilmeleri için üçünü de kullanıcı arayüzünde gösterin.

Silme eylemini, zaten kaydedilmiş rotayı DELETE /passkeys/{passkey} ile ilişkilendirin. management_middleware (varsayılan olarak şifre onay) yönetim görünümünü ve silme eylemini korur, böylece kullanıcılar değişiklik yapmadan önce yeniden kimlik doğrulaması yapmak zorundadır.

spatie/laravel-passkeys ile Karşılaştırma

Her iki paket de web-auth/webauthn-lib kullanmakta ve aynı sonuca ulaşmaktadır. Fark, yaklaşımdadır.

laravel/passkeys (yerel) birinci parti ve ön yüz üzerinde yığın bağımsızdır. Yeni Laravel 11, 12 veya 13 projeleri ve Fortify kullanan her şey için doğru seçimdir. Eğer baştan yeni bir başlangıç yapıyorsanız, bunu kullanın.

spatie/laravel-passkeys Livewire bileşenleri ile birlikte gelir. Eğer uygulamanız zaten Livewire ağırlıklıysa ve Spatie paketini çalıştırıyorsanız, geçiş için bir neden yoktur. Önceki geçiş anahtarları kılavuzu bu kurulum hakkında tam bilgi vermektedir.

Her iki paketi aynı anda çalıştırmayın. Çünkü çakışan rotalar kaydederler ve sorun yaşayabilirsiniz.

Gönderimden Önce Düzgün Yapılması Gerekenler

Size bir hata ayıklama oturumunu kurtaracak birkaç şey:

HTTPS zorunludur. WebAuthn yalnızca güvenli kökenlerde çalışır. Yerel geliştirme için valet secure (Valet veya Herd) kullanın veya Sail'de SSL yapılandırması yapın. Eğer APP_URL http:// kullanıyorsa, tarayıcı töreni tamamen yürütmeyi reddeder. Hiçbir hata mesajı vermez. Sadece sessizlik.

Şifre kimliğini bir yedek olarak tutun. Herhangi bir kullanıcı, geçiş anahtarı olan bir cihaza sahip olmayabilir. Geçiş anahtarları ek olarak yerleştirilmelidir. Mevcut giriş formunuzu kaldırmayın. Geçiş anahtarı düğmesinin yanında bir seçenek olarak bırakın, yerine geçici olarak değil.

Hesap kurtarma düşünülmelidir. Kullanıcı tüm kayıtlı cihazlarına erişimini kaybederse, nasıl geri dönecek? Paket bunu çözmez. E-posta ile kurtarma veya yönetici tarafından başlatılan şifre sıfırlamaları standart yaklaşımlardır. Bu akışı canlıya almadan önce oluşturun.

Birden fazla geçiş anahtarı varsayılan olarak desteklenir. Kullanıcılar birden fazla cihazda kayıtlıdır ve bu beklenmektedir. Yönetim kullanıcı arayüzünüz (her geçiş anahtarı için bir iptal düğmesi ile bir liste) bunu ele alır. Kullanıcılara farklı isim, oluşturulma tarihi ve en son kullanım tarihini gösterin ki nelerin var olduğunu anlayabilsinler.

management_middleware varsayılanı password.confirm'dir. Kullanıcılar geçiş anahtarları eklerken veya iptal ederken yeniden şifrelerini doğrularlar. Bunu kaldırmayın. Bu, her tür hassas hesap eylemi uygularken uygulayacağınız güvenlik modeline dayanmaktadır.

Yerel Geliştirme

İnsanları zaman zaman yanıltan bir şey: APP_URL dosyası .env dosyasında tarayıcıda gerçekten eriştiğiniz alan adını yansıtmalıdır. Uyuşmazlık, geçiş partisi kontrolünü başarısız kılar ve hata okunaksız olabilir.

APP_URL=https://myapp.test

Valet kullanıyorsanız:

valet secure myapp

Bu kadar. Paket otomatik olarak konfigürasyon için APP_URL'yi okur.

SSS

Bu Laravel 11 ve 12'de mi, yoksa sadece 13'te mi çalışıyor?

Paket illuminate/contracts: ^11.0|^12.0|^13.0 gerektiriyor, dolayısıyla her üç sürüm de desteklenmektedir. Kullanmanız için Laravel 13'e güncelleme yapmanızı gerektirmiyor.

Bunu kullanmak için Fortify gerekli mi?

Hayır. Fortify entegrasyonu isteğe bağlıdır. Sunucu paketi bağımsız olarak çalışır: kendi rotalarınızı tanımlarsınız ve yönlendirmeleri ele alırsınız. Features::passkeys() yalnızca Fortify zaten yığınınızda ise kurulumun otomatik hale gelmesine yardımcı olur.

Zaten spatie/laravel-passkeys kullanıyorsam ne yapmalıyım?

Özellikle Livewire kurulumunuz çalışıyorsa, özel bir neden olmadıkça Spatie'de kalın. Eğer geçiş yapmayı planlıyorsanız, önce Spatie paketini kaldırın ve servis sağlayıcısını silin. İkisini aynı anda çalıştırmayın.

v0.1.0 yeterince stabil mi?

Paket, zaten Laravel'in resmi başlangıç kitlerinde varsayılan olarak yer almakta ve Fortify tarafından desteklenmektedir. v0.1.0 etiketi, kamu API'sinin evrilebileceğini anlamına gelir, deneysel olduğu anlamına gelmez. Yeni projeler için çekinmeden kullanabilirsiniz.

Bunu bir JavaScript çerçevesi olmadan kullanabilir miyim?

Evet. Çerçeveye özel yardımcı programlar (Vue, React, Svelte), aynı çekirdek API etrafında yapılan rahatlık sarfiyatlarıdır. Eğer Blade kullanıyorsanız, ön yüz çerçevesi kullanmadan Passkeys.register() ve Passkeys.verify() çağırabilir ve @laravel/passkeys içe aktardıktan sonra basit bir bloğu kullanabilirsiniz.

Bağlantıyı Kurun

Yerel geçiş anahtarları, herhangi bir Laravel projesine küçük ve odaklanmış bir eklemedir. Varsayılan konfigürasyon mantıklıdır, Fortify entegrasyonu tek satırdır ve ön yüz API'si iki yöntem çağrısıdır. Eğer yeni bir Laravel projesi başlatıyorsanız ve şifresiz kimlik doğrulama istemiyorsanız, bu yol sizin için en iyisidir.

Eğer mevcut bir üretim uygulamasına geçiş anahtarları ekliyorsanız veya karmaşık bir kimlik doğrulama kurulumunu göç ediyorsanız, benimle iletişime geçin ve entegrasyon sürecini birlikte çalışalım.