Middleware

The package ships with several middleware components. Enable or rename them in config/microservice.php under middleware_aliases.

Set an alias to null or an empty string to disable registration.

'middleware_aliases' => [
    'jwt_auth'       => 'jwt.auth',
    'correlation_id' => 'correlation.id',
    'load_access'    => 'load.access',
    'role'           => 'role',
    'permission'     => 'permission',
],

JWT Authentication

Validates incoming JWT tokens and attaches the decoded payload to the request.

Route::middleware('jwt.auth')->get('/profile', fn () => auth()->user());

Configuration

JWT authentication is configured in config/microservice.php under the auth key:

'auth' => [
    // Path or URL to the RSA public key for verifying JWT tokens.
    'jwt_public_key' => env('JWT_PUBLIC_KEY_PATH'),

    // Algorithm used for JWT signature verification (default: RS256).
    'jwt_algorithm' => env('JWT_ALGORITHM', 'RS256'),

    // Time-to-live (in seconds) for caching JWT keys (default: 3600).
    'jwt_cache_ttl' => env('JWT_CACHE_TTL', 3600),

    // HTTP header to extract the JWT token from (default: 'Authorization').
    'header' => 'Authorization',

    // Prefix expected before the JWT token in the header (default: 'Bearer').
    'prefix' => 'Bearer',
],

• jwt_public_key: Path or URL to the public key used for verifying JWT tokens. Store securely, typically in your environment file.
• jwt_algorithm: Supported algorithms include HS256, RS256, ES256, EdDSA, and others as supported by firebase/php-jwt.
• jwt_cache_ttl: Duration (in seconds) to cache JWT keys.
• header: HTTP header name to read the JWT from (e.g., Authorization).
• prefix: Prefix before the JWT in the header (e.g., Bearer).

Adjust these settings as needed for your authentication requirements.

See Authorization for Blade helpers.

LoadAccess

By default, the ValidateJwt middleware will automatically load roles and permissions from the JWT payload if they are present.

The LoadAccess middleware fetches the latest roles and permissions for the authenticated user when needed. This is recommended when using a centralized permission microservice, as it ensures access information is always up to date by triggering an API call. Use this middleware only if your service requires real-time access checks, since it may impact performance.

Configuration

You can configure the permissions cache duration and the endpoint used to fetch permissions in config/microservice.php:

'permissions_cache_ttl' => env('PERMISSIONS_CACHE_TTL', 60), // Cache duration in seconds
'permissions_endpoint'  => env('PERMISSIONS_ENDPOINT', '/auth/permissions'), // API endpoint

• permissions_cache_ttl: How long (in seconds) to cache fetched roles and permissions for an authenticated user. Adjust via the PERMISSIONS_CACHE_TTL environment variable.
• permissions_endpoint: The API endpoint used to fetch the user's roles and permissions. This endpoint is typically exposed via the ApiGateway and configured using the PERMISSIONS_ENDPOINT environment variable.

Adjust these settings to balance performance and real-time accuracy according to your application's needs.

Permission Middleware

Restricts access based on user permissions.

Route::middleware('permission:posts.create')->post('/posts', ...);

Role Middleware

Restricts access based on user roles.

Route::middleware('role:admin')->delete('/posts/{id}', ...);

Correlation ID

Adds or propagates an X-Correlation-ID header for distributed tracing. This header helps track requests across multiple services for debugging and monitoring. If the incoming request already has the header, it will be reused; otherwise, a new UUID is generated. The header is added to both the request and the response.

The correlation ID middleware is enabled by default for all API routes. To disable it, set the correlation_id alias to null or an empty string in your middleware_aliases configuration.

Configuration

You can customize the header name and ID length in config/microservice.php:

'correlation' => [
    'header' => 'X-Correlation-ID', // Header name
    'length' => 36,                  // ID length (default: UUID)
],

Example Header

X-Correlation-ID: 123e4567-e89b-12d3-a456-426614174000

Auth Middleware Group

Use microservice.auth to run both JWT validation and permission loading in one step.

Route::middleware('microservice.auth')->get('/me', fn () => auth()->user());