PHPackages bspdx/keystone - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. bspdx/keystone ActiveLibrary[Authentication & Authorization](/categories/authentication) bspdx/keystone ============== Complete authentication package for Laravel with Fortify, Passkeys, TOTP 2FA, and RBAC v0.7.1(3mo ago)019MITPHPPHP ^8.2CI passing Since Jan 25Pushed 1mo agoCompare [ Source](https://github.com/TheBootstrapParadox/Keystone)[ Packagist](https://packagist.org/packages/bspdx/keystone)[ RSS](/packages/bspdx-keystone/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (13)Versions (5)Used By (0) BSPDX Keystone ============== [](#bspdx-keystone) [![Latest Version on Packagist](https://camo.githubusercontent.com/56eee7b5cb738ef740e64e77ca59c0feae6c34190cb1d162f21b7c7c9d6085c8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f62737064782f6b657973746f6e652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bspdx/keystone)[![Total Downloads](https://camo.githubusercontent.com/d8c816027f193f878694b0b6101bca654ae37e500cdb87bd712f8858cc34e90b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f62737064782f6b657973746f6e652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bspdx/keystone)[![License](https://camo.githubusercontent.com/be2dadbb61545b3f530fa6e202360e1bdfac4c97bb6ca8aa77ea7a2a7f8f0056/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f62737064782f6b657973746f6e652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/bspdx/keystone) A comprehensive, production-ready authentication package for Laravel 12 with an **API-first architecture**. Keystone combines the power of Laravel Fortify, Sanctum, Spatie Laravel Permission, and Spatie Laravel Passkeys to provide a full-featured auth system with: - 🔐 **Standard Authentication** - Powered by Laravel Fortify - 👥 **Role-Based Access Control (RBAC)** - Clean service layer API - 📱 **TOTP Two-Factor Authentication** - Google Authenticator, Authy, etc. - 🔑 **Passkey Authentication** - Modern WebAuthn/FIDO2 login - 🛡️ **Passkey as 2FA** - Use passkeys as a second factor - 🎨 **Optional Blade UI Components** - Pre-built views for Laravel projects - 🌐 **API-First Design** - Works with React, Vue, mobile apps, or any frontend - 🏢 **Multi-Tenancy Ready** - Optional tenant scoping Frontend Flexibility -------------------- [](#frontend-flexibility) **Keystone works with any frontend framework:** - ✅ **React, Vue, Angular, Svelte** - Use the JSON API endpoints - ✅ **Mobile Apps** - iOS, Android, React Native, Flutter - ✅ **Laravel Blade** - Optional pre-built UI components included - ✅ **Inertia.js** - Perfect for hybrid approaches All controllers return JSON when requested, making Keystone truly framework-agnostic at the API level. Table of Contents ----------------- [](#table-of-contents) - [Frontend Flexibility](#frontend-flexibility) - [Requirements](#requirements) - [Installation](#installation) - [Configuration](#configuration) - [Usage](#usage) - [User Model Setup](#user-model-setup) - [Service Layer](#service-layer-new-in-v030) - [Blade Components (Optional)](#blade-components-optional) - [Routes](#routes) - [Middleware](#middleware) - [API Usage](#api-usage) - [Architecture](#architecture) - [HTTPS Setup](#https-setup) - [Multi-Tenancy](#multi-tenancy) - [Testing](#testing) - [Credits](#credits) - [License](#license) Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 12.0+ - MySQL 5.7+ / PostgreSQL 9.6+ / SQLite 3.8.8+ Installation ------------ [](#installation) ### Step 1: Install via Composer [](#step-1-install-via-composer) ``` composer require bspdx/keystone ``` ### Step 2: Publish Configuration & Assets [](#step-2-publish-configuration--assets) ``` # Publish the essentials: configuration and migrations php artisan vendor:publish --tag=keystone-config --tag=keystone-migrations # Publish Blade views (optional - only if you want to customize) php artisan vendor:publish --tag=keystone-views # Publish example routes php artisan vendor:publish --tag=keystone-routes # Publish database seeders php artisan vendor:publish --tag=keystone-seeders ``` ### Step 3: Run Migrations [](#step-3-run-migrations) ``` php artisan migrate ``` This will create tables for: - Two-factor authentication columns in `users` table - Roles and permissions (Spatie) - Passkeys (Spatie) - Personal access tokens (Sanctum) ### Step 4: Seed Demo Data (Optional) [](#step-4-seed-demo-data-optional) ``` php artisan db:seed --class=KeystoneSeeder ``` This creates: - 4 default roles: `super-admin`, `admin`, `editor`, `user` - Common permissions for each role - 4 demo users (all with password: `password`) - `superadmin@example.com` - Super Admin - `admin@example.com` - Admin - `editor@example.com` - Editor - `user@example.com` - Regular User ### Step 5: Configure Fortify [](#step-5-configure-fortify) In your `config/fortify.php`, ensure these features are enabled: ``` 'features' => [ Features::registration(), Features::resetPasswords(), Features::emailVerification(), Features::updateProfileInformation(), Features::updatePasswords(), Features::twoFactorAuthentication([ 'confirm' => true, 'confirmPassword' => true, ]), ], ``` Configuration ------------- [](#configuration) The package configuration is located at `config/keystone.php`. Key settings: ### Enable/Disable Features [](#enabledisable-features) ``` 'features' => [ 'registration' => true, 'email_verification' => true, 'two_factor' => true, 'passkeys' => true, 'passkey_2fa' => true, 'api_tokens' => true, 'update_profile' => true, 'update_passwords' => true, 'account_deletion' => false, 'passwordless_login' => true, 'show_permissions' => true, // Enable multi-tenant mode (adds tenant_id column to users, roles, and permissions tables) 'multi_tenant' => env('KEYSTONE_MULTI_TENANT', false), ], ``` When `multi_tenant` is enabled, Keystone will add a nullable `tenant_id` column to users, roles, permissions, and pivot tables. Keystone uses **global scopes** for automatic tenant isolation (not Spatie's teams feature). **Key Features:** - **Automatic Filtering** - Authenticated users only see roles/permissions for their tenant - **Global Roles/Permissions** - Set `tenant_id = NULL` for cross-tenant access - **UUID Support** - Works with both UUID and bigint tenant IDs - **Super-Admin Bypass** - Use `::withoutTenant()` for cross-tenant operations **Example:** ``` use BSPDX\Keystone\Models\KeystoneRole; // Create global role (accessible to all tenants) $superAdmin = KeystoneRole::withoutTenant()->create([ 'name' => 'super_administrator', 'tenant_id' => null, ]); // Create tenant-specific role (auto-scoped) Auth::login($userInTenantA); $manager = KeystoneRole::create(['name' => 'manager']); // tenant_id automatically populated from auth()->user()->tenant_id ``` See [Multi-Tenancy Documentation](docs/multi-tenancy.md) for detailed architecture, usage examples, and migration guides. ### RBAC Settings [](#rbac-settings) ``` 'rbac' => [ 'default_role' => 'user', 'super_admin_role' => 'super-admin', ], ``` ### Passkey Settings [](#passkey-settings) ``` 'passkey' => [ 'rp_name' => env('APP_NAME', 'Laravel'), 'rp_id' => env('PASSKEY_RP_ID', 'localhost'), 'user_verification' => 'preferred', 'allow_multiple' => true, 'required_for_roles' => [ // 'admin', ], ], ``` ### Two-Factor Settings [](#two-factor-settings) ``` 'two_factor' => [ 'qr_code_size' => 200, 'recovery_codes_count' => 8, 'required_for_roles' => [ // 'admin', ], ], ``` Usage ----- [](#usage) ### User Model Setup [](#user-model-setup) Add the `HasKeystone` trait to your `User` model: ```