Download the PHP package kz370/jwt-auth without Composer

Laravel JWT Auth

A sophisticated, secure, and developer-friendly JWT authentication package for Laravel. Designed with a dual-token architecture (Access + Refresh tokens) and advanced security features like automatic rotation and replay attack detection.

🚀 Key Features

• Dual-Token Architecture: Implements short-lived Access Tokens for security and long-lived Refresh Tokens for a seamless user experience.
• Secure Token Management: All refresh tokens are hashed (SHA-256) before storage, ensuring data safety even in the event of a database compromise.
• Automatic Token Rotation: Implements a "sliding session" approach where a new refresh token is issued on every use, immediately invalidating the previous one.
• Advanced Replay Detection: Real-time monitoring of token families. If a previously used refresh token is re-submitted, the system detects a breach and revokes the entire token family.
• Granular Device Control: Native support for tracking, listing, and revoking specific device sessions from anywhere in your application.
• Zero-Config Integration: Drop-in replacement for standard Laravel guards (Sanctum/Passport).

📦 Installation

Install the package via Composer:

1. Run Migrations

The package requires specific tables to manage token families and device sessions.

2. Publish Configuration (Optional)

Customize the TTL (Time-To-Live), signing algorithm, and other settings:

3. Generate JWT Secret

Generate a secure signing key for your tokens. This will be added to your .env file:

👨‍💻 User Model Setup

To enable session management and token relationships on your User model, add the HasJwtAuth trait:

This trait provides several helper methods:

• $user->jwtTokens: Get all active sessions.
• $user->currentJwtToken(): Get the session model for the current request.

🎭 Multi-Model & Multi-Guard Support

The package is not limited to the User model. You can use it with any Eloquent model (Admins, Customers, etc.) and even manage multiple guards simultaneously.

1. Custom Model

If you only use one model but it's not App\Models\User, update your config/jwt-auth.php:

2. Multiple Guards (e.g., User and Admin)

If you need separate authentication for different tables, define them in config/auth.php:

Then protect your routes accordingly:

How it works

The package uses a polymorphic relationship in the database. Instead of a simple user_id, the tokens table contains:

• authenticatable_id: The ID of the record (e.g., 1).
• authenticatable_type: The class name of the model (e.g., App\Models\Admin).

This design ensures that sessions are perfectly isolated, even if two different models share the same ID.

Note: Ensure every model used for authentication includes the HasJwtAuth trait.

⚙️ Configuration

Automatic Guard Registration

The package automatically registers a jwt authentication guard. To use it as your default for API routes, update your config/jwt-auth.php:

🛡 Middleware Usage

The package provides two middlewares out of the box to help you secure your routes.

1. jwt.auth

Protects routes that require a valid Access Token. It automatically validates the JWT and sets the authenticated user for the request.

2. jwt.refresh

Ensures that the request contains a refresh_token. Useful for specific refresh or logout endpoints.

⚡ Integration with Existing Auth

If you are migrating from Laravel Sanctum or Passport, you simply need to replace your token generation logic in your authentication controllers.

Find where you currently generate tokens (e.g., $user->createToken(...)) and replace it with the JwtAuth facade:

This ensures that users transitioning to this package correctly adopt the new dual-token system without leaving behind outdated logic.

🛠 Usage

Authentication (The Facade)

The JwtAuth facade is the primary entry point for all operations.

User Login (Credentials)

Token Refresh

Exchange a refresh token for a brand new pair of tokens (rotates the family).

Logout

Invalidates the current refresh token and session. Returns true on success, or false if the token is invalid/expired.

📱 Device & Session Management

Take full control of user sessions across multiple devices:

🔒 Security Design

Family IDs & Token Rotation

Every login starts a "Token Family". When you refresh, the old refresh token is revoked, and a new one is issued within the same family.

Replay Attack Protection

If a used refresh token is ever presented again (indicating it was stolen and replayed), the package detects this immediately and revokes every token in that family, forcing the legitimate user to re-authenticate and securing the account.

🖥 Console Commands

Recommendation: Schedule the cleanup command to run daily:

📄 License

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