README

一个用于处理 JSON Web Token 和 JSON Web Signature 的简单库（需要 PHP 5.3+）。实现基于当前草案。

重要

• 仅限 Aegis 内部使用。使用此库的风险自行承担。

安装

该软件包在 Packagist 上可用，您可以使用 Composer 安装它。

composer require aegis/jwt

依赖

• PHP 5.3+
• OpenSSL 扩展
• aegis/json

基本用法

创建

只需使用构建器创建新的 JWT/JWS 令牌

use Aegis\JWT\Builder;

$builder = new Builder();

$token = $builder
    ->setIssuer('http://example.com')       // Configures the issuer (iss claim)
    ->setAudience('http://example.org')     // Configures the audience (aud claim)
    ->setId('4f1g23a12aa', true)            // Configures the id (jti claim), replicating as a header item
    ->setIssuedAt(time())                   // Configures the time that the token was issue (iat claim)
    ->setNotBefore(time() + 60)             // Configures the time that the token can be used (nbf claim)
    ->setExpiration(time() + 3600)          // Configures the expiration time of the token (nbf claim)
    ->set('uid', 1)                         // Configures a new claim, called "uid"
    ->getToken()                            // Retrieves the generated token
;


$token->getHeaders();                       // Retrieves the token headers
$token->getClaims();                        // Retrieves the token claims

echo $token->getHeader('jti');              // will print "4f1g23a12aa"
echo $token->getClaim('iss');               // will print "http://example.com"
echo $token->getClaim('uid');               // will print "1"
echo $token;                                // The string representation of the object is a JWT string (pretty easy, right?)

从字符串解析

使用解析器从 JWT 字符串创建新的令牌（以之前的令牌为例）

use Aegis\JWT\Parser;

$parser = new Parser();

$token = $parser->parse((string) $token);   // Parses from a string
$token->getHeaders();                       // Retrieves the token header
$token->getClaims();                        // Retrieves the token claims

echo $token->getHeader('jti');              // will print "4f1g23a12aa"
echo $token->getClaim('iss');               // will print "http://example.com"
echo $token->getClaim('uid');               // will print "1"

验证

我们可以轻松地验证令牌是否有效（以之前的令牌为例）

use Aegis\JWT\ValidationData;

$data = new ValidationData();               // It will use the current time to validate (iat, nbf and exp)
$data->setIssuer('http://example.com');
$data->setAudience('http://example.org');
$data->setId('4f1g23a12aa');

var_dump($token->validate($data));          // true, because validation information is equals to data contained on the token

$data->setCurrentTime(time() + 4000);       // changing the validation time to future

var_dump($token->validate($data));          // false, because token is expired since current time is greater than exp

令牌签名

我们可以使用签名来验证令牌在生成后是否被修改。此库实现了 Hmac、RSA 和 ECDSA 签名（使用 256、384 和 512）。

Hmac

Hmac 签名非常简单易用

use Aegis\JWT\Builder;
use Aegis\JWT\Signer\Hmac\Sha256;

$signer = new Sha256();
$builder = new Builder();

$token = $builder
    ->setIssuer('http://example.com')       // Configures the issuer (iss claim)
    ->setAudience('http://example.org')     // Configures the audience (aud claim)
    ->setId('4f1g23a12aa', true)            // Configures the id (jti claim), replicating as a header item
    ->setIssuedAt(time())                   // Configures the time that the token was issue (iat claim)
    ->setNotBefore(time() + 60)             // Configures the time that the token can be used (nbf claim)
    ->setExpiration(time() + 3600)          // Configures the expiration time of the token (nbf claim)
    ->set('uid', 1)                         // Configures a new claim, called "uid"
    ->sign($signer, 'testing')              // creates a signature using "testing" as key
    ->getToken()                            // Retrieves the generated token
;


$token->verify($signer, 'testing 1'); // false, because the key is different
$token->verify($signer, 'testing');   // true, because the key is the same

RSA 和 ECDSA

RSA 和 ECDSA 签名基于公钥和私钥，因此您需要使用私钥生成并使用公钥验证

use Aegis\JWT\Builder;
use Aegis\JWT\Signer\Keychain;      // just to make our life simpler
use Aegis\JWT\Signer\Rsa\Sha256;    // you can use Aegis\JWT\Signer\Ecdsa\Sha256 if you're using ECDSA keys

$signer = new Sha256();

$keychain = new Keychain();

$builder = new Builder();

$token = $builder
    ->setIssuer('http://example.com')   // Configures the issuer (iss claim)
    ->setAudience('http://example.org') // Configures the audience (aud claim)
    ->setId('4f1g23a12aa', true)    // Configures the id (jti claim), replicating as a header item
    ->setIssuedAt(time())           // Configures the time that the token was issue (iat claim)
    ->setNotBefore(time() + 60)     // Configures the time that the token can be used (nbf claim)
    ->setExpiration(time() + 3600)  // Configures the expiration time of the token (nbf claim)
    ->set('uid', 1)                 // Configures a new claim, called "uid"
    ->sign($signer,  $keychain->getPrivateKey('file://{path to your private key}')) // creates a signature using your private key
    ->getToken()                    // Retrieves the generated token
;


var_dump($token->verify($signer, $keychain->getPublicKey('file://{path to your public key}')); // true when the public key was generated by the private one =)

重要的是要说明，如果您使用 RSA 密钥，则不应调用 ECDSA 签名者（反之亦然），否则 sign() 和 verify() 将引发异常！