php-simple-jwt/README.md

104 lines
2.6 KiB
Markdown
Raw Normal View History

2023-04-09 00:40:21 +00:00
# SimpleJWT
2021-02-11 12:22:51 +00:00
This is a simple library for generating (signing) and verifying JWT tokens. It
is by no means an advanced library. If you just need to sign and refresh tokens
for users of your site or intranet, this will work great. If you need all the
glorious features of the JWT spec you should look elsewhere.
* Only handles HMAC-SHA256.
* Only handles expiry ('exp') natively
* Doesn't use any X.509 stuff.
## Use Cases
Use this to avoid having to rewrite the wheel when implementing authorization
internally within a system where OAuth may be overkill.
* Make good use of the expiry. JWTs aren't armored in any way, so make sure
they can't be used longer than they have to. (An hour is a good idea)
* Make sure you understand the security aspects of JWTs.
## Installation
Install using composer:
$ composer require noccylabs/simple-jwt:@dev
## Usage
2023-04-09 00:40:21 +00:00
You need a key for both generating and parsing tokens. Create a `JWTDerivedKey`
or a `JWTPlaintextKey` and pass it to the `JWTToken` constructor:
2021-02-11 12:22:51 +00:00
2023-04-09 00:46:48 +00:00
```php
use NoccyLabs\SimpleJWT\Key\{JWTDerivedKey,JWTPlaintextKey}
2021-02-11 12:22:51 +00:00
2023-04-09 00:46:48 +00:00
// Derive a key using secret and salt...
$key = new JWTDerivedKey("secret", "salt");
// ...or use a prepared plaintext key
$key = new JWTPlaintextKey("This Should Be Binary Data..");
```
2021-02-11 12:22:51 +00:00
2023-04-09 12:10:12 +00:00
`JWTDerivedKey` uses hash_pbkdf2.
2021-02-11 12:22:51 +00:00
### Generating tokens
2023-04-09 00:46:48 +00:00
```php
use NoccyLabs\SimpleJWT\JWTToken;
2021-02-11 12:22:51 +00:00
2023-04-09 00:46:48 +00:00
$tok = new JWTToken($key);
$tok->setExpiry("1h");
$tok->claims->add("some/claim/MaxItems", 8);
2021-02-11 12:22:51 +00:00
2022-12-29 01:18:13 +00:00
$str = $tok->getSignedToken();
```
2021-02-11 12:22:51 +00:00
### Parsing tokens
Parsing is done by passing the raw token as the 2nd parameter
2023-04-09 00:46:48 +00:00
```php
use NoccyLabs\SimpleJWT\JWTToken;
2021-02-11 12:22:51 +00:00
2022-12-29 01:18:13 +00:00
$str = "...received token...";
2021-02-11 12:22:51 +00:00
2023-04-09 00:46:48 +00:00
$tok = new JWTToken($key, $str);
2021-02-11 12:22:51 +00:00
2022-12-29 01:18:13 +00:00
if (!$tok->isValid()) {
// This check works, but using the validator might be better
}
2021-02-11 12:22:51 +00:00
2022-12-29 01:18:13 +00:00
// Using ->has() follwed by ->get() is one way
if ($tok->claims->has("some/claim/MaxItems")) {
// The claim exists, we can get the value (if any)
$val = $tok->claims->get("some/claim/MaxItems");
}
2021-02-11 12:22:51 +00:00
2022-12-29 01:18:13 +00:00
// You can also use valueOf() to return a default value if needed
$val = $tok->claims->valueOf("some/claim/MaxItems", 64);
```
2021-02-11 12:22:51 +00:00
### Validating tokens
2023-04-09 00:46:48 +00:00
```php
use NoccyLabs\SimpleJWT\Validator\JWTValidator;
$validator = new JWTValidator();
// Require that some claim exists
$validator
->requireIssuer("api.issuer.tld")
->requireAudience(["api.issuer.tld", "foo.issuer.tld"])
->addRequiredClaim("some/required/Claim");
try {
// Pass a JWTToken to validateToken()...
$valid = $validator->validateToken($tok);
// ...or pass a JWTKeyInterface and the raw string to validate()
$valid = $validator->validate($key, $tokenstr);
}
catch (JWTValidatorException $e) {
// validation failed
}
```