-
Notifications
You must be signed in to change notification settings - Fork 0
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',
],
Validates incoming JWT tokens and attaches the decoded payload to the request.
Route::middleware('jwt.auth')->get('/profile', fn () => auth()->user());
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.
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.
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.
Restricts access based on user permissions.
Route::middleware('permission:posts.create')->post('/posts', ...);
Restricts access based on user roles.
Route::middleware('role:admin')->delete('/posts/{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.
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)
],
X-Correlation-ID: 123e4567-e89b-12d3-a456-426614174000
Use microservice.auth
to run both JWT validation and permission loading in one step.
Route::middleware('microservice.auth')->get('/me', fn () => auth()->user());
Maintained by @KroderDev
💬 Feedback? Open an issue
Last updated: July 1, 2025