Laravel JWT Auth

https://laravel-jwt-auth.readthedocs.io/en/latest
Admin
Laravel JWT Auth provides JSON Web Token authentication for Laravel and Lumen applications, enabling...
Tokens:4,263
Snippets:44
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Publish JWT Auth Package Configuration

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/laravel-installation

This command publishes the configuration file for the JWT Auth package to your Laravel project's config directory. This allows for customization of package settings.

```bash
php artisan vendor:publish --provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider"
```

--------------------------------

### Sending JWT Token for Authentication

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/quick-start

This endpoint group covers different methods to send a JWT token to authenticate requests.

```APIDOC
## Authenticated Requests

There are a number of ways to send the token via http:

### Authorization Header

This is the most common and recommended method for sending the JWT token.

#### Method
GET, POST, PUT, DELETE, etc.

#### Endpoint
Any API endpoint that requires authentication

#### Request Headers
- **Authorization** (string) - Required - The JWT token prefixed with "Bearer ".
  Example: `Authorization: Bearer eyJhbGciOiJIUzI1NiI...`

### Query String Parameter

Tokens can also be appended as a query string parameter.

#### Method
GET, POST, PUT, DELETE, etc.

#### Endpoint
Any API endpoint that requires authentication

#### Query Parameters
- **token** (string) - Required - The JWT token.
  Example: `http://example.dev/me?token=eyJhbGciOiJIUzI1NiI...`

### Post Parameter

Tokens can be sent within the request body as a post parameter.

#### Method
POST, PUT, etc.

#### Endpoint
Any API endpoint that requires authentication

#### Request Body
- **token** (string) - Required - The JWT token.

### Cookies

Tokens can be sent via HTTP cookies.

### Laravel Route Parameter

Tokens can be passed as a route parameter in Laravel applications.
```

--------------------------------

### Add JWT Auth Service Provider (Laravel 5.4 and below)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/laravel-installation

This snippet shows how to register the JWT Auth service provider within the `config/app.php` file for Laravel versions 5.4 and below. This is a manual step required for older Laravel installations.

```php
'providers' => [

    ...

    PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider::class,
]
```

--------------------------------

### Configure JWT Guard in Laravel Auth Configuration (PHP)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/quick-start

This code demonstrates how to configure Laravel's authentication system to use the JWT guard. It involves modifying the 'defaults' and 'guards' sections in the `config/auth.php` file. This setup enables the 'jwt' driver for the 'api' guard, making JWT authentication the default for API routes.

```php
'defaults' => [
    'guard' => 'api',
    'passwords' => 'users',
],

...

'guards' => [
    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],

```

--------------------------------

### Generate JWT Certificates (RSA)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/laravel-installation

This command generates RSA certificates for JWT signing. It can optionally force overwriting existing certificates, specify key bits, and set the hashing algorithm. The generated certificates will update the `.env` file.

```bash
php artisan jwt:generate-certs --force --algo=rsa --bits=4096 --sha=512
```

--------------------------------

### Install Laravel JWT Auth via Composer

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/lumen-installation

Installs the latest version of the php-open-source-saver/jwt-auth package using Composer. This is the initial step to add JWT authentication capabilities to your Lumen project.

```bash
composer require php-open-source-saver/jwt-auth
```

--------------------------------

### Generate JWT Certificates

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/lumen-installation

Generates RSA or EC certificates for signing JWT tokens. This command updates the .env file with certificate information and accepts parameters to customize the certificate generation process.

```bash
php artisan jwt:generate-certs
```

```bash
php artisan jwt:generate-certs --force --algo=rsa --bits=4096 --sha=512
```

```bash
php artisan jwt:generate-certs --force --algo=ec --curve=prime256v1 --sha=512
```

--------------------------------

### Generate JWT Certificates (EC)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/laravel-installation

This command generates Elliptic Curve (EC) certificates for JWT signing. It allows forcing overwrites, specifying the curve (e.g., prime256v1), and the hashing algorithm. The `.env` file is updated with certificate details.

```bash
php artisan jwt:generate-certs --force --algo=ec --curve=prime256v1 --sha=512
```

--------------------------------

### Create AuthController for JWT Operations (PHP)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/quick-start

This PHP code defines an AuthController for handling JWT authentication operations in Laravel. It includes methods for login, retrieving the authenticated user, logging out, and refreshing tokens. The controller utilizes Laravel's built-in Auth facade and the JWTAuth library. The constructor applies the 'auth:api' middleware to all routes except 'login'.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Auth;
use App\Http\Controllers\Controller;

class AuthController extends Controller
{
    /**
     * Create a new AuthController instance.
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware('auth:api', ['except' => ['login']]);
    }

    /**
     * Get a JWT via given credentials.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function login()
    {
        $credentials = request(['email', 'password']);

        if (! $token = auth()->attempt($credentials)) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        return $this->respondWithToken($token);
    }

    /**
     * Get the authenticated User.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function me()
    {
        return response()->json(auth()->user());
    }

    /**
     * Log the user out (Invalidate the token).
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function logout()
    {
        auth()->logout();

        return response()->json(['message' => 'Successfully logged out']);
    }

    /**
     * Refresh a token.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function refresh()
    {
        return $this->respondWithToken(auth()->refresh());
    }

    /**
     * Get the token array structure.
     *
     * @param  string $token
     *
     * @return \Illuminate\Http\JsonResponse
     */
    protected function respondWithToken($token)
    {
        return response()->json([
            'access_token' => $token,
            'token_type' => 'bearer',
            'expires_in' => auth()->factory()->getTTL() * 60
        ]);
    }
}

```

--------------------------------

### Register JWT Configuration in Lumen

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/lumen-installation

Copies the JWT configuration file to the Lumen application's config directory and registers it. This ensures that the JWT settings are loaded by the application.

```php
$app->configure('jwt');
```

--------------------------------

### Uncomment Auth Middleware in Lumen

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/lumen-installation

Uncomments the 'auth' middleware registration in the Lumen bootstrap file. This makes the authentication middleware available for use in routes.

```php
$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);
```

--------------------------------

### Define JWT Authentication Routes in Laravel (PHP)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/quick-start

This snippet shows how to define API routes for JWT authentication within a Laravel application. It uses a route group with the 'api' middleware and a '/auth' prefix to manage login, logout, refresh, and user profile endpoints. These routes are defined in `routes/api.php`.

```php
Route::group([

    'middleware' => 'api',
    'prefix' => 'auth'

], function ($router) {

    Route::post('login', 'AuthController@login');
    Route::post('logout', 'AuthController@logout');
    Route::post('refresh', 'AuthController@refresh');
    Route::post('me', 'AuthController@me');

});

```

--------------------------------

### Implement JWTSubject Contract in User Model (PHP)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/quick-start

This snippet shows how to implement the JWTSubject contract in your User model. It requires the implementation of getJWTIdentifier() to return the user's unique identifier and getJWTCustomClaims() to return any custom claims for the JWT payload. Ensure your User model extends Authenticatable and uses the Notifiable trait if applicable.

```php
<?php

namespace App;

use PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements JWTSubject
{
    use Notifiable;

    // Rest omitted for brevity

    /**
     * Get the identifier that will be stored in the subject claim of the JWT.
     *
     * @return mixed
     */
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    /**
     * Return a key value array, containing any custom claims to be added to the JWT.
     *
     * @return array
     */
    public function getJWTCustomClaims()
    {
        return [];
    }
}

```

--------------------------------

### Register JWT Service Providers in Lumen

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/lumen-installation

Adds the necessary service providers for JWT authentication to the Lumen application's bootstrap file. This enables the JWT authentication features within the application.

```php
// Uncomment this line
$app->register(App\Providers\AuthServiceProvider::class);

// Add this line
$app->register(PHPOpenSourceSaver\JWTAuth\Providers\LumenServiceProvider::class);
```

--------------------------------

### Generate JWT Secret Key

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/lumen-installation

Generates a secret key for signing JWT tokens using the provided Artisan command. This key is essential for securing your tokens and is typically stored in the .env file.

```bash
php artisan jwt:secret
```

--------------------------------

### Get Token by User ID

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The tokenById() method retrieves a JWT associated with a specific user ID. This can be useful for generating tokens for users without requiring them to log in interactively.

```php
$token = auth()->tokenById(123);

```

--------------------------------

### Override Token Time To Live (TTL)

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The setTTL() method allows you to override the default token expiration time. The value is provided in minutes. This example sets the token to expire after 2 hours (120 minutes).

```php
$token = auth()->setTTL(120)->attempt($credentials);

```

--------------------------------

### Get JWT Payload

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The payload() method retrieves the raw JWT payload, which contains various claims such as subject (sub), expiration time (exp), and JWT ID (jti). Claims can be accessed directly or the payload can be converted to an array.

```php
$payload = auth()->payload();

// then you can access the claims directly e.g.
$payload->get('sub'); // = 123
$payload['jti']; // = 'asfe4fq434asdf'
$payload('exp') // = 123456
$payload->toArray(); // = ['sub' => 123, 'exp' => 123456, 'jti' => 'asfe4fq434asdf'] etc

```

--------------------------------

### Attempt Authentication with Credentials

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The attempt() method tries to authenticate a user based on provided credentials. If successful, it returns a JWT; otherwise, it returns null. This is typically used for login functionalities.

```php
// Generate a token for the user if the credentials are valid
$token = auth()->attempt($credentials);

```

--------------------------------

### Login User and Generate JWT

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The login() method logs in a user and generates a JWT for them. This method requires a User object as input and returns the generated token upon successful authentication.

```php
// Get some user from somewhere
$user = User::first();

// Get the token
$token = auth()->login($user);

```

--------------------------------

### Configure JWT Secret Key

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/configuration

This configuration option sets the secret key used for signing and verifying JWT tokens. It is typically loaded from the JWT_SECRET environment variable. Ensure this key is kept confidential and is sufficiently complex to prevent unauthorized token generation.

```php
'secret' => env('JWT_SECRET'),
```

--------------------------------

### Retrieve Authenticated User or Throw Exception

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The userOrFail() method retrieves the currently authenticated user. If no user is authenticated, it throws a PHPOpenSourceSaver\JWTAuth\Exceptions\UserNotDefinedException, allowing for explicit error handling.

```php
try {
    $user = auth()->userOrFail();
} catch (PHPOpenSourceSaver\JWTAuth\Exceptions\UserNotDefinedException $e) {
    // do something
}

```

--------------------------------

### Set Request Instance Explicitly

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The setRequest() method allows you to explicitly set the request instance that the authentication guard should use. This can be helpful in testing scenarios or when manually managing requests.

```php
$user = auth()->setRequest($request)->user();

```

--------------------------------

### Specify Guard for Multiple Guards

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

When multiple authentication guards are defined or the 'api' guard is not the default, explicitly specify the guard when calling the auth() method to obtain an authentication token.

```php
$token = auth('api')->attempt($credentials);

```

--------------------------------

### Set JWT Token Explicitly

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The setToken() method allows you to explicitly set a JWT for authentication purposes, bypassing the usual token retrieval mechanisms from the request. This is useful when you have a token available elsewhere.

```php
$user = auth()->setToken('eyJhb...')->user();

```

--------------------------------

### Retrieve Authenticated User

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The user() method retrieves the currently authenticated user. If no user is authenticated, it returns null. This is useful for accessing user information after successful authentication.

```php
// Get the currently authenticated user
$user = auth()->user();

```

--------------------------------

### Add Custom Claims to JWT

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

Custom claims can be added to the JWT payload before attempting authentication by chaining the claims() method with attempt(). This allows for including additional, non-standard information in the token.

```php
$token = auth()->claims(['foo' => 'bar'])->attempt($credentials);

```

--------------------------------

### Validate User Credentials

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The validate() method checks if the provided credentials are valid for authentication. It returns a boolean value: true if the credentials are valid, and false otherwise.

```php
if (auth()->validate($credentials)) {
    // credentials are valid
}

```

--------------------------------

### Log Out User and Invalidate Token

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The logout() method logs out the current user, invalidating their token and unsetting the authenticated user session. An optional boolean parameter can be passed to permanently blacklist the token.

```php
auth()->logout();

// Pass true to force the token to be blacklisted "forever"
auth()->logout(true);

```

--------------------------------

### Refresh JWT Token

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The refresh() method invalidates the current JWT and generates a new one. It accepts optional parameters to permanently blacklist the old token or reset token claims.

```php
$newToken = auth()->refresh();

// Pass true as the first param to force the token to be blacklisted "forever".
// The second parameter will reset the claims for the new token
$newToken = auth()->refresh(true, true);

```

--------------------------------

### Invalidate JWT Token

Source: https://laravel-jwt-auth.readthedocs.io/en/latest/auth-guard

The invalidate() method adds the current token to the blacklist, effectively invalidating it. An optional boolean parameter can be passed to permanently blacklist the token.

```php
auth()->invalidate();

// Pass true as the first param to force the token to be blacklisted "forever".
auth()->invalidate(true);

```
Tokens:
Raw