README

A self-contained PHP auth package for Laravel. Ships with its own routes, controllers, migrations, config, and views — zero external runtime dependencies.

Features

Requirements

• PHP >= 8.0
• Extensions: ext-hash, ext-json, ext-curl, ext-mbstring, ext-sodium
• (Optional) Laravel >= 11.0 if using as a Laravel drop-in

Installation

composer require jarir-ahmed/auth-microservice

For Non-Laravel (Framework-Agnostic) Users

Since this package is completely framework-agnostic, you can integrate it into any PHP application (Symfony, Slim, vanilla PHP):

1. Dependency Injection: Use our provided Container (or your own PSR-11 container) to bind the required Repositories.

use JarirAhmed\AuthMicroservice\Container;
use JarirAhmed\AuthMicroservice\Contracts\UserRepositoryInterface;
use App\Repositories\MyUserRepository;

$container = new Container();
$container->bind(UserRepositoryInterface::class, function () {
    return new MyUserRepository(); // Provide your own DB implementation
});

1. Configuration: Load the package configuration array and customize it for your needs.
2. Database: Use the provided schemas in database/migrations to create the required tables in your database using your preferred tool (Phinx, Doctrine, raw SQL).

For Laravel Users (Drop-in)

If you are using Laravel, the package will auto-discover its Service Provider and act as a seamless drop-in.

Publish config and migrations:

php artisan vendor:publish --tag=auth-microservice-config
php artisan vendor:publish --tag=auth-microservice-migrations
php artisan migrate

Configuration:

php artisan vendor:publish --tag=auth-microservice-config

Key settings in config/auth-microservice.php:

'user_model' => \App\Models\User::class,

'registration' => [
    'require_email_verification' => true,
],

'lockout' => [
    'max_attempts'    => 5,
    'lockout_minutes' => 15,
],

'two_factor' => [
    'issuer' => env('APP_NAME', 'AuthMicroservice'),
],

'oauth' => [
    'google' => [
        'client_id'     => env('GOOGLE_CLIENT_ID'),
        'client_secret' => env('GOOGLE_CLIENT_SECRET'),
        'redirect_uri'  => env('GOOGLE_REDIRECT_URI'),
    ],
    // facebook, github, twitter, linkedin ...
],

Routes

All routes are prefixed with /auth by default (configurable).

Middleware

Register in your bootstrap/app.php or Http/Kernel.php:

use JarirAhmed\AuthMicroservice\Middleware\TokenAuthMiddleware;
use JarirAhmed\AuthMicroservice\Middleware\TwoFactorMiddleware;
use JarirAhmed\AuthMicroservice\Middleware\EmailVerifiedMiddleware;
use JarirAhmed\AuthMicroservice\Middleware\AccountLockoutMiddleware;
use JarirAhmed\AuthMicroservice\Middleware\LastOnlineMiddleware;
use JarirAhmed\AuthMicroservice\Middleware\TrackAuthMiddleware;

Design Decisions

• Zero external runtime dependencies — TOTP, OAuth 2.0, backup codes all implemented natively using PHP 8.0+ built-in extensions only
• SHA-256 token storage — plaintext token returned once on creation, only the hash stored in DB (same pattern as GitHub, GitLab, Laravel Sanctum)
• Native TOTP — RFC 6238 compliant, HMAC-SHA1 + time-step truncation, base32 encoded secrets
• QR codes deferred to frontend — package returns the otpauth:// URI; client-side JS renders it
• Event-driven — every auth action fires an event; listeners handle logging, notifications, and tracking decoupled from the main flow
• Extendable User model — set auth-microservice.user_model to your own model

Testing

composer install
./vendor/bin/phpunit

License

MIT