README

PSR-15 JWT authentication middleware with zero-config approach. Just add your JWT secret and you're ready to go!

Features

• ✅ Zero Configuration - Works out of the box with environment variables
• ✅ PSR-15 Compliant - Standard middleware interface
• ✅ Framework Agnostic - Works with any PSR-15 compatible framework
• ✅ Flexible Token Extraction - Bearer token (default) or custom header
• ✅ Multiple Algorithms - Supports HS256 (symmetric) and RS256 (asymmetric)
• ✅ Standard Claims Validation - Validates exp, nbf, iss, aud automatically
• ✅ Optional User Loading - Inject your own user loader
• ✅ Optional Scope Validation - Route-level permission checks
• ✅ Route-Specific Protection - Opt-in authentication per route

Installation

composer require methorz/jwt-auth-middleware

Quick Start

1. Set Environment Variable

# For symmetric key (HS256)
JWT_SECRET=your-secret-key-here

# Or for asymmetric (RS256)
JWT_PUBLIC_KEY_PATH=/path/to/public.pem
JWT_ALGORITHM=RS256

2. Add to Your Pipeline

Mezzio:

// config/pipeline.php
$app->pipe(\MethorZ\JwtAuthMiddleware\Middleware\JwtAuthenticationMiddleware::class);

Slim:

$app->add(\MethorZ\JwtAuthMiddleware\Middleware\JwtAuthenticationMiddleware::class);

3. Protect Routes

Mezzio:

$app->get('/api/protected', ProtectedHandler::class, 'protected-route')
    ->setOptions(['auth' => ['required' => true]]);

In Your Handler:

public function handle(ServerRequestInterface $request): ResponseInterface
{
    // Get JWT claims from request
    $claims = $request->getAttribute('jwt_claims');
    $userId = $claims->get('sub'); // User ID from token

    // Optional: Get loaded user (if user loader configured)
    $user = $request->getAttribute('user');

    return new JsonResponse(['user_id' => $userId]);
}

That's it! 🎉

Configuration

Environment Variables (Zero-Config)

Advanced Configuration (Optional)

If you need more control, create a configuration file:

// config/autoload/jwt-auth.php
return [
    'jwt_auth' => [
        'algorithm' => 'HS256',
        'secret' => $_ENV['JWT_SECRET'],

        // Validation constraints
        'issuer' => 'your-app',
        'audience' => 'your-api',

        // Token extraction
        'header_name' => 'Authorization',
        'header_prefix' => 'Bearer',

        // Optional: Custom header
        // 'header_name' => 'X-Auth-Token',
        // 'header_prefix' => '',

        // Optional: User loader service
        // 'user_loader' => UserLoaderInterface::class,
    ],
];

Usage Examples

Protect Specific Routes

// Only require JWT for specific routes
$app->get('/public', PublicHandler::class); // No auth

$app->get('/protected', ProtectedHandler::class)
    ->setOptions(['auth' => ['required' => true]]); // Requires JWT

Scope/Permission Validation

// Require specific scopes
$app->post('/admin/users', AdminHandler::class)
    ->setOptions([
        'auth' => [
            'required' => true,
            'scopes' => ['admin', 'users:write'],
        ],
    ]);

In your token, include a scope claim:

{
  "sub": "user123",
  "scope": "admin users:write users:read"
}

Custom User Loading

Implement UserLoaderInterface to load user from database:

use MethorZ\JwtAuthMiddleware\Contract\UserLoaderInterface;
use Lcobucci\JWT\Token\Plain;

class DatabaseUserLoader implements UserLoaderInterface
{
    public function __construct(private UserRepository $repository) {}

    public function loadUser(Plain $token): ?object
    {
        $userId = $token->claims()->get('sub');
        return $this->repository->findById($userId);
    }
}

Register in container:

// ConfigProvider.php
use MethorZ\JwtAuthMiddleware\Contract\UserLoaderInterface;

return [
    'dependencies' => [
        'factories' => [
            UserLoaderInterface::class => DatabaseUserLoaderFactory::class,
        ],
    ],
];

Now $request->getAttribute('user') contains your user object!

Generate Tokens (Separate from Middleware)

use Lcobucci\JWT\Configuration;
use Lcobucci\JWT\Signer\Hmac\Sha256;
use Lcobucci\JWT\Signer\Key\InMemory;

$config = Configuration::forSymmetricSigner(
    new Sha256(),
    InMemory::plainText($_ENV['JWT_SECRET'])
);

$now = new DateTimeImmutable();
$token = $config->builder()
    ->issuedBy('your-app')
    ->permittedFor('your-api')
    ->identifiedBy('unique-token-id')
    ->issuedAt($now)
    ->expiresAt($now->modify('+1 hour'))
    ->withClaim('sub', 'user123')
    ->withClaim('scope', 'users:read users:write')
    ->getToken($config->signer(), $config->signingKey());

echo $token->toString(); // Send to client

Request Attributes

After successful authentication, these attributes are added to the request:

Exceptions

All exceptions extend MethorZ\JwtAuthMiddleware\Exception\JwtAuthenticationException:

Recommendation: Use with methorz/http-problem-details to automatically format exceptions as RFC 7807 Problem Details responses.

Testing

composer test          # Run tests
composer cs-check      # Check code style
composer cs-fix        # Fix code style
composer analyze       # Static analysis
composer check         # All checks

Requirements

• PHP 8.2 or higher
• PSR-15 compatible framework
• lcobucci/jwt ^5.4

License

MIT License. See LICENSE for details.

Contributing

Contributions welcome! Please ensure:

• All tests pass
• Code follows PSR-12
• PHPStan level 9 passes
• Zero-config principle maintained