README.md
201 lines
| 1 | [](https://travis-ci.org/firebase/php-jwt](https://travis-ci.org/firebase/php-jwt](https://travis-ci.org/firebase/php-jwt) |
| 2 | [](https://packagist.org/packages/firebase/php-jwt](https://packagist.org/packages/firebase/php-jwt](https://packagist.org/packages/firebase/php-jwt) |
| 3 | [](https://packagist.org/packages/firebase/php-jwt](https://packagist.org/packages/firebase/php-jwt](https://packagist.org/packages/firebase/php-jwt) |
| 4 | [](https://packagist.org/packages/firebase/php-jwt](https://packagist.org/packages/firebase/php-jwt](https://packagist.org/packages/firebase/php-jwt) |
| 5 | |
| 6 | PHP-JWT |
| 7 | ======= |
| 8 | A simple library to encode and decode JSON Web Tokens (JWT) in PHP, conforming to [](https://tools.ietf.org/html/rfc7519RFC 7519](https://tools.ietf.org/html/rfc7519](https://tools.ietf.org/html/rfc7519). |
| 9 | |
| 10 | Installation |
| 11 | ------------ |
| 12 | |
| 13 | Use composer to manage your dependencies and download PHP-JWT: |
| 14 | |
| 15 | ```bash |
| 16 | composer require firebase/php-jwt |
| 17 | ``` |
| 18 | |
| 19 | Example |
| 20 | ------- |
| 21 | ```php |
| 22 | <?php |
| 23 | use \Firebase\JWT\JWT; |
| 24 | |
| 25 | $key = "example_key"; |
| 26 | $token = array( |
| 27 | "iss" => "http://example.org", |
| 28 | "aud" => "http://example.com", |
| 29 | "iat" => 1356999524, |
| 30 | "nbf" => 1357000000 |
| 31 | ); |
| 32 | |
| 33 | /** |
| 34 | * IMPORTANT: |
| 35 | * You must specify supported algorithms for your application. See |
| 36 | * https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40 |
| 37 | * for a list of spec-compliant algorithms. |
| 38 | */ |
| 39 | $jwt = JWT::encode($token, $key); |
| 40 | $decoded = JWT::decode($jwt, $key, array('HS256')); |
| 41 | |
| 42 | print_r($decoded); |
| 43 | |
| 44 | /* |
| 45 | NOTE: This will now be an object instead of an associative array. To get |
| 46 | an associative array, you will need to cast it as such: |
| 47 | */ |
| 48 | |
| 49 | $decoded_array = (array) $decoded; |
| 50 | |
| 51 | /** |
| 52 | * You can add a leeway to account for when there is a clock skew times between |
| 53 | * the signing and verifying servers. It is recommended that this leeway should |
| 54 | * not be bigger than a few minutes. |
| 55 | * |
| 56 | * Source: http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html#nbfDef |
| 57 | */ |
| 58 | JWT::$leeway = 60; // $leeway in seconds |
| 59 | $decoded = JWT::decode($jwt, $key, array('HS256')); |
| 60 | |
| 61 | ?> |
| 62 | ``` |
| 63 | Example with RS256 (openssl) |
| 64 | ---------------------------- |
| 65 | ```php |
| 66 | <?php |
| 67 | use \Firebase\JWT\JWT; |
| 68 | |
| 69 | $privateKey = <<<EOD |
| 70 | -----BEGIN RSA PRIVATE KEY----- |
| 71 | MIICXAIBAAKBgQC8kGa1pSjbSYZVebtTRBLxBz5H4i2p/llLCrEeQhta5kaQu/Rn |
| 72 | vuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t0tyazyZ8JXw+KgXTxldMPEL9 |
| 73 | 5+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4ehde/zUxo6UvS7UrBQIDAQAB |
| 74 | AoGAb/MXV46XxCFRxNuB8LyAtmLDgi/xRnTAlMHjSACddwkyKem8//8eZtw9fzxz |
| 75 | bWZ/1/doQOuHBGYZU8aDzzj59FZ78dyzNFoF91hbvZKkg+6wGyd/LrGVEB+Xre0J |
| 76 | Nil0GReM2AHDNZUYRv+HYJPIOrB0CRczLQsgFJ8K6aAD6F0CQQDzbpjYdx10qgK1 |
| 77 | cP59UHiHjPZYC0loEsk7s+hUmT3QHerAQJMZWC11Qrn2N+ybwwNblDKv+s5qgMQ5 |
| 78 | 5tNoQ9IfAkEAxkyffU6ythpg/H0Ixe1I2rd0GbF05biIzO/i77Det3n4YsJVlDck |
| 79 | ZkcvY3SK2iRIL4c9yY6hlIhs+K9wXTtGWwJBAO9Dskl48mO7woPR9uD22jDpNSwe |
| 80 | k90OMepTjzSvlhjbfuPN1IdhqvSJTDychRwn1kIJ7LQZgQ8fVz9OCFZ/6qMCQGOb |
| 81 | qaGwHmUK6xzpUbbacnYrIM6nLSkXgOAwv7XXCojvY614ILTK3iXiLBOxPu5Eu13k |
| 82 | eUz9sHyD6vkgZzjtxXECQAkp4Xerf5TGfQXGXhxIX52yH+N2LtujCdkQZjXAsGdm |
| 83 | B2zNzvrlgRmgBrklMTrMYgm1NPcW+bRLGcwgW2PTvNM= |
| 84 | -----END RSA PRIVATE KEY----- |
| 85 | EOD; |
| 86 | |
| 87 | $publicKey = <<<EOD |
| 88 | -----BEGIN PUBLIC KEY----- |
| 89 | MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC8kGa1pSjbSYZVebtTRBLxBz5H |
| 90 | 4i2p/llLCrEeQhta5kaQu/RnvuER4W8oDH3+3iuIYW4VQAzyqFpwuzjkDI+17t5t |
| 91 | 0tyazyZ8JXw+KgXTxldMPEL95+qVhgXvwtihXC1c5oGbRlEDvDF6Sa53rcFVsYJ4 |
| 92 | ehde/zUxo6UvS7UrBQIDAQAB |
| 93 | -----END PUBLIC KEY----- |
| 94 | EOD; |
| 95 | |
| 96 | $token = array( |
| 97 | "iss" => "example.org", |
| 98 | "aud" => "example.com", |
| 99 | "iat" => 1356999524, |
| 100 | "nbf" => 1357000000 |
| 101 | ); |
| 102 | |
| 103 | $jwt = JWT::encode($token, $privateKey, 'RS256'); |
| 104 | echo "Encode:\n" . print_r($jwt, true) . "\n"; |
| 105 | |
| 106 | $decoded = JWT::decode($jwt, $publicKey, array('RS256')); |
| 107 | |
| 108 | /* |
| 109 | NOTE: This will now be an object instead of an associative array. To get |
| 110 | an associative array, you will need to cast it as such: |
| 111 | */ |
| 112 | |
| 113 | $decoded_array = (array) $decoded; |
| 114 | echo "Decode:\n" . print_r($decoded_array, true) . "\n"; |
| 115 | ?> |
| 116 | ``` |
| 117 | |
| 118 | Changelog |
| 119 | --------- |
| 120 | |
| 121 | #### 5.0.0 / 2017-06-26 |
| 122 | - Support RS384 and RS512. |
| 123 | See [#117](https://github.com/firebase/php-jwt/pull/117). Thanks [@joostfaassen](https://github.com/joostfaassen)! |
| 124 | - Add an example for RS256 openssl. |
| 125 | See [#125](https://github.com/firebase/php-jwt/pull/125). Thanks [@akeeman](https://github.com/akeeman)! |
| 126 | - Detect invalid Base64 encoding in signature. |
| 127 | See [#162](https://github.com/firebase/php-jwt/pull/162). Thanks [@psignoret](https://github.com/psignoret)! |
| 128 | - Update `JWT::verify` to handle OpenSSL errors. |
| 129 | See [#159](https://github.com/firebase/php-jwt/pull/159). Thanks [@bshaffer](https://github.com/bshaffer)! |
| 130 | - Add `array` type hinting to `decode` method |
| 131 | See [#101](https://github.com/firebase/php-jwt/pull/101). Thanks [@hywak](https://github.com/hywak)! |
| 132 | - Add all JSON error types. |
| 133 | See [#110](https://github.com/firebase/php-jwt/pull/110). Thanks [@gbalduzzi](https://github.com/gbalduzzi)! |
| 134 | - Bugfix 'kid' not in given key list. |
| 135 | See [#129](https://github.com/firebase/php-jwt/pull/129). Thanks [@stampycode](https://github.com/stampycode)! |
| 136 | - Miscellaneous cleanup, documentation and test fixes. |
| 137 | See [#107](https://github.com/firebase/php-jwt/pull/107), [#115](https://github.com/firebase/php-jwt/pull/115), |
| 138 | [#160](https://github.com/firebase/php-jwt/pull/160), [#161](https://github.com/firebase/php-jwt/pull/161), and |
| 139 | [#165](https://github.com/firebase/php-jwt/pull/165). Thanks [@akeeman](https://github.com/akeeman), |
| 140 | [@chinedufn](https://github.com/chinedufn), and [@bshaffer](https://github.com/bshaffer)! |
| 141 | |
| 142 | #### 4.0.0 / 2016-07-17 |
| 143 | - 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)! |
| 144 | - 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)! |
| 145 | - Fixes to exceptions classes. See [#81](https://github.com/firebase/php-jwt/pull/81) for details. Thanks to [@Maks3w](https://github.com/Maks3w)! |
| 146 | - Fixes to PHPDoc. See [#76](https://github.com/firebase/php-jwt/pull/76) for details. Thanks to [@akeeman](https://github.com/akeeman)! |
| 147 | |
| 148 | #### 3.0.0 / 2015-07-22 |
| 149 | - Minimum PHP version updated from `5.2.0` to `5.3.0`. |
| 150 | - Add `\Firebase\JWT` namespace. See |
| 151 | [#59](https://github.com/firebase/php-jwt/pull/59) for details. Thanks to |
| 152 | [@Dashron](https://github.com/Dashron)! |
| 153 | - Require a non-empty key to decode and verify a JWT. See |
| 154 | [#60](https://github.com/firebase/php-jwt/pull/60) for details. Thanks to |
| 155 | [@sjones608](https://github.com/sjones608)! |
| 156 | - Cleaner documentation blocks in the code. See |
| 157 | [#62](https://github.com/firebase/php-jwt/pull/62) for details. Thanks to |
| 158 | [@johanderuijter](https://github.com/johanderuijter)! |
| 159 | |
| 160 | #### 2.2.0 / 2015-06-22 |
| 161 | - Add support for adding custom, optional JWT headers to `JWT::encode()`. See |
| 162 | [#53](https://github.com/firebase/php-jwt/pull/53/files) for details. Thanks to |
| 163 | [@mcocaro](https://github.com/mcocaro)! |
| 164 | |
| 165 | #### 2.1.0 / 2015-05-20 |
| 166 | - Add support for adding a leeway to `JWT:decode()` that accounts for clock skew |
| 167 | between signing and verifying entities. Thanks to [@lcabral](https://github.com/lcabral)! |
| 168 | - Add support for passing an object implementing the `ArrayAccess` interface for |
| 169 | `$keys` argument in `JWT::decode()`. Thanks to [@aztech-dev](https://github.com/aztech-dev)! |
| 170 | |
| 171 | #### 2.0.0 / 2015-04-01 |
| 172 | - **Note**: It is strongly recommended that you update to > v2.0.0 to address |
| 173 | known security vulnerabilities in prior versions when both symmetric and |
| 174 | asymmetric keys are used together. |
| 175 | - Update signature for `JWT::decode(...)` to require an array of supported |
| 176 | algorithms to use when verifying token signatures. |
| 177 | |
| 178 | |
| 179 | Tests |
| 180 | ----- |
| 181 | Run the tests using phpunit: |
| 182 | |
| 183 | ```bash |
| 184 | $ pear install PHPUnit |
| 185 | $ phpunit --configuration phpunit.xml.dist |
| 186 | PHPUnit 3.7.10 by Sebastian Bergmann. |
| 187 | ..... |
| 188 | Time: 0 seconds, Memory: 2.50Mb |
| 189 | OK (5 tests, 5 assertions) |
| 190 | ``` |
| 191 | |
| 192 | New Lines in private keys |
| 193 | ----- |
| 194 | |
| 195 | If your private key contains `\n` characters, be sure to wrap it in double quotes `""` |
| 196 | and not single quotes `''` in order to properly interpret the escaped characters. |
| 197 | |
| 198 | License |
| 199 | ------- |
| 200 | [](http://opensource.org/licenses/BSD-3-Clause3-Clause BSD](http://opensource.org/licenses/BSD-3-Clause](http://opensource.org/licenses/BSD-3-Clause). |
| 201 |