adhocore/php-jwt

Ultra lightweight, dependency free and standalone JSON web token (JWT) library for PHP5.6 to PHP8.2. This library makes JWT a cheese. It is a minimal JWT integration for PHP.

adhocore/jwt

If you are new to JWT or want to refresh your familiarity with it, please check jwt.io

• Lightweight JSON Web Token (JWT) library for PHP7, PHP8 and beyond.
• Zero dependency (no vendor bloat).
• If you still use PHP5.6, use version 0.1.2

Installation

# PHP7.x, PHP8.x
composer require adhocore/jwt

# PHP5.6 (deprecated)
composer require adhocore/jwt:0.1.2

# For PHP5.4-5.5 (deprecated), use version 0.1.2 with a polyfill for https://php.net/hash_equals

Features

• Six algorithms supported:

'HS256', 'HS384', 'HS512', 'RS256', 'RS384', 'RS512'

• kid support.
• Leeway support 0-120 seconds.
• Timestamp spoofing for tests.
• Passphrase support for RS* algos.

Usage

use Ahc\Jwt\JWT;

// Instantiate with key, algo, maxAge and leeway.
$jwt = new JWT('secret', 'HS256', 3600, 10);

Only the key is required. Defaults will be used for the rest:

$jwt = new JWT('secret');
// algo = HS256, maxAge = 3600, leeway = 0

For RS* algo, the key should be either a resource like below:

$key = openssl_pkey_new([
    'digest_alg' => 'sha256',
    'private_key_bits' => 1024,
    'private_key_type' => OPENSSL_KEYTYPE_RSA,
]);

OR, a string with full path to the RSA private key like below:

$key = '/path/to/rsa.key';

// Then, instantiate JWT with this key and RS* as algo:
$jwt = new JWT($key, 'RS384');

Pro You dont need to specify pub key path, that is deduced from priv key.

Generate JWT token from payload array:

$token = $jwt->encode([
    'uid'    => 1,
    'aud'    => 'http://site.com',
    'scopes' => ['user'],
    'iss'    => 'http://api.mysite.com',
]);

Retrieve the payload array:

$payload = $jwt->decode($token);

Oneliner:

$token   = (new JWT('topSecret', 'HS512', 1800))->encode(['uid' => 1, 'scopes' => ['user']]);
$payload = (new JWT('topSecret', 'HS512', 1800))->decode($token);

Pro

Can pass extra headers into encode() with second parameter:

$token = $jwt->encode($payload, ['hdr' => 'hdr_value']);

Test mocking

Spoof time() for testing token expiry:

$jwt->setTestTimestamp(time() + 10000);

// Throws Exception.
$jwt->parse($token);

Call again without parameter to stop spoofing time():

$jwt->setTestTimestamp();

Examples with kid

$jwt = new JWT(['key1' => 'secret1', 'key2' => 'secret2']);

// Use key2
$token = $jwt->encode(['a' => 1, 'exp' => time() + 1000], ['kid' => 'key2']);

$payload = $jwt->decode($token);

$token = $jwt->encode(['a' => 1, 'exp' => time() + 1000], ['kid' => 'key3']);
// -> Exception with message Unknown key ID key3

Stabillity

The library is now marked at version 1.*.* as being stable in functionality and API.

Integration

Phalcon

Check adhocore/phalcon-ext.

Consideration

Be aware of some security related considerations as outlined here which can be valid for any JWT implementations.

php-jwt's Issues

Release v1.0.0 with PHP5 support dropped

Old versions will still support PHP5

This is done to make PHP typehints work properly and improve code standards.

Add JWT::verify() & support JWT::decode() without verify

Sometimes it is useful to be able to decode the token without validation of the signature or timestamps.
And other times it is useful to just validate the token without (the need to) decoding it.

nbf validation issue

Hi, in the current version:

php-jwt/src/ValidatesJWT.php

Line 89 in 926ef39

['nbf', $this->maxAge - $this->leeway, static::ERROR_TOKEN_NOT_NOW, 'Not now'],

That line should be:

['nbf', -$this->leeway, static::ERROR_TOKEN_NOT_NOW, 'Not now'],

When checking the nbf ("not before") time, then the "max age" value is not relevant.

Let's see an example:

• Current time = 2020-10-08 12:00:00
• Max age = 3 hours = 10800 sec
• nbf = 2020-10-08 11:00:00 (will be valid after this time)
• leeway = 5 sec (allow max 5 sec misalignment of server clocks)

Then the current code would say:

• The token fails the nbf check because:
  • reference value = 2020-10-08 11:00:00 + 3 hours - 5 sec = 2020-10-08 13:59:55
  • And the current time still hasn't reached this value yet.

But it should only subtract the leeway, and leave the irrelevant "max age" out of this:

• The nbf check is successful, because:
  • reference value = 2020-10-08 11:00:00 - 5 sec = 2020-10-08 10:59:55
  • And the current time is greater than this value.

new JWT() - 500 Internal server error

Hello, when I call the route with $jwt = new JWT('secret', 'HS256', 3600, 10); on code, returns Server Error 500, I'm using Docker:

api/test.php:

<?php
  include "../vendor/autoload.php";
	use Ahc\Jwt\JWT;

  $jwt = new JWT('secret', 'HS256', 3600, 10);
?>

Error on POST:

In Try Catch return this error:

Error Object
(
    [message:protected] => Class 'Ahc\Jwt\JWT' not found
    [string:Error:private] => 
    [code:protected] => 0
    [file:protected] => /var/www/html/api/test.php
    [line:protected] => 8
    [trace:Error:private] => Array
        (
        )

    [previous:Error:private] => 
)

When I remove $jwt = new JWT('secret', 'HS256', 3600, 10); the error not occurred.
Any idea how solve this?

ECDSA algo

Unsupported algo PS256

An uncaught Exception was encountered

Type: Ahc\Jwt\JWTException

Message: Unsupported algo PS256

Pass key as string?

From what I can see in docs, it seems only possible to pass a file path in the constructor. It would be helpful if I could pass the key directly as a string without having to create a file first (in my case it's coming from a database). Is there maybe a trick using the resource method somehow?

Move to GitHub action

Move to GitHub action.
Build should run on all php versions currently supported by this library.

validate with public key

Hi,

I managed to include this very user friendly library in a project and create a token that validates on jwt.io.
I am sending this token in a http header to another server where it needs to be validated. This is not working though. The other server only has access to the public key. When I try to echo (new JWT($public_key))->decode($token); I receive an error:

Uncaught Ahc\Jwt\JWTException: Invalid token: Signature failed in JWT.php:153 Stack trace: #0 ....Ahc\Jwt\JWT->decode(Array) #1 {main} thrown in JWT.php on line 153

Surely I am doing something wrong. How can I validate the JWT string and decode it to retrieve its content?

Support header 'kid'

problem with PEM file key

I created a PEM file on server ubuntu 18 with openssl 1.1.1 using this code

 $privkey = openssl_pkey_new([
            'digest_alg' => 'sha256',
            'private_key_bits' => 1024,
            'private_key_type' => OPENSSL_KEYTYPE_RSA,
        ]);
        try {
            openssl_pkey_export_to_file($privkey, 'WEB-INF/config/' . $filename);
        } catch (Exception $e) {
            echo 'Caught exception: ',  $e->getMessage(), "\n";
        }

on the same server it runs well, encoding and decoding as expected.

Then if I try the to decode using the same PEM file on different server (wich use openssl 1.1.1f) it doesn't run saying that signature is invalid.

Doing the same using a string instead of PEM file works. I cannot understand... could it be that PEM file I created depend on specficia server?

Add JWTException

still extends \InvalidArgumentException

Not working with PHP 7

Please change the description

Invalid nbf validation

Closing this. I saw it was fixed in a newer version.