Laravel API Authentication Using Firebase PHP JWT: Symmetric and Asymmetric Cryptography Implementations
Introduction
When building modern web applications, you often need to authenticate requests to your API from various clients like mobile apps, single-page applications (SPAs), or third-party services. While session-based authentication works well for traditional web applications, it's not ideal for APIs. JSON Web Tokens (JWTs) offer a better solution by being stateless, scalable, and portable. Unlike sessions that require server-side storage and can be challenging to scale across multiple servers, JWTs contain all necessary authentication data within the token itself. This makes them perfect for distributed systems where your API might run on multiple servers. They are also more efficient for mobile and SPA clients since there's no need to maintain session state or deal with CORS issues. In this tutorial, we'll implement JWT authentication for a Laravel API using the Firebase PHP JWT package, covering both basic token handling and advanced security considerations.
Setup
To get started, ensure you have a Laravel application up and running. If not, you can follow the official Laravel installation guide to set up your application quickly. Next, install the firebase/php-jwt package. The library provides a straightforward way to encode and decode JWTs. Add it to your project using Composer:
composer require firebase/php-jwt
The package requires Sodium encryption support (libsodium). If your PHP version is below 7.2.0, you can achieve this by either:
- Installing the Sodium PHP extension as detailed in the official documentation.
- Installing the compatibility package using Composer:
composer require paragonie/sodium_compat
JWT Implementation Using Symmetric Key Cryptography
The two main features that the firebase/php-jwt package provides are encoding and decoding JWTs. Let's create a class to wrap that functionality.
<?php
declare(strict_types=1);
namespace App\Services;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Illuminate\Support\Facades\Log;
class JWTCodec
{
/**
* Encode a payload into a jwt.
*/
public function encode(array $payload): string
{
return JWT::encode($payload, (string) config('jwt.secret_key'), (string) config('jwt.algorithm'));
}
/**
* Decode a jwt into an array.
*
* @throws \Throwable
*/
public function decode(string $jwt): ?array
{
try {
$payload = JWT::decode($jwt, new Key((string) config('jwt.secret_key'), (string) config('jwt.algorithm')));
return (array) $payload;
} catch (\Throwable $exception) {
Log::error('JWT decoding failed', [
'message' => $exception->getMessage(),
'trace' => $exception->getTraceAsString(),
]);
return null;
}
}
}
The class above simplifies the process of encoding and decoding JWTs. The encode method generates a JWT by signing a payload using a secret key and a specified cryptographic algorithm. It would be used to issue JWTs to clients after successful authentication. The decode method verifies the authenticity of a JWT and returns the extracted JWT payload as an array. It would be used to validate incoming JWTs from clients. For example, when a client makes an API request, the application can use this method to verify the token and extract claims such as the identity or roles of the user making the request.
Next, create a configuration file to store JWT-related variables:
touch config/jwt.php
// add to config/jwt.php
<?php
return [
/*
|--------------------------------------------------------------------------
| Secret Key
|--------------------------------------------------------------------------
|
| A secret key is used to sign and validate JWTs when using symmetric
| algorithms. Asymmetric algorithms use a private/public key pair.
|
*/
'secret_key' => env('JWT_SECRET_KEY'),
/*
|--------------------------------------------------------------------------
| Algorithm
|--------------------------------------------------------------------------
|
| JWT uses an algorithm to encode and decode tokens.
| Valid algorithms are listed here
| https://datatracker.ietf.org/doc/html/rfc7518#section-3
|
*/
'algorithm' => env('JWT_ALGORITHM', 'HS256'),
];
Generate a secure secret key using Laravel's tinker:
php artisan tinker
>>> bin2hex(random_bytes(32))
=> 60e6f39da755c8f2373aebffc181bd59f060cf10253eb92c85337ef8f0e36d3f
Then add the generated key to the .env file:
# Add to .env
JWT_SECRET_KEY=paste-generated-secret-key-here
Symmetric Key Cryptography Security Considerations
The current implementation uses symmetric cryptography, where the same key is used for both signing (encoding) and validating (decoding) JWTs. While functional, this approach requires careful key management to prevent compromise. A more robust approach is to use public-key or asymmetric cryptography, where a private key signs (encodes) the JWT and a public key validates (decodes) the JWT.
The asymmetric approach offers advantages such as:
- Enhanced security through separate signing and validation keys, where the private key for signing remains completely isolated on the authorization server.
- Simpler scaling in distributed systems, as new resource servers only need the public key for verification, and compromising any resource server doesn't enable token creation.
- Lower operational complexity when rotating keys, since only the authorization server's private key needs to change while public keys can be updated gradually.
- API clients (mobile apps, SPAs) can validate JWT authenticity using the public key before making API requests.
Implementing Asymmetric Key Cryptography
We are going to be using the phpseclib/phpseclib package to generate encryption keys. Install the package using Composer:
composer require phpseclib/phpseclib
Next, create a console command that will be used to generate encryption keys.
php artisan make:command GenerateEncryptionKeys
While there are a number of public key cryptography algorithms that can be used to generate public-private key pairs, we are going to be using the RSA (Rivest-Shamir-Adleman) algorithm in this tutorial. Add the following code to the generated command class.
<?php
declare(strict_types=1);
namespace App\Console\Command;
use Illuminate\Console\Command;
use App\Services\EncryptionKeyService;
use phpseclib3\Crypt\RSA;
use Illuminate\Support\Facades\Storage;
class GenerateEncryptionKeys extends Command
{
/**
* The name and signature of the console command.
*
* @var string
*/
protected $signature = 'auth:generate-encryption-keys
{--force : Overwrite keys if they already exist}
{--length=4096 : The length of the private key}';
/**
* The console command description.
*
* @var string
*/
protected $description = 'Create the encryption keys for API authentication';
/**
* Execute the console command.
*/
public function handle(): int
{
$validKeyLengths = [
2048,
3072,
4096,
];
$length = (int) $this->option('length');
if (! in_array($length, $validKeyLengths, true)) {
$message = sprintf('Invalid key length provided. Valid values are: %s', implode(',', $validKeyLengths));
$this->error($message);
return Command::FAILURE;
}
$publicKey = config('jwt.encryption_keys.public_key_filename');
$privateKey = config('jwt.encryption_keys.private_key_filename');
$disk = Storage::build(['driver' => 'local', 'root' => storage_path('keys')]);
if (($disk->exists($publicKey) || $disk->exists($privateKey)) && ! $this->option('force')) {
$this->error('Encryption keys already exist. Use the --force option to overwrite them.');
return Command::FAILURE;
}
$key = RSA::createKey($length);
$disk->put($publicKey, (string) $key->getPublicKey());
$disk->put($privateKey, (string) $key);
$this->info('Encryption keys generated successfully.');
return Command::SUCCESS;
}
}
The command generates and stores RSA encryption keys for API authentication. It validates the key length which may be provided as an option to the command and ensures existing keys are not overwritten unless the --force option is used. The keys are securely stored in the storage/keys directory, with filenames configured in the application.
Next, we need to add the neccessary variables to the config/jwt.php configuration file.
// other config variables
'algorithm' => env('JWT_ALGORITHM', 'RS256'),
/*
|--------------------------------------------------------------------------
| Encryption Keys
|--------------------------------------------------------------------------
|
| JWT uses encryption keys while generating secure access tokens for your
| application. By default, the keys are stored as local files.
| The filenames of the files are set below.
|
*/
'encryption_keys' => [
'private_key_filename' => env('JWT_PRIVATE_KEY_FILENAME', 'auth_private.key'),
'public_key_filename' => env('JWT_PUBLIC_KEY_FILENAME', 'auth_public.key'),
],
By default, Laravel automatically registers all commands in the app/Console/Commands directory. If your command is in another directory, register it using the instructions provided here. Some usage examples of the command are provided below:
# run the command with default options to generate a 4096-bit key pair
php artisan auth:generate-encryption-keys
# use the --force option to overwrite existing keys
php artisan auth:generate-encryption-keys --force
# generate a key pair with a specific length (e.g. 2048 bits):
php artisan auth:generate-encryption-keys --length=2048
Don't forget to add the storage/keys folder to .gitignore so that the folder won't be committed into source control. Now that we have encryption keys to sign and validate JWTs, we need to amend the JWTCodec class to use the encryption keys when encoding a payload or decoding a JWT.
<?php
declare(strict_types=1);
namespace App\Services;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Illuminate\Support\Facades\Log;
use Illuminate\Contracts\Filesystem\FileNotFoundException;
use Illuminate\Support\Facades\Storage;
class JWTCodec
{
/**
* Encode a payload into a jwt.
*
* @throws \Throwable
*/
public function encode(array $payload): ?string
{
$disk = Storage::build(['driver' => 'local', 'root' => storage_path('keys')]);
$filename = (string) config('jwt.encryption_keys.private_key_filename');
throw_if(
! $disk->exists($filename),
new FileNotFoundException(sprintf('Could not find the jwt private key file: %s', $filename))
);
$key = $disk->get($filename);
try {
return JWT::encode($payload, $key, config('jwt.algorithm'));;
} catch (\Throwable $exception) {
Log::error('JWT encoding failed', [
'message' => $exception->getMessage(),
'trace' => $exception->getTraceAsString(),
]);
return null;
}
}
/**
* Decode a jwt into an array.
*
* @throws \Throwable
*/
public function decode(string $jwt): ?array
{
$disk = Storage::build(['driver' => 'local', 'root' => storage_path('keys')]);
$filename = (string) config('jwt.encryption_keys.public_key_filename');
throw_if(
! $disk->exists($filename),
new FileNotFoundException(sprintf('Could not find the jwt public key: %s', $filename))
);
$key = $disk->get($filename);
try {
$payload = JWT::decode($jwt, new Key($key, (string) config('jwt.algorithm')));
return (array) $payload;
} catch (\Throwable $exception) {
Log::error('JWT decoding failed', [
'message' => $exception->getMessage(),
'trace' => $exception->getTraceAsString(),
]);
return null;
}
}
}
Finally, delete the secret_key entry from the config/jwt.php file, and JWT_SECRET_KEY from the .env file.
Performance Optimization
While safer, asymmetric encryption is generally slower than symmetric encryption as symmetric encryption can process larger amounts of data in less time and with less overhead. Also, reading a key file from disk introduces latency, especially if the file is accessed frequently. If the encode or decode method of the class are invoked multiple times, the files will be accessed repeatedly, compounding latency.
To optimize performance, we can minimize or eliminate redundant disk I/O operations when encoding or decoding JWTs. This can be achieved by loading the keys into memory once and reusing them. The great thing is that Laravel provides an easy solution for this in the form of configuration variables which can be cached during deployment.
# add to your .env file
JWT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
<private key here>
-----END RSA PRIVATE KEY-----"
JWT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
<public key here>
-----END PUBLIC KEY-----"
Next we update the config/jwt.php configuration file
// previous config entries
/*
|--------------------------------------------------------------------------
| Encryption Keys
|--------------------------------------------------------------------------
|
| JWT uses encryption keys while generating secure access tokens for your
| application. By default, the keys are stored as local files but can
| be set via environment variables when that is more convenient.
|
*/
'encryption_keys' => [
'private_key' => env('JWT_PRIVATE_KEY'),
'private_key_filename' => env('JWT_PRIVATE_KEY_FILENAME', 'auth_private.key'),
'public_key' => env('JWT_PUBLIC_KEY')
'public_key_filename' => env('JWT_PUBLIC_KEY_FILENAME', 'auth_public.key'),
],
Then we need to update the JWTCodec class to first read the encryption key content from the config variables before performing a disk I/O.
<?php
declare(strict_types=1);
namespace App\Services;
use App\Support\Enums\EncryptionKeyType;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use Illuminate\Contracts\Filesystem\FileNotFoundException;
use Illuminate\Support\Facades\Log;
class JWTCodec
{
private ?string $privateKey = null;
private ?string $publicKey = null;
/**
* Encode a payload into a jwt.
*
* @throws \Throwable
*/
public function encode(array $payload): ?string
{
$privateKey = $this->getEncryptionKey(EncryptionKeyType::PRIVATE);
try {
return JWT::encode($payload, $privateKey, (string) config('jwt.algorithm'));
} catch (\Throwable $exception) {
Log::error('JWT encoding failed', [
'message' => $exception->getMessage(),
'trace' => $exception->getTraceAsString(),
]);
return null;
}
}
/**
* Decode a jwt into an array.
*
* @throws \Throwable
*/
public function decode(string $jwt): ?array
{
$publicKey = $this->getEncryptionKey(EncryptionKeyType::PUBLIC);
try {
$payload = JWT::decode($jwt, new Key($publicKey, (string) config('jwt.algorithm')));
return (array) $payload;
} catch (\Throwable $exception) {
Log::error('JWT decoding failed', [
'message' => $exception->getMessage(),
'trace' => $exception->getTraceAsString(),
]);
return null;
}
}
/**
* Retrieve an encryption key from config or storage.
*
* @throws \Throwable
*/
private function getEncryptionKey(EncryptionKeyType $type): string
{
if ($type === EncryptionKeyType::PRIVATE && ! empty($this->privateKey)) {
return $this->privateKey;
}
if ($type === EncryptionKeyType::PUBLIC && ! empty($this->publicKey)) {
return $this->publicKey;
}
$key = (string) config("jwt.encryption_keys.{$type->value()}_key");
if (empty($key)) {
$disk = get_encryption_keys_storage_disk();
$filename = (string) config("jwt.encryption_keys.{$type->value()}_key_filename");
throw_if(
! $disk->exists($filename),
new FileNotFoundException(sprintf('Could not find the %s key file: %s', $type->value(), $filename))
);
$key = $disk->get($filename);
}
if ($type === EncryptionKeyType::PRIVATE) {
$this->privateKey = $key;
}
if ($type === EncryptionKeyType::PUBLIC) {
$this->publicKey = $key;
}
return $key;
}
}
The get_encryption_keys_storage_disk method is an helper method that retrieves the disk the encryption keys are stored on. The EncryptionKeyType enum defines two types of keys, PUBLIC and PRIVATE, and includes a value method which returns the name of the enum in lowercase. This value is then used to fetch the appropriate key from configuration or storage.
<?php
declare(strict_types=1);
namespace App\Support\Enums;
enum EncryptionKeyType
{
case PUBLIC;
case PRIVATE;
public function value(): string
{
return strtolower($this->name);
}
}
Finally, register the JWTCodec class as a singleton in the application's container. Doing this ensures that only one instance of the class is used throughout the request lifecycle.
<?php
declare(strict_types=1);
namespace App\Providers;
use App\Services\JWTCodec;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* Register any application services.
*/
public function register(): void
{
$this->app->singleton(JWTCodec::class, fn ($app) => new JWTCodec());
}
}
Best Practices and Deployment
Proper key management forms the foundation of a secure JWT authentication system. Therefore, never commit your encryption keys to version control and always maintain secure backups of your keys. Many cloud platforms provide secure key management services (KMS) which can be used instead of .env files for production environments. Using them improves security as most KMS products support key rotation.
During key rotation, ensure all servers are updated in a coordinated manner. It is also advisable to deploy new public keys before rotating private keys to ensure a smooth transition. Monitoring and logging also play crucial roles in maintaining a healthy JWT authentication system. Track JWT decode failures and invalid token attempts to detect potential security issues. Also, set up alerts for unusual patterns that might indicate problems.
Before deploying to production, follow this essential checklist:
- Generate production RSA keys with appropriate length.
- Configure secure key storage and environment variables.
- Cache your application configuration.
- Test token generation and validation thoroughly.
- Document your deployment and key rotation procedures.
- Set up monitoring and logging systems.
Have emergency procedures ready for key compromise scenarios. This should include steps for emergency key rotation and service recovery. Maintain clear documentation of these procedures and ensure relevant team members understand their roles in emergency situations. Also, periodically audit your key management practices, token configurations and monitoring systems to adapt to evolving security threats. By following these practices, you'll build a robust and secure JWT authentication system that's ready for production use. Remember that security is an ongoing process - regularly audit and update these practices as your system evolves and new security considerations emerge.
Summary and Next Steps
In this part of the series, we explored the fundamentals of implementing JWT authentication in Laravel, using both symmetric and asymmetric cryptography. We covered setting up the Firebase PHP JWT package, creating a JWTCodec class for token handling, and generating RSA key pairs for enhanced security. We also tackled performance optimization by caching encryption keys in memory to minimize disk I/O by leveraging Laravel's configuration features and deployment considerations for production systems.
In the next part of this series, we will implement a login endpoint that validates user credentials and issues tokens on successful validation. Then we will create a custom guard to authenticate API requests using JWTs.
The code for this tutorial is available on GitHub for you to read, clone, fork or star. If you have any challenges with the tutorial, I can reached via Twitter/X or LinkedIn. Please don't forget to share if you have found it useful.