Subversion Repositories oidplus

[![Build Status](https://travis-ci.org/firebase/php-jwt.png?branch=master)](https://travis-ci.org/firebase/php-jwt)

[![Latest Stable Version](https://poser.pugx.org/firebase/php-jwt/v/stable)](https://packagist.org/packages/firebase/php-jwt)

[![Total Downloads](https://poser.pugx.org/firebase/php-jwt/downloads)](https://packagist.org/packages/firebase/php-jwt)

[![License](https://poser.pugx.org/firebase/php-jwt/license)](https://packagist.org/packages/firebase/php-jwt)

PHP-JWT

=======

A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to [RFC 7519](https://tools.ietf.org/html/rfc7519).

Installation

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

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

```bash

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:

```bash

composer require paragonie/sodium_compat

```

Example

-------

```php

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

);

/**

 * IMPORTANT:

 * You must specify supported algorithms for your application. See

 * https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40

 * for a list of spec-compliant algorithms.

 */

$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;

/**

 * You can add a leeway to account for when there is a clock skew times between

 * the signing and verifying servers. It is recommended that this leeway should

 * not be bigger than a few minutes.

 *

 * Source: http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#nbfDef

 */

JWT::$leeway = 60; // $leeway in seconds

$decoded = JWT::decode($jwt, new Key($key, 'HS256'));

```

Example with RS256 (openssl)

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

```php

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

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

```php

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)

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

```php

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](https://github.com/firebase/php-jwt/pull/117). Thanks [@joostfaassen](https://github.com/joostfaassen)!

- Add an example for RS256 openssl.

  See [#125](https://github.com/firebase/php-jwt/pull/125). Thanks [@akeeman](https://github.com/akeeman)!

- Detect invalid Base64 encoding in signature.

  See [#162](https://github.com/firebase/php-jwt/pull/162). Thanks [@psignoret](https://github.com/psignoret)!

- Update `JWT::verify` to handle OpenSSL errors.

  See [#159](https://github.com/firebase/php-jwt/pull/159). Thanks [@bshaffer](https://github.com/bshaffer)!

- Add `array` type hinting to `decode` method

  See [#101](https://github.com/firebase/php-jwt/pull/101). Thanks [@hywak](https://github.com/hywak)!

- Add all JSON error types.

  See [#110](https://github.com/firebase/php-jwt/pull/110). Thanks [@gbalduzzi](https://github.com/gbalduzzi)!

- Bugfix 'kid' not in given key list.

  See [#129](https://github.com/firebase/php-jwt/pull/129). Thanks [@stampycode](https://github.com/stampycode)!

- Miscellaneous cleanup, documentation and test fixes.

  See [#107](https://github.com/firebase/php-jwt/pull/107), [#115](https://github.com/firebase/php-jwt/pull/115),

  [#160](https://github.com/firebase/php-jwt/pull/160), [#161](https://github.com/firebase/php-jwt/pull/161), and

  [#165](https://github.com/firebase/php-jwt/pull/165). Thanks [@akeeman](https://github.com/akeeman),

  [@chinedufn](https://github.com/chinedufn), and [@bshaffer](https://github.com/bshaffer)!

#### 4.0.0 / 2016-07-17

- Add support for late static binding. See [#88](https://github.com/firebase/php-jwt/pull/88) for details. Thanks to [@chappy84](https://github.com/chappy84)!

- Use static `$timestamp` instead of `time()` to improve unit testing. See [#93](https://github.com/firebase/php-jwt/pull/93) for details. Thanks to [@josephmcdermott](https://github.com/josephmcdermott)!

- Fixes to exceptions classes. See [#81](https://github.com/firebase/php-jwt/pull/81) for details. Thanks to [@Maks3w](https://github.com/Maks3w)!

- Fixes to PHPDoc. See [#76](https://github.com/firebase/php-jwt/pull/76) for details. Thanks to [@akeeman](https://github.com/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](https://github.com/firebase/php-jwt/pull/59) for details. Thanks to

[@Dashron](https://github.com/Dashron)!

- Require a non-empty key to decode and verify a JWT. See

[#60](https://github.com/firebase/php-jwt/pull/60) for details. Thanks to

[@sjones608](https://github.com/sjones608)!

- Cleaner documentation blocks in the code. See

[#62](https://github.com/firebase/php-jwt/pull/62) for details. Thanks to

[@johanderuijter](https://github.com/johanderuijter)!

#### 2.2.0 / 2015-06-22

- Add support for adding custom, optional JWT headers to `JWT::encode()`. See

[#53](https://github.com/firebase/php-jwt/pull/53/files) for details. Thanks to

[@mcocaro](https://github.com/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](https://github.com/lcabral)!

- Add support for passing an object implementing the `ArrayAccess` interface for

`$keys` argument in `JWT::decode()`. Thanks to [@aztech-dev](https://github.com/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:

```bash

$ 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](http://opensource.org/licenses/BSD-3-Clause).