Download the PHP package jekk0/jwt-auth without Composer

Laravel JWT Authentication

Installation

Optionally, install the paragonie/sodium_compat package from composer if your php env does not have libsodium installed:

Package configuration

Publish package resources

After running this command, resources from the package, such as the configuration file and migrations, will be added to your Laravel application.

Configure package (optional)

You should now have a ./config/jwtauth.php file that allows you to configure the package.

Create a new table for manage refresh tokens

Run the migrate command to create the table jwt_refresh_tokens needed to store JWT refresh token data

Generate certificates and add configuration to your .env file

Laravel application configuration

Configure auth guard

Make the following changes to the file:

A JWT user can be any model that implements the native laravel interface \Illuminate\Contracts\Auth\Authenticatable

Create the user auth controller

Add auth routes

Pruning expired JWT refresh tokens

Refresh Token Flow

The Refresh Token Flow is a mechanism that allows users to obtain a new access token without re-authenticating. It is used to maintain sessions securely while keeping access tokens short-lived.

User Authentication

The user logs in with their credentials (e.g., email/password) The server verifies the credentials and issues:

• A short-lived access token (e.g., valid for 15 minutes).
• A long-lived refresh token (e.g., valid for several days or weeks).

Authentication request:

Authentication response:

An access token is used to authenticate and authorize users, granting them access to protected resources without needing to repeatedly log in. It contains user identity and custom claims and is typically short-lived to enhance security.

A refresh token is used to obtain a new access token without requiring the user to log in again. It is long-lived and helps maintain user sessions securely while minimizing exposure of credentials.

Accessing Protected Resources

• The client includes the access token in the Authorization header (Bearer ) to make authenticated API requests.
• The server validates the token and grants access.

User profile request:

Token Expiration & Refresh Request

• When the access token expires, the client sends a request to the token refresh endpoint.
• The request includes the refresh token.
• The server verifies the refresh token (e.g., checks its validity and ensures it is not revoked).
• If valid, the server issues a new access token and refresh token.
• The client replaces the expired access token and refresh token with new ones.

Refresh request:

Refresh response:

Logout or Token Revocation

• If the user logs out, the refresh token will be revoked (removed from a database).
• If a refresh token is compromised, see Refresh token compromised

Logout request:

Logout from all devices request:

Security

Access token invalidation

Since the lifetime of an access token is relatively short (up to one hour, with a default of 15 minutes), the package does not invalidate the access token upon logout. Instead, invalidation is only performed for the refresh token to avoid additional database query overhead.

It is assumed that the frontend will simply remove the access token from storage upon logout, allowing it to expire naturally. However, if token invalidation needs to be enforced on every request, this can be implemented using an event-based mechanism.

Make event listener:

Refresh token compromised

If a refresh token is reused (i.e., an old token is attempted after a new one has been issued), it is a strong indication of a token theft or replay attack. Here’s what to do:

1. Immediately Revoke All Active Tokens
   • Revoke both the newly issued and previously used refresh tokens.
   • Invalidate any active access tokens associated with the compromised refresh token.
2. Notify the User
   • If a stolen refresh token was used, inform the user about a possible security breach.
   • Recommend changing their password if suspicious activity is detected.

Make event listener:

Customization

Customize JWT token payload

To add custom claims to a JWT token, you need to implement the interface Jekk0\JwtAuth\Contracts\JwtCustomClaims

Customize JWT extractor

By implementing a custom extractor (default Authorization: Bearer), you can retrieve the JWT token from alternative locations such as request headers, query parameters or even custom request attributes.

Customize JWT token issuer

By default, the JWT token issuer is taken from the request URL. To change this behavior, override the binding for Jekk0\JwtAuth\Contracts\TokenExtractor as shown in the example below:

Available events:

1. Jekk0\JwtAuth\Events\JwtAccessTokenDecoded
2. Jekk0\JwtAuth\Events\JwtAttempting
3. Jekk0\JwtAuth\Events\JwtAuthenticated
4. Jekk0\JwtAuth\Events\JwtFailed
5. Jekk0\JwtAuth\Events\JwtLogin
6. Jekk0\JwtAuth\Events\JwtLogout
7. Jekk0\JwtAuth\Events\JwtLogoutFromAllDevices
8. Jekk0\JwtAuth\Events\JwtRefreshTokenCompromised
9. Jekk0\JwtAuth\Events\JwtRefreshTokenDecoded
10. Jekk0\JwtAuth\Events\JwtTokensRefreshed
11. Jekk0\JwtAuth\Events\JwtValidated

Functionally testing a JWT protected api

Login with Laravel's default actingAs method:

Login with JWT guard:

or

Manually generate a JWT token for end-to-end testing:

Examples

• Laravel separated user auth example application

  It demonstrates a role-based authentication system where different user types (User, Admin, Company) are stored separately in the database.