Download the PHP package bspdx/keystone without Composer

BSPDX Keystone

A comprehensive, production-ready authentication package for Laravel with an API-first architecture. Keystone combines the power of Laravel Fortify, Sanctum, 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

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

• Frontend Flexibility
• Requirements
• Installation
• Configuration
• Usage
  • User Model Setup
  • Service Layer
  • Blade Components (Optional)
  • Routes
  • Middleware
  • API Usage
• Architecture
• HTTPS Setup
• Multi-Tenancy
• Testing
• Credits
• License

Requirements

• PHP 8.2+
• Laravel 12.x or 13.x
• MySQL 5.7+ / PostgreSQL 9.6+ / SQLite 3.8.8+

Installation

Step 1: Install via Composer

Step 2: Publish Configuration & Assets

Step 3: Run Migrations

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)

This creates:

• 4 default roles: super-admin, admin, editor, user
• Common permissions for each role
• 4 demo users (all with password: password)
  • [email protected] - Super Admin
  • [email protected] - Admin
  • [email protected] - Editor
  • [email protected] - Regular User

Step 5: Configure Fortify

In your config/fortify.php, ensure these features are enabled:

Configuration

The package configuration is located at config/keystone.php. Key settings:

Enable/Disable Features

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:

See Multi-Tenancy Documentation for detailed architecture, usage examples, and migration guides.

RBAC Settings

Passkey Settings

Two-Factor Settings

Usage

User Model Setup

New project? Use the built-in KeystoneUser model and skip this setup entirely. See User Model Configuration for a full comparison and setup instructions.

Add the HasKeystone trait to your existing User model:

This trait combines:

• HasApiTokens (Sanctum)
• TwoFactorAuthenticatable (Fortify)
• HasPasskeys (Spatie Passkeys)

You can also query users by assigned role directly from the model:

Service Layer (NEW in v0.3.0)

Keystone v0.3.0 introduces a clean service layer architecture to interact with roles, permissions, and passkeys. All external dependencies are now abstracted behind Keystone services.

Using Services in Controllers

Benefits:

• Clean dependency injection
• Easy to mock for testing
• No direct external package dependencies in your code
• Future-proof architecture

Blade Components (Optional)

Keystone provides optional pre-built Blade components for Laravel projects. If you're using React, Vue, or another frontend framework, you can skip this section and use the JSON API endpoints instead.

For Laravel Blade users:

Login Form

Register Form

Two-Factor Challenge

Passkey Registration

Passkey Login

Routes

Keystone doesn't auto-register routes. Add them manually from the published examples:

Web Routes (routes/keystone-web.php):

API Routes (routes/keystone-api.php):

Middleware

Keystone provides three middleware aliases:

Role Middleware

Permission Middleware

2FA Enforcement Middleware

Checking Permissions in Code

Traditional Approach (User Model Methods)

Service Layer Approach (Recommended for Controllers)

API Usage

Keystone is designed with an API-first architecture, making it perfect for:

• Single Page Applications (React, Vue, Angular, Svelte)
• Mobile applications (iOS, Android, React Native, Flutter)
• Headless/decoupled architectures
• Microservices

Authentication

Use Sanctum for API authentication. All Keystone controllers automatically return JSON when the request has Accept: application/json header or uses wantsJson():

API Endpoints

All API routes are protected with auth:sanctum middleware. Example requests:

Get All Roles:

Assign Role to User:

Enable 2FA:

Architecture

Keystone v0.3.0+ uses an API-first, service layer architecture to isolate external dependencies and provide maximum flexibility for any frontend framework.

Service Layer

All role, permission, and passkey operations go through dedicated services:

• PasskeyService - Manages WebAuthn/passkey operations
  • registerOptions(), register(), authenticationOptions(), authenticate()
• RoleService - Role CRUD and queries
  • getAllWithPermissions(), create(), delete(), syncPermissions()
• PermissionService - Permission CRUD and queries
  • getAllWithRoles(), create(), delete(), syncToUser()
• AuthorizationService - High-level authorization operations
  • assignRolesToUser(), assignPermissionsToUser(), userHasRole(), userHasPermission()

All services are registered in Laravel's service container with interface bindings and convenient aliases:

• keystone.passkey
• keystone.roles
• keystone.permissions
• keystone.authorization

Models

Keystone provides its own model classes that extend Spatie's models:

• BSPDX\Keystone\Models\KeystoneRole - Extends Spatie's Role model
  • Adds isSuperAdmin() method
• BSPDX\Keystone\Models\KeystonePermission - Extends Spatie's Permission model

All type hints use these Keystone models, providing a consistent BSPDX\Keystone namespace throughout your application.

Benefits

• API-First - Works with any frontend framework (React, Vue, mobile apps, etc.)
• Testability - Mock service interfaces in tests instead of facades
• Maintainability - All external dependencies isolated in service layer
• Flexibility - Easy to swap implementations or add caching/logging
• Clean API - No third-party classes in your controllers
• Optional UI - Blade components included but completely optional

Multi-Tenancy

Keystone provides comprehensive multi-tenant support using global scopes for automatic tenant isolation. Roles and permissions can be global (accessible across all tenants) or tenant-specific (isolated per organization).

Keystone handles the RBAC side of multi-tenancy — scoping roles, permissions, and assignments to a tenant_id. It does not provide a Tenant model, tenant creation, or user-to-tenant assignment. Your application is responsible for managing tenants and populating tenant_id on your User model. Keystone reads that value automatically to scope all role and permission queries.

Quick Start

Enable multi-tenancy in your .env:

Features

• Automatic Tenant Filtering - Global scopes automatically filter roles/permissions by authenticated user's tenant
• Global Roles/Permissions - Set tenant_id = NULL to make roles/permissions accessible across all tenants
• Tenant-Specific Roles - Roles with tenant_id are isolated to a single organization
• UUID Support - Works with both UUID and bigint tenant IDs
• Super-Admin Bypass - Use ::withoutTenant() scope for cross-tenant operations

Usage Examples

Creating Global Roles

Creating Tenant-Specific Roles

Super-Admin Operations

Keystone Management Commands

Keystone provides artisan commands for managing roles, permissions, and users:

Learn More

For comprehensive documentation on multi-tenancy:

• Multi-Tenancy Architecture - Global scopes vs Spatie teams
• Multi-Tenant Usage Examples - Common patterns and best practices
• Migration guides for upgrading from single-tenant to multi-tenant

HTTPS Setup

Passkeys require HTTPS! See our detailed guide: HTTPS Setup for Laravel Sail

Quick summary:

1. Install mkcert:

2. Generate certificates:

3. Update .env:

4. Configure Nginx/Caddy to use the certificates

See the full guide for detailed instructions.

Testing

Run the package tests:

Or with PHPUnit directly:

Customization

Custom Blade Views

Publish the views and modify as needed:

Views will be in resources/views/vendor/keystone/.

Custom Styling

All Blade components use CSS custom properties for easy theming:

Security

If you discover any security issues, please email [email protected] instead of using the issue tracker.

Credits

• BSPDX
• Built with:
  • Laravel Fortify
  • Laravel Sanctum
  • Spatie Laravel Passkeys (abstracted)

Note: Starting with v0.3.0, all Spatie dependencies are abstracted through Keystone's service layer, providing a clean BSPDX\Keystone namespace throughout your application. Starting with v0.8.0, role and permission management uses a custom built-in RBAC system; Spatie Laravel Passkeys remains as the passkey backend.

License

The MIT License (MIT). Please see License File for more information.

Quick Start Example

Here's a complete example to get you started quickly:

1. Install Package

2. Update User Model

3. Create Login Page

4. Add Routes

5. Test It Out

That's it! You now have a complete authentication system with 2FA, passkeys, and RBAC.

Support

• Documentation: Full documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions