README

⭐ Found this useful? Install from Packagist and give the repo a star on GitHub.

Symfony bundle for configurable login, registration, and password reset: overridable Twig templates, registration modes (disabled, first_user_only, always), optional embeddable auth dropdown, locale-prefixed routes, assignable registration role, configurable user entity and form fields, built-in routes, and translations (de, en, es, fr, it, nl, pt). Works alongside Symfony Security — security.yaml remains required and is documented in INSTALLATION.md with optional CLI helper nowo:auth-kit:configure-security.

This bundle is FrankenPHP worker mode friendly (including when the kernel is not reset between requests — see FRANKENPHP-WORKER-AUDIT.md).

AuthKit sign-in page in the demo: UiKit auth panel on the host guest layout (demo navbar with locale switcher), email and password with visibility toggle, Sign in button, footer links to magic link, QR phone sign-in and password reset, Symfony profiler toolbar

_{Sign in — UiKit auth scaffold on the host's guest layout}

AuthKit invitation administration in the demo: Invitations list page on the host admin layout with Invite button, e-mail search and status filter, rows with e-mail, Pending badge, inviter, sent and expiry dates, Resend and Revoke actions, Symfony profiler toolbar

_{Invitations — administration list (opt-in, 1.32)}

AuthKit accept-invitation page: registration form with the inviter's message, the invited e-mail pre-filled and read-only, password and confirmation, Register button, Symfony profiler toolbar

_{Accept an invitation — registration form, e-mail locked}

Features

Login page compatible with Symfony form_login
Registration with Doctrine persistence and password hashing
Password reset (link, code, or both) with pluggable notifier
Magic login (passwordless email link via Symfony login_link; optional CSRF confirm interstitial)
Social login (OAuth; see SOCIAL-LOGIN.md)
Enterprise SSO (OIDC) via social credentials + enterpriseSso flag (see SSO.md)
QR phone login (opt-in; see QR-LOGIN.md)
Invitations (opt-in, 1.32): invite by e-mail instead of open registration (registration_mode: invite_only), hashed single-use expiring links, administration pages (list, invite, resend, revoke) on the UiKit scaffolds, acceptance on the registration form, Symfony Mailer delivery, audit events, grant SPI and purge command (see INVITATIONS.md)
Two-factor authentication (opt-in, 1.34): TOTP authenticator apps with a server-rendered QR code, single-use recovery codes, a firewall-level two-step token after every first factor, remember-me only after the second step, trusted devices, required roles with a grace period, admin reset, UserKit session integration (see MFA.md)
Several accounts at once (opt-in, 1.34): Google-style account switcher, each account in its own session through its own sign-in and MFA, switch without a password, sign out one or all, UserKit revocation and personal-data erasure; schedule nowo:auth-kit:accounts:purge (nightly) to drop expired entries (see MULTI-ACCOUNT.md)
WebAuthn / passkeys — design locked for a later release (see WEBAUTHN.md, ROADMAP.md)
Embedded auth dropdown (auth_kit_dropdown()) for navbars and layouts
Locale in URL paths (/en/login, /es/register, …)
Remember me (optional persistent login cookie)
Password strength (optional integration with nowo-tech/password-strength-bundle)
Slide to confirm (optional integration with nowo-tech/slide-to-confirm-bundle for registration consent and QR approve)
Device intelligence (optional integration with nowo-tech/device-intelligence-bundle, PHP 8.3+: collect on auth pages, new-device notify, device-keyed rate limits, QR trusted-device step-up; Device ID is not a credential)
OTP input (optional integration with nowo-tech/otp-input-bundle for a multi-box password-reset code field; UX only)
Registration modes: disabled, first user only, always open
Admin CLI — nowo:auth-kit:create-admin (hidden password prompt, min length + password-strength policy, AdminUserCreatedEvent hook)
Recipient-locale notifications — reset / magic-login / new-device links and notifier translator in the account's preferred locale (PreferredLocaleAwareInterface)
Translated flash messages — AuthKit flashes are stored as text (any host flash template works) plus a flash_trans Twig filter with a configurable domain chain
Named profiles — separate auth config per user entity (User, Admin, …) with O(1) class resolution
Configurable user_class, identifier field, login/register fields, role, routes, templates
Legacy-host opt-ins (1.30+): bare route name suffix (.default), POST + CSRF logout, reset check-email page and token in session, throttled reset signal from a custom token manager, unmapped auth_kit_* entities and no routes for disabled features (CONFIGURATION.md, PASSWORD-RESET.md)
UiKit page contract (REQ-UI-003): every auth page is the UiKit auth scaffold on your guest layout — theme it once in nowo_ui_kit, no page overrides (TEMPLATES.md)
Per-page template overrides via web_ui.templates.<page> (thin {% extends '@!NowoAuthKit/…' %} + data block)
Translation domain NowoAuthKitBundle with app overrides (de, en, es, fr, it, nl, pt)

Installation

composer require nowo-tech/auth-kit-bundle

# config/packages/nowo_auth_kit.yaml
nowo_auth_kit:
    default_profile: default
    profiles:
        default:
            user_class: App\Entity\User
            user_identifier_field: email
            registration_mode: first_user_only
            registration_role: ROLE_USER

The legacy flat layout (user_class at root) remains supported. See Configuration.

php bin/console nowo:auth-kit:configure-security

Demo

make -C demo up-symfony8   # Symfony 8.1 — http://localhost:8010

Register the first user, then try password login, password reset, magic login, QR phone sign-in and dual locale URLs (/en/login and bare /login → redirect). The demo host renders the auth pages through its UiKit guest layout (templates/layouts/guest.html.twig, Bootstrap 5 theme), with the navbar auth_kit_dropdown(), a session delivery inbox (no mailer) and FrankenPHP (Docker); it has no AuthKit template overrides. Screenshots: see the top of this README (make -C demo/symfony8 demo-screenshots).

See demo/README.md for template override paths and docs/DEMO-FRANKENPHP.md for FrankenPHP setup (including worker mode for production).

Development

make up
make test
make release-check

Documentation

Additional documentation

PSR evaluation (REQ-CS-007)
Templates (UiKit page contract)
GitHub Actions CI requirements
Password reset
Magic login
Social login
QR phone login — opt-in (mode: disabled by default; shipped since v1.12)
Invitations — opt-in (invitations.mode: disabled by default; since v1.32)
Two-factor authentication — opt-in (mfa.enabled: false by default; since v1.34)
Several accounts at once — opt-in (multi_account.enabled: false by default; since v1.34)
Roadmap
Demo with FrankenPHP
FrankenPHP worker audit (no kernel reset)

Tests and coverage

Tests: PHPUnit (unit + integration)
PHP: 100%
TS/JS: N/A
Python: N/A

License

MIT — see LICENSE.

nowo-tech / auth-kit-bundle

Package info

Security

Fund package maintenance!

Statistics