Laravel Passkeys 초기 조사 (passkeys-server + @laravel/passkeys)

이 글은 laravel/passkeys-server와 laravel/passkeys의 README에 기반한 초기 조사입니다. 두 패키지는 아직 태그 없는 개발 단계입니다 (2026년 4월 시점).

이것은 무엇에 관한 패키지인가

Laravel의 공식 리포지토리에서 패스워드리스 인증(WebAuthn / 패스키)을 구현하기 위한 2개의 패키지가 공개되어 있습니다.

서버 측 (PHP): laravel/passkeys-server
클라이언트 측 (JavaScript): @laravel/passkeys

이 두 개를 조합하면 Laravel 앱에서 패스키 등록과 패스키 로그인을 일관되게 구현할 수 있습니다.

서버 측: `laravel/passkeys-server`

설치와 초기 셋업

PHP 패키지 추가

composer require laravel/passkeys

마이그레이션 공개 및 실행

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

User 모델에 trait과 contract 추가

use Laravel\Passkeys\Contracts\PasskeyUser;
use Laravel\Passkeys\PasskeyAuthenticatable;

class User extends Authenticatable implements PasskeyUser
{
    use PasskeyAuthenticatable;
}

필요에 따라 설정 파일도 공개할 수 있습니다.

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

자동 등록되는 라우트

구분	메서드	라우트	역할
Login (guest)	`GET`	`/passkeys/login/options`	인증 옵션 취득
Login (guest)	`POST`	`/passkeys/login`	패스키 검증과 로그인
Confirm (auth)	`GET`	`/passkeys/confirm/options`	확인용 옵션 취득
Confirm (auth)	`POST`	`/passkeys/confirm`	패스키 확인
Management (auth)	`GET`	`/user/passkeys/options`	등록 옵션 취득
Management (auth)	`POST`	`/user/passkeys`	신규 패스키 저장
Management (auth)	`DELETE`	`/user/passkeys/{passkey}`	패스키 삭제

`config/passkeys.php`의 주요 옵션

relying_party_id
allowed_origins
user_handle_secret
timeout
guard
middleware
throttle
redirect

이벤트

패키지는 이하의 이벤트를 발화합니다.

PasskeyRegistered
PasskeyVerified
PasskeyDeleted

커스터마이즈 포인트

LoginAuthorizationCallback (로그인 허가 판정)

Passkeys::authorizeLoginUsing()으로 검증 성공 후의 로그인 허가를 제어할 수 있습니다. 정지시키고 싶은 경우는 false를 반환하거나 ValidationException을 던집니다.

CustomActions (WebAuthn 처리 교체)

GenerateRegistrationOptions / GenerateVerificationOptions / StorePasskey / VerifyPasskey / DeletePasskey를 상속하여 서비스 컨테이너에 바인딩하고, 동작을 교체할 수 있습니다.

CustomResponses (응답 교체)

PasskeyLoginResponse 등의 컨트랙트를 독자적으로 구현하여, 성공 시 응답(JSON · 리다이렉트 등)을 앱 요건에 맞게 변경할 수 있습니다.

클라이언트 측: `@laravel/passkeys`

@laravel/passkeys는 브라우저 측 WebAuthn ceremony를 다루는 JavaScript 클라이언트입니다.

설치

npm install @laravel/passkeys

기본 API

import { Passkeys } from "@laravel/passkeys";

await Passkeys.register({ name: "My MacBook" });
await Passkeys.verify();

프레임워크 헬퍼

React: @laravel/passkeys/react의 usePasskeyVerify, usePasskeyRegister
Vue: @laravel/passkeys/vue의 usePasskeyVerify, usePasskeyRegister
Svelte: @laravel/passkeys/svelte의 usePasskeyVerify, usePasskeyRegister

패스키 자동완성

autofill: true를 지정하면 autocomplete="... webauthn"을 가진 input에 브라우저의 패스키 피커를 표시할 수 있습니다. 지원되지 않는 환경이나 사용자 취소 시에는 일반 흐름으로 폴백합니다.

타입이 부여된 오류

README에서는 다음 오류 클래스가 공개되어 있습니다.

NotSupportedError
UserCancelledError
PasskeyExistsError
PasskeyError (베이스 클래스)

SSR 대응

WebAuthn은 브라우저 API이지만, 각 프레임워크용 훅은 SSR 세이프입니다. 서버 측에서는 isSupported가 false로 취급되고, 마운트 후에 실제 브라우저 상태로 갱신됩니다.

정리

laravel/passkeys-server (PHP)와 @laravel/passkeys (JS)를 조합하면, Laravel에서 완결되는 패스키 인증 스택을 구축할 수 있습니다.
둘 다 태그 없는 개발 단계이지만, Laravel 공식 에코시스템으로서 앞으로의 표준 인증 수단이 될 가능성이 높습니다.
조기 채용하는 경우, README의 라우트 · 설정 · 오류 핸들링 · 커스터마이즈 확장점을 전제로 설계하면 안전합니다.

그 후 패스키는 Laravel Fortify의 기능으로 정식 추가되었습니다. Fortify 경유로 패스키를 활성화하는 경우는 laravel/passkeys-server를 직접 설치하지 않고 Features::passkeys()를 사용합니다. 자세한 내용은 Laravel Fortify와 스타터 킷을 참고하세요.

laravel/passkeys-server

서버 측 패키지의 최신 README와 구현을 확인합니다.