README

PHP-JWT

一个简单的PHP库，用于编码和解码符合RFC 7519的JSON Web Tokens (JWT)。

安装

使用composer管理依赖并下载PHP-JWT

composer require firebase/php-jwt

可选地，如果你的PHP版本小于7.2或未安装libsodium，可以使用composer安装paragonie/sodium_compat包

composer require paragonie/sodium_compat

示例

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$key = 'example_key';
$payload = [
    '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'));

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 = [
    '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";

带密码的示例

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 = [
    '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";

EdDSA (libsodium和Ed25519签名) 示例

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 = [
    '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";

使用JWKs

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 Firebase\JWT\Key
// objects. Pass this as the second parameter to JWT::decode.
JWT::decode($payload, JWK::parseKeySet($jwks));

使用缓存密钥集

CachedKeySet类可以用于从公开URI获取并缓存JWKS（JSON Web Key Sets）。以下是一些优点：

结果被缓存以提高性能。
如果请求了未识别的密钥，则刷新缓存，以适应密钥轮换。
如果启用了速率限制，则JWKS URI每秒不会进行超过10次请求。

use Firebase\JWT\CachedKeySet;
use Firebase\JWT\JWT;

// The URI for the JWKS you wish to cache the results from
$jwksUri = 'https://www.gstatic.com/iap/verify/public_key-jwk';

// Create an HTTP client (can be any PSR-7 compatible HTTP client)
$httpClient = new GuzzleHttp\Client();

// Create an HTTP request factory (can be any PSR-17 compatible HTTP request factory)
$httpFactory = new GuzzleHttp\Psr\HttpFactory();

// Create a cache item pool (can be any PSR-6 compatible cache item pool)
$cacheItemPool = Phpfastcache\CacheManager::getInstance('files');

$keySet = new CachedKeySet(
    $jwksUri,
    $httpClient,
    $httpFactory,
    $cacheItemPool,
    null, // $expiresAfter int seconds to set the JWKS to expire
    true  // $rateLimit    true to enable rate limit of 10 RPS on lookup of invalid keys
);

$jwt = 'eyJhbGci...'; // Some JWT signed by a key from the $jwkUri above
$decoded = JWT::decode($jwt, $keySet);

杂项

转换为数组

JWT::decode的返回值是通用的PHP对象stdClass。如果您想用数组来处理，可以这样做：

// return type is stdClass
$decoded = JWT::decode($payload, $keys);

// cast to array
$decoded = json_decode(json_encode($decoded), true);

变更日志

6.3.0 / 2022-07-15

添加了对JWK解析的ES256支持（《https://github.com/firebase/php-jwt/pull/399》#399）
通过将jwks作为字符串缓存，在CachedKeySet中修复了潜在的缓存错误（《https://github.com/firebase/php-jwt/pull/435》#435）

6.2.0 / 2022-05-14

添加了CachedKeySet（《https://github.com/firebase/php-jwt/pull/397》#397）
为JWT::parseKey和JWT::parseKeySet添加了$defaultAlg参数（《https://github.com/firebase/php-jwt/pull/426》#426）。

6.1.0 / 2022-03-23

停止支持PHP 5.3、5.4、5.5、5.6和7.0
尽可能添加参数类型和返回类型

6.0.0 / 2022-01-24

向后不兼容的更改：有关更多信息，请参阅发行说明。
添加新的密钥对象以防止密钥/算法类型混淆（#365）
添加了对JWK的支持（#273）
添加了对ES256的支持（#256）
添加了对ES384的支持（#324）
添加了对Ed25519的支持（#343）

5.0.0 / 2017-06-26

支持RS384和RS512。请参阅#117。感谢@joostfaassen！
添加了RS256 openssl的示例。请参阅#125。感谢@akeeman！
检测签名中的无效Base64编码。请参阅#162。感谢@psignoret！
更新JWT::verify以处理OpenSSL错误。请参阅#159。感谢@bshaffer！
为decode方法添加array类型提示。请参阅#101。感谢@hywak！
添加所有JSON错误类型。请参阅 #110。感谢 @gbalduzzi!
修复了 'kid' 不在给定密钥列表中的错误。请参阅 #129。感谢 @stampycode!
杂项清理、文档和测试修复。请参阅 #107、#115、#160、#161 和 #165。感谢 @akeeman、@chinedufn 和 @bshaffer!

4.0.0 / 2016-07-17

添加了对静态绑定的支持。请参阅 #88 了解详情。感谢 @chappy84!
使用静态 $timestamp 而不是 time() 来提高单元测试。请参阅 #93 了解详情。感谢 @josephmcdermott!
修复了异常类。请参阅 #81 了解详情。感谢 @Maks3w!
修复了 PHPDoc。请参阅 #76 了解详情。感谢 @akeeman!

3.0.0 / 2015-07-22

最低PHP版本从 5.2.0 更新到 5.3.0。
添加了 \Firebase\JWT 命名空间。请参阅 #59 了解详情。感谢 @Dashron!
在解码和验证JWT时需要一个非空密钥。请参阅 #60 了解详情。感谢 @sjones608!
代码中的文档块更清晰。请参阅 #62 了解详情。感谢 @johanderuijter!

2.2.0 / 2015-06-22

为 JWT::encode() 添加了支持添加自定义的、可选的JWT头。请参阅 #53 了解详情。感谢 @mcocaro!

2.1.0 / 2015-05-20

为 JWT:decode() 添加了支持添加一个容错值，以考虑签名和验证实体之间的时钟偏差。感谢 @lcabral!
为 JWT::decode() 中的 $keys 参数添加了支持传递实现 ArrayAccess 接口的对象。感谢 @aztech-dev!

2.0.0 / 2015-04-01

注意：强烈建议您更新到 > v2.0.0，以解决在使用对称和非对称密钥一起使用时先前版本中已知的安全漏洞。
更新 JWT::decode(...) 的签名，要求使用支持算法的数组来验证令牌签名。

测试

使用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)

私钥中的新行

如果您的私钥包含 \n 字符，请确保将其用双引号 "" 而不是单引号 '' 括起来，以便正确解释转义字符。

许可证

3-Clause BSD.

mderakhshi / php-jwt

维护者

详细信息