zenstruck/jwt

JSON Object Signing and Encryption library for PHP.

zenstruck/jwt

, _(*1)

Provides a lightweight implementation of the JWS (JSON Web Signature) specification. This library is a fork of namshi/jose., _(*2)

Requirements

1. PHP 5.4.8+ (tested on 5.4, 5.5, 5.6, 7 and HHVM)
2. (Optional) OpenSSL extension (when using RSA/ECDSA signers)
3. (Optional) symfony/polyfill-php56 library (when HMAC signers in PHP versions less than 5.6)

Installation

composer require zenstruck/jwt

When using an HMAC signer in PHP versions less than 5.6, _(*3)

composer require symfony/polyfill-php56

Basic Usage

1. Create, encode and send a token to the user:, _(*4)

   use Zenstruck\JWT\Token;
   use Zenstruck\JWT\Signer\HMAC\HS256;
   
   // create the token
   $token = new Token([
       'username' => 'kevin', // custom claim
       'iss' => 'zenstruck', // set issuer
       'exp' => time() + 86400, // set expiry claim to 1 day from now
   ]);
   
   // can access claims
   $token->get('username'); // kevin
   $token->get('non-existant'); // null
   
   // sign the token
   $token->sign(new HS256(), 'my secret key');
   
   $encodedTokenForUser = (string) $token;
   
   // ...pass to user
   

2. Fetch encoded token from user, decode, verify, validate and access custom claims, _(*5)

   use Zenstruck\JWT\Token;
   use Zenstruck\JWT\Signer\HMAC\HS256;
   use Zenstuck\JWT\Validator\ExpiresAtValidator;
   use Zenstuck\JWT\Validator\IssuerValidator;
   use Zenstruck\JWT\Exception\MalformedToken;
   use Zenstruck\JWT\Exception\UnverifiedToken;
   use Zenstruck\JWT\Exception\Validation\ExpiredToken;
   use Zenstruck\JWT\Exception\ValidationFailed;
   
   $encodedTokenFromUser = // ...fetched from user
   
   try {
       $decodedToken = Token::fromString($encodedTokenFromUser);
   } catch (MalformedToken $e) {
       // token is not correctly formed
   }
   
   // at this point $decodedToken is a JWT but is not yet verified or validated
   
   try {
       $decodedToken->verify(new HS256(), 'my secret key');
   } catch (UnverifiedToken $e) {
       // token could not be verified
   }
   
   try {
       $decodedToken->validate(new ExpiresAtValidator());
       $decodedToken->validate(new IssuerValidator('zenstruck'));
   } catch (ExpiredToken $e) {
       // the token has expired
   } catch (ValidationFailed $e) {
       // token is invalid - in this case, the issuer does not match
   }
   
   // can access claims
   $token->get('username'); // kevin
   $token->get('non-existant'); // null
   

Token Builder

use Zenstruck\JWT\TokenBuilder;

$token = (new TokenBuilder())
    ->issuer('kevin')
    ->subject('zenstruck\jwt')
    ->audience('php community')
    ->expiresAt(new \DateTime('+1 day'))
    ->notBefore(new \DateTime('+1 hour'))
    ->issuedAt() // can pass \DateTime object - uses current time by default
    ->id('foo')
    ->set('foo', 'bar') // set custom claims
    ->create(); // instance of Zenstruck\JWT\Token

Signers

HMAC

These signers require an identical key string to be used for signing and validating., _(*6)

Usage

$token = // ... instance of Zenstruck\JWT\Token
$signer = // an instance of one of the classes in the table above

$token->sign($signer, 'my secret key');
$token->verify($signer, 'my secret key'); // verified
$token->verify($signer, 'invalid secret key'); // unverified - exception thrown

RSA/ECDSA (OpenSSL)

These signers require a private key for signing and a public key for verifying., _(*7)

• PrivateKey: a string (key contents or filename), resource or instance of Zenstruck\JWT\Signer\OpenSSL\PrivateKey
• PublicKey: a string (key contents or filename), resource or instance of Zenstruck\JWT\Signer\OpenSSL\PublicKey
• Keychain: instance of Zenstruck\JWT\Signer\OpenSSL\Keychain contains both a public and private key. Can be passed as the key to both Signer::sign() and Signer::verify().

Usage

$token = // ... instance of Zenstruck\JWT\Token
$signer = // an instance of one of the classes in the table above
$privateKey = // can be string, resource, filename, instance of Zenstruck\JWT\Signer\OpenSSL\PrivateKey, instance of Zenstruck\JWT\Signer\OpenSSL\Keychain
$publicKey = // can be string, resource, filename, instance of Zenstruck\JWT\Signer\OpenSSL\PublicKey, instance of Zenstruck\JWT\Signer\OpenSSL\Keychain

$token->sign($signer, $privateKey);
$token->verify($signer, $publicKey); // verified
$token->verify($signer, '/path/to/unmatched/public/key'); // unverified - exception thrown

Keychain

A keychain contains both a public and private key. When passed a keychain as the key, the signer uses the proper key for the operation., _(*8)

use Zenstruck\JWT\Signer\OpenSSL\Keychain;

$token = // ... instance of Zenstruck\JWT\Token
$signer = // an instance of one of the classes in the table above
$privateKey = // can be string, resource, filename, instance of Zenstruck\JWT\Signer\OpenSSL\PrivateKey
$publicKey = // can be string, resource, filename, instance of Zenstruck\JWT\Signer\OpenSSL\PublicKey

$keychain = new Keychain($publicKey, $privateKey, 'my passphrase');

$token->sign($signer, $keychain);
$token->verify($signer, $keychain); // verified

Validation

Usage

use Zenstruck\JWT\Validator\IssuerValidator;
use Zenstruck\JWT\Validator\AudienceValidator;
use Zenstruck\JWT\Validator\ChainValidator;

$token = // ... instance of Zenstruck\JWT\Token
$validator = new ChainValidator([new IssuerValidator(), new AudienceValidator()]);

try {
    $token->validate($validator);
} catch (ValidationFailed $e) {
    $reason = $e->getMessage();
}

ValidatorBuilder

$validator = (new ValidatorBuilder())
    ->issuer('kevin')
    ->subject('zenstruck\jwt')
    ->audience('php community')
    ->expiresAt()
    ->notBefore()
    ->issuedAt(time())
    ->id('foo')
    ->create(); // instance of Zenstruck\JWT\Validator\ChainValidator