Як створити гібридну стратегію Passkey в Symfony 7.4: навігація за межами фортеці без пароля

У цієї серії ми дослідили «святий Грааль» сучасної автентифікації: 100% безпарольну програму. Ми позбулися паролів, хешів та електронних листів для скидання, замінивши їх криптографічною елегантністю WebAuthn API. Частині 1 Але реальний світ рідко буває таким чистим. У вас є давні користувачі, які довіряють своїм менеджерам паролів більше, ніж біометрії. У вас є корпоративні середовища, де ключі безпеки ще не є стандартом. Найголовніше, у вас є «Перехідний період» — той незграбний етап, коли вам потрібно підтримувати старе, агресивно просуваючи нове. Сьогодні ми створюємо гібридну модель. Ми створимо єдину, інтелектуальну форму входу, яка автоматично визначає, чи є у користувача Passkey, запускає біометричні дані, якщо вони доступні, але в разі необхідності граціозно повертається до традиційного пароля. Ми також розглянемо умовне посередництво (автозаповнення Passkey) — «магічний» UX, який дозволяє користувачеві входити в систему, просто зосередившись на полі введення. Технологічний стек Щоб дотримуватися цього посібника, вам знадобиться: Використання класів тільки для читання та просування конструктора. PHP 8.2+: Використання останніх удосконалень компонента безпеки. Symfony 7.4: : Галузевий стандарт для WebAuthn у Symfony. web-auth/webauthn-symfony-bundle Для фронтенд-досвіду без Node.js. Stimulus & AssetMapper: Шедевр UX: Як це працює Замість того, щоб спантеличувати користувачів двома окремими кнопками входу («Увійти з паролем» проти «Увійти з Passkey»), ми надаємо їм один елегантний ввід: їхню адресу електронної пошти. Користувач вводить свою електронну адресу та натискає «Продовжити». За лаштунками наш бекенд Symfony 7.4 виконує блискавичну перевірку. Ми миттєво запускаємо нативний запит на біометричні дані WebAuthn (FaceID, TouchID, Windows Hello). Якщо у користувача зареєстровано Passkey: Форма граціозно розгортається, щоб показати традиційне поле введення пароля. Якщо користувач покладається на пароль: Це саме той потік, який використовують технічні гіганти, такі як та , і сьогодні ми створюємо його повністю за допомогою стандартних інструментів Symfony! Google GitHub Доменна модель: Поєднання двох світів У нашій наша сутність User навіть не мала поля пароля. Щоб підтримувати гібридний потік, ми повинні його знову ввести, але як необов'язковий обліковий запис. Це дозволяє створити багаторівневу модель безпеки: користувач може почати з простого пароля, а пізніше «оновити» свій обліковий запис, зареєструвавши Passkey, який врешті-решт стане основним (і найбезпечнішим) способом входу. попередній чисто безпарольній конфігурації Реалізуючи , зберігаючи поле пароля необов’язковим, ми задовольняємо вимоги безпеки Symfony для традиційного входу, не змушуючи кожного користувача мати застарілий обліковий запис. Цей архітектурний вибір має вирішальне значення для підтримки зворотної сумісності, чітко сигналізуючи, що Passkey є перспективним стандартом для програми. PasswordAuthenticatedUserInterface // src/Entity/User.php namespace App\Entity; use App\Repository\UserRepository; use Doctrine\ORM\Mapping as ORM; use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface; use Symfony\Component\Security\Core\User\UserInterface; use Symfony\Component\Uid\Uuid; #[ORM\Entity(repositoryClass: UserRepository::class)] #[ORM\Table(name: '`user`')] class User implements UserInterface, PasswordAuthenticatedUserInterface { #[ORM\Id] #[ORM\GeneratedValue] #[ORM\Column] private ?int $id = null; #[ORM\Column(length: 180, unique: true)] private ?string $email = null; #[ORM\Column(length: 255, unique: true)] private ?string $userHandle = null; #[ORM\Column(type: 'string', length: 255, nullable: true)] private ?string $password = null; public function __construct() { // WebAuthn requires a persistent, non-identifying handle $this->userHandle = Uuid::v4()->toRfc4122(); } // ... standard getters/setters public function getPassword(): ?string { return $this->password; } public function setPassword(?string $password): static { $this->password = $password; return $this; } public function eraseCredentials(): void { // Clear temporary sensitive data } public function getUserIdentifier(): string { return (string) $this->email; } } Вибір архітектури: Виявлення потоку Ядром чудового гібридного UX є виявлення потоку. Ми не хочемо показувати дві форми. Ми хочемо один ввід: «Введіть свою електронну адресу». Коли користувач натискає «Продовжити», наш контролер Stimulus звертається до легковагового API-кінцевого пункту, щоб визначити наступний крок. Це запобігає «втомі від поля пароля», коли користувачі стикаються зі складною формою, перш ніж вони навіть ідентифікували себе. Важливо, що цей кінцевий пункт розроблений з урахуванням «безпеки через двозначність». Якщо електронна адреса не знайдена, ми за замовчуванням надаємо відповідь для потоку пароля. Це запобігає використанню зловмисниками API для перевірки, які електронні адреси зареєстровані в нашій системі (перерахування користувачів), одночасно дозволяючи нам надавати індивідуальний, прогресивний UI для наших законних користувачів. API потоку // src/Controller/AuthController.php namespace App\Controller; use App\Repository\UserRepository; use App\Repository\PublicKeyCredentialSourceRepository; use Symfony\Component\HttpFoundation\JsonResponse; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\Routing\Attribute\Route; class AuthController extends AbstractController { #[Route('/api/auth/flow', name: 'app_api_auth_flow', methods: ['GET'])] public function apiAuthFlow( Request $request, UserRepository $userRepo, PublicKeyCredentialSourceRepository $credsRepo ): JsonResponse { $email = $request->query->get('email'); $user = $userRepo->findOneBy(['email' => $email]); if (!$user) { // Treat non-existent users as password users to prevent enumeration return new JsonResponse(['flow' => 'password']); } $hasPasskeys = count($credsRepo->findAllForUserEntity($user->toWebauthnUser())) > 0; return new JsonResponse([ 'flow' => $hasPasskeys ? 'passkey' : 'password' ]); } } Охорона безпеки: HybridAuthenticator У той час як автоматично обробляє , нам потрібен спосіб обробки традиційного резервного варіанту пароля. Замість використання вбудованого form_login, ми реалізуємо власний . Це дозволяє нам розглядати різні типи облікових даних ( ) як окремі «значки» в єдиній уніфікованій події автентифікації, забезпечуючи набагато чистішу інтеграцію з сучасним компонентом безпеки Symfony 7.4. webauthn-symfony-bundle перевірку Passkey HybridAuthenticator Passkey проти паролів Використовуючи власний автентифікатор, ми також можемо гарантувати, що обидва методи автентифікації мають однакові обробники успіху та невдачі. Це означає, що перенаправлені URL-адреси панелі інструментів, флеш-повідомлення та журнали безпеки є послідовними для всієї програми, незалежно від того, використовував користувач свій відбиток пальця чи 20-символьний пароль для доступу. // src/Security/HybridAuthenticator.php namespace App\Security; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\Response; use Symfony\Component\Security\Core\Authentication\Token\TokenInterface; use Symfony\Component\Security\Core\Exception\AuthenticationException; use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator; use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge; use Symfony\Component\Security\Http\Authenticator\Passport\Credentials\PasswordCredentials; use Symfony\Component\Security\Http\Authenticator\Passport\Passport; class HybridAuthenticator extends AbstractAuthenticator { public function __construct( private readonly AuthenticationSuccessHandler $successHandler, private readonly AuthenticationFailureHandler $failureHandler ) {} public function supports(Request $request): ?bool { // Only intercept standard POST login attempts with a password return $request->isMethod('POST') && $request->getPathInfo() === '/login' && $request->request->has('password'); } public function authenticate(Request $request): Passport { $email = $request->request->getString('username'); $password = $request->request->getString('password'); return new Passport( new UserBadge($email), new PasswordCredentials($password) ); } public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewall): ?Response { return $this->successHandler->onAuthenticationSuccess($request, $token); } public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response { return $this->failureHandler->onAuthenticationFailure($request, $exception); } } Система автентифікаторів Symfony 7.4 надзвичайно гнучка. Ми можемо налаштувати наш для прийняття як входу за формою (паролі), так і WebAuthn-тверджень в одному файрволі! security.yaml security: password_hashers: App\Entity\User: 'auto' providers: app_user_provider: entity: class: App\Entity\User property: email firewalls: dev: pattern: ^/(_(profiler|wdt)|css|images|js)/ security: false main: lazy: true provider: app_user_provider custom_authenticator: App\Security\HybridAuthenticator webauthn: authentication: routes: options_path: /login/passkey/options result_path: /login/passkey/result registration: enabled: true routes: options_path: /register/passkey/options result_path: /register/passkey/result success_handler: App\Security\AuthenticationSuccessHandler failure_handler: App\Security\AuthenticationFailureHandler logout: path: app_logout access_control: - { path: ^/dashboard, roles: ROLE_USER } Магія фронтенду: Умовне посередництво (автозаповнення) Ось тут програма починає відчуватися по-справжньому сучасною. Умовне посередництво дозволяє браузеру запропонувати Passkey, як тільки користувач зосередиться на полі електронної пошти. Цей вхід «нульовим зусиллям» означає, що для багатьох користувачів процес входу складається з одного натискання на їхнє ім’я у спливаючому вікні браузера, за яким слідує біометричний сканування. Щоб досягти цього, ми використовуємо атрибут у нашому HTML. Це служить прямим сигналом для менеджера облікових даних браузера. На стороні JavaScript метод Stimulus connect() є ідеальним місцем для ініціювання фонового «прослуховування» цих пропозицій автозаповнення, дозволяючи сторінці залишатися інтерактивною, поки браузер чекає вибору користувача. autocomplete=”username webauthn” Шаблон Нам потрібно додати до нашого вводу. Це сигнал для браузера. autocomplete=”username webauthn” {# templates/app/login.html.twig #} hybrid-login#submit"> Continue Контролер Stimulus У нашому методі ми перевіряємо, чи підтримує браузер автозаповнення. Якщо так, ми негайно запускаємо . connect() церемонію WebAuthn у фоновому режимі // assets/controllers/hybrid_login_controller.js import { Controller } from '@hotwired/stimulus'; import { startAuthentication, browserSupportsWebAuthnAutofill } from '@simplewebauthn/browser'; export default class extends Controller { async connect() { if (await browserSupportsWebAuthnAutofill()) { try { // Background listen for autofill const credential = await startAuthentication({ optionsJSON: await this.fetchOptions(), useBrowserAutofill: true }); await this.verifyResult(credential); } catch (e) { // Silent catch: user might just type manually } } } async submit(event) { event.preventDefault(); const email = this.emailTarget.value; // 1. Check Flow const { flow } = await fetch(`/api/auth/flow?email=${email}`).then(r => r.json()); if (flow === 'passkey') { await this.triggerPasskeyLogin(email); } else { this.showPasswordInput(); } } } Шлях «Оновлення»: Додавання Passkey з панелі інструментів Найбільша проблема з Passkey — це не код; це прийняття. Вам потрібно дати вашим користувачам причину та спосіб додати біометричні дані до своїх існуючих облікових записів паролів. Ми реалізували спеціалізований , який дозволяє вже залогіненим користувачам безпечно подолати розрив між їхнім минулим, заснованим на паролях, та їхнім біометричним майбутнім без труднощів повної повторної реєстрації. PasskeySettingsController Ключовою частиною цього потоку є використання . Передаючи існуючі ідентифікатори облікових даних користувача до браузера під час цього процесу, ми гарантуємо, що користувачеві не буде запропоновано створити дублікат Passkey на тому самому пристрої. Це запобігає «засміченню облікових даних» і гарантує, що панель інструментів користувача показує лише унікальні, функціональні ключі безпеки, зберігаючи досвід чистим та керованим. excludeCredentials // src/Controller/PasskeySettingsController.php #[Route('/dashboard/passkey/options', methods: ['POST'])] public function options(): JsonResponse { $user = $this->getUser(); $userEntity = new PublicKeyCredentialUserEntity( $user->getEmail(), $user->getUserHandle(), $user->getEmail() ); // Exclude existing keys so the browser doesn't offer duplicates $excludeDescriptors = array_map( fn ($source) => new PublicKeyCredentialDescriptor('public-key', $source->publicKeyCredentialId), $this->credsRepo->findAllForUserEntity($userEntity) ); $options = $this->optionsFactory->create('default', $userEntity, $excludeDescriptors); $this->optionsStorage->store(Item::create($options, $userEntity)); return new JsonResponse($this->serializer->serialize($options, 'json'), 200, [], true); } Технічні проблеми та перевірка Двійкові дані та JSON Однією з найпоширеніших проблем у розробці WebAuthn є кодування. Ідентифікатори облікових даних та виклики — це сирі двійкові дані, які стандартний json_encode не може обробити. Ми повинні використовувати стандарт base64url, який спеціально розроблений для безпечного транспортування в URL-адресах та JSON без проблематичних символів + або / зі стандартного Base64. Використання спеціалізованого серіалізатора пакета гарантує, що це перетворення відбувається правильно та послідовно. Кроки перевірки Створіть обліковий запис за допомогою застарілого маршруту /register/password, щоб встановити базового користувача «старого світу». Реєстрація пароля: Перейдіть до /login та введіть електронну адресу. Система повинна правильно ідентифікувати користувача як користувача лише з паролем і показати поле пароля. Гібридний вхід: Увійдіть зі своїм паролем, перейдіть до панелі інструментів та натисніть «Додати Passkey», щоб об’єднати обліковий запис у біометричний світ. Оновлення: Вийдіть із системи. Клацніть поле електронної пошти. Ваш браузер тепер повинен негайно запропонувати Passkey, замикаючи коло гібридного досвіду. Автозаповнення: Висновок Реалізація гібридної моделі автентифікації в Symfony 7.4 є витонченим балансом між передовою безпекою та практичною доступністю. Надаючи уніфікований інтерфейс, який поважає як застарілі звички щодо паролів, так і рух до біометрії, ви усуваєте те тертя, яке часто вбиває впровадження нових функцій. Цей підхід не просто покращує безпеку; він будує довіру з вашими користувачами, зустрічаючи їх там, де вони є, одночасно чітко показуючи їм кращий, швидший шлях уперед. Технічно ми побачили, що сучасний компонент безпеки Symfony та пакет WebAuthn забезпечують надзвичайно надійну основу для цих складних потоків. Можливість розглядати паролі та Passkey як взаємодоповнюючі значки в одній екосистемі означає, що ви, як розробник, не боретеся з фреймворком для реалізації власної логіки. Натомість ви використовуєте стандартні, взаємодіючі примітиви для створення системи, яка настільки ж зручна в обслуговуванні, наскільки й безпечна. Заглядаючи в майбутнє, мета — це веб, де автентифікація настільки безперешкодна, що стає невидимою. З умовним посередництвом та гібридними резервними варіантами ми наближаємося до цієї реальності, де тягар безпеки переходить від пам’яті користувача до апаратного забезпечення в його кишені. Впроваджуючи ці шаблони сьогодні, ви забезпечуєте майбутнє своєї програми та гарантуєте, що ваші користувачі отримають переваги від найвищих стандартів цифрової безпеки, не жертвуючи зручністю, яку вони очікують. Ви можете знайти повну реалізацію та стежити за прогресом проекту на GitHub: [ ] Вихідний код: https://github.com/mattleads/PasskeysAuth Зв'яжімося! Якщо ви знайшли це корисним або маєте запитання щодо реалізації, я був би радий почути від вас. Давайте залишатися на зв’язку та продовжувати розмову на цих платформах: LinkedIn: [ ] https://www.linkedin.com/in/matthew-mochalkin/ X (Twitter): [ ] https://x.com/MattLeads Telegram: [ ] https://t.me/MattLeads GitHub: [ ] https://github.com/mattleads