README

PHP-JWT

A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to RFC 7519.

Installation

Use composer to manage your dependencies and download PHP-JWT:

composer require firebase/php-jwt

Optionally, install the paragonie/sodium_compat package from composer if your php is < 7.2 or does not have libsodium installed:

composer require paragonie/sodium_compat

Example

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
 
$key = "example_key";
$payload = array(
    "iss" => "http://example.org",
    "aud" => "http://example.com",
    "iat" => 1356999524,
    "nbf" => 1357000000
);
 
$jwt = JWT::encode($payload, $key, 'HS256');
$decoded = JWT::decode($jwt, new Key($key, 'HS256'));
 
print_r($decoded);
 
/*
 NOTE: This will now be an object instead of an associative array. To get
 an associative array, you will need to cast it as such:
*/
 
$decoded_array = (array) $decoded;
 
JWT::$leeway = 60; // $leeway in seconds
$decoded = JWT::decode($jwt, new Key($key, 'HS256'));

Example with RS256 (openssl)

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
 
$privateKey = <<<EOD
-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQC8kGa1pSjbSYZVebtTRBLxBz5H4i2p/llLCrEeQhta5kaQu/Rn
vuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t0tyazyZ8JXw+KgXTxldMPEL9
5+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4ehde/zUxo6UvS7UrBQIDAQAB
AoGAb/MXV46XxCFRxNuB8LyAtmLDgi/xRnTAlMHjSACddwkyKem8//8eZtw9fzxz
bWZ/1/doQOuHBGYZU8aDzzj59FZ78dyzNFoF91hbvZKkg+6wGyd/LrGVEB+Xre0J
Nil0GReM2AHDNZUYRv+HYJPIOrB0CRczLQsgFJ8K6aAD6F0CQQDzbpjYdx10qgK1
cP59UHiHjPZYC0loEsk7s+hUmT3QHerAQJMZWC11Qrn2N+ybwwNblDKv+s5qgMQ5
5tNoQ9IfAkEAxkyffU6ythpg/H0Ixe1I2rd0GbF05biIzO/i77Det3n4YsJVlDck
ZkcvY3SK2iRIL4c9yY6hlIhs+K9wXTtGWwJBAO9Dskl48mO7woPR9uD22jDpNSwe
k90OMepTjzSvlhjbfuPN1IdhqvSJTDychRwn1kIJ7LQZgQ8fVz9OCFZ/6qMCQGOb
qaGwHmUK6xzpUbbacnYrIM6nLSkXgOAwv7XXCojvY614ILTK3iXiLBOxPu5Eu13k
eUz9sHyD6vkgZzjtxXECQAkp4Xerf5TGfQXGXhxIX52yH+N2LtujCdkQZjXAsGdm
B2zNzvrlgRmgBrklMTrMYgm1NPcW+bRLGcwgW2PTvNM=
-----END RSA PRIVATE KEY-----
EOD;
 
$publicKey = <<<EOD
-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC8kGa1pSjbSYZVebtTRBLxBz5H
4i2p/llLCrEeQhta5kaQu/RnvuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t
0tyazyZ8JXw+KgXTxldMPEL95+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4
ehde/zUxo6UvS7UrBQIDAQAB
-----END PUBLIC KEY-----
EOD;
 
$payload = array(
    "iss" => "example.org",
    "aud" => "example.com",
    "iat" => 1356999524,
    "nbf" => 1357000000
);
 
$jwt = JWT::encode($payload, $privateKey, 'RS256');
echo "Encode:\n" . print_r($jwt, true) . "\n";
 
$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));
 
/*
 NOTE: This will now be an object instead of an associative array. To get
 an associative array, you will need to cast it as such:
*/
 
$decoded_array = (array) $decoded;
echo "Decode:\n" . print_r($decoded_array, true) . "\n";

Example with a passphrase

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
 
// Your passphrase
$passphrase = '[YOUR_PASSPHRASE]';
 
// Your private key file with passphrase
// Can be generated with "ssh-keygen -t rsa -m pem"
$privateKeyFile = '/path/to/key-with-passphrase.pem';
 
// Create a private key of type "resource"
$privateKey = openssl_pkey_get_private(
    file_get_contents($privateKeyFile),
    $passphrase
);
 
$payload = array(
    "iss" => "example.org",
    "aud" => "example.com",
    "iat" => 1356999524,
    "nbf" => 1357000000
);
 
$jwt = JWT::encode($payload, $privateKey, 'RS256');
echo "Encode:\n" . print_r($jwt, true) . "\n";
 
// Get public key from the private key, or pull from from a file.
$publicKey = openssl_pkey_get_details($privateKey)['key'];
 
$decoded = JWT::decode($jwt, new Key($publicKey, 'RS256'));
echo "Decode:\n" . print_r((array) $decoded, true) . "\n";

Example with EdDSA (libsodium and Ed25519 signature)

use Firebase\JWT\JWT;
use Firebase\JWT\Key;
 
// Public and private keys are expected to be Base64 encoded. The last
// non-empty line is used so that keys can be generated with
// sodium_crypto_sign_keypair(). The secret keys generated by other tools may
// need to be adjusted to match the input expected by libsodium.
 
$keyPair = sodium_crypto_sign_keypair();
 
$privateKey = base64_encode(sodium_crypto_sign_secretkey($keyPair));
 
$publicKey = base64_encode(sodium_crypto_sign_publickey($keyPair));
 
$payload = array(
    "iss" => "example.org",
    "aud" => "example.com",
    "iat" => 1356999524,
    "nbf" => 1357000000
);
 
$jwt = JWT::encode($payload, $privateKey, 'EdDSA');
echo "Encode:\n" . print_r($jwt, true) . "\n";
 
$decoded = JWT::decode($jwt, new Key($publicKey, 'EdDSA'));
echo "Decode:\n" . print_r((array) $decoded, true) . "\n";
````
 
Using JWKs
----------
 
```php
use Firebase\JWT\JWK;
use Firebase\JWT\JWT;
 
// Set of keys. The "keys" key is required. For example, the JSON response to
// this endpoint: https://www.gstatic.com/iap/verify/public_key-jwk
$jwks = ['keys' => []];
 
// JWK::parseKeySet($jwks) returns an associative array of **kid** to private
// key. Pass this as the second parameter to JWT::decode.
// NOTE: The deprecated $supportedAlgorithm must be supplied when parsing from JWK.
JWT::decode($payload, JWK::parseKeySet($jwks), $supportedAlgorithm);

Changelog

5.0.0 / 2017-06-26

• Support RS384 and RS512. See #117. Thanks @joostfaassen!
• Add an example for RS256 openssl. See #125. Thanks @akeeman!
• Detect invalid Base64 encoding in signature. See #162. Thanks @psignoret!
• Update JWT::verify to handle OpenSSL errors. See #159. Thanks @bshaffer!
• Add array type hinting to decode method See #101. Thanks @hywak!
• Add all JSON error types. See #110. Thanks @gbalduzzi!
• Bugfix 'kid' not in given key list. See #129. Thanks @stampycode!
• Miscellaneous cleanup, documentation and test fixes. See #107, #115, #160, #161, and #165. Thanks @akeeman, @chinedufn, and @bshaffer!

4.0.0 / 2016-07-17

• Add support for late static binding. See #88 for details. Thanks to @chappy84!
• Use static $timestamp instead of time() to improve unit testing. See #93 for details. Thanks to @josephmcdermott!
• Fixes to exceptions classes. See #81 for details. Thanks to @Maks3w!
• Fixes to PHPDoc. See #76 for details. Thanks to @akeeman!

3.0.0 / 2015-07-22

• Minimum PHP version updated from 5.2.0 to 5.3.0.
• Add \Firebase\JWT namespace. See #59 for details. Thanks to @Dashron!
• Require a non-empty key to decode and verify a JWT. See #60 for details. Thanks to @sjones608!
• Cleaner documentation blocks in the code. See #62 for details. Thanks to @johanderuijter!

2.2.0 / 2015-06-22

• Add support for adding custom, optional JWT headers to JWT::encode(). See #53 for details. Thanks to @mcocaro!

2.1.0 / 2015-05-20

• Add support for adding a leeway to JWT:decode() that accounts for clock skew between signing and verifying entities. Thanks to @lcabral!
• Add support for passing an object implementing the ArrayAccess interface for $keys argument in JWT::decode(). Thanks to @aztech-dev!

2.0.0 / 2015-04-01

• Note: It is strongly recommended that you update to > v2.0.0 to address known security vulnerabilities in prior versions when both symmetric and asymmetric keys are used together.
• Update signature for JWT::decode(...) to require an array of supported algorithms to use when verifying token signatures.

Tests

Run the tests using phpunit:

$ pear install PHPUnit
$ phpunit --configuration phpunit.xml.dist
PHPUnit 3.7.10 by Sebastian Bergmann.
.....
Time: 0 seconds, Memory: 2.50Mb
OK (5 tests, 5 assertions)

New Lines in private keys

If your private key contains \n characters, be sure to wrap it in double quotes "" and not single quotes ‘’'` in order to properly interpret the escaped characters.

License

3-Clause BSD.