Auth Kit Bundle

⭐ 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).

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

Invitations — administration list (opt-in, 1.32)

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

• Installation
• Configuration
• Usage
• Contributing
• Code of Conduct
• Changelog
• Upgrading
• Release
• Security
• Engram
• Spec-driven development
• GitHub Spec Kit

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.