Simple JWT implementation
Go to file
Chris f83998e6c7 Additional checks for validity and in validator
* Properly check nbf and exp claims in token to determine simple
  validity.
* Properly check nbf and exp claims in validator and throw exceptions
  if expired/not yet valid.
2024-03-11 23:34:19 +01:00
src Additional checks for validity and in validator 2024-03-11 23:34:19 +01:00
tests Fixed case in test filenames 2023-04-10 00:55:15 +02:00
.gitignore Initial commit 2021-02-11 13:22:51 +01:00
.woodpecker.yml Added woodpecker config 2023-04-21 01:46:52 +02:00
CHANGELOG.md Added woodpecker config 2023-04-21 01:46:52 +02:00
README.md phpstan fixes 2023-04-09 14:12:48 +02:00
composer.json Fixed capitalization, tests 2023-04-09 02:40:21 +02:00
phpstan.neon Fixed capitalization, tests 2023-04-09 02:40:21 +02:00
phpunit.xml Fixed capitalization, tests 2023-04-09 02:40:21 +02:00

README.md

SimpleJWT

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

You need a key for both generating and parsing tokens. Create a JWTDerivedKey or a JWTPlaintextKey and pass it to the JWTToken constructor:

use NoccyLabs\SimpleJWT\Key\{JWTDerivedKey,JWTPlaintextKey}

// 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.."); 

JWTDerivedKey uses hash_pbkdf2.

Generating tokens

use NoccyLabs\SimpleJWT\JWTToken;

$tok = new JWTToken($key);
$tok->setExpiry("1h");
$tok->claims->add("some/claim/MaxItems", 8);

$str = $tok->getSignedToken();

Parsing tokens

Parsing is done by passing the raw token as the 2nd parameter

use NoccyLabs\SimpleJWT\JWTToken;

$str = "...received token...";

$tok = new JWTToken($key, $str);

if (!$tok->isValid()) {
    // This check works, but using the validator might be better
}

// 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");
}

// You can also use valueOf() to return a default value if needed
$val = $tok->claims->valueOf("some/claim/MaxItems", 64);

Validating tokens

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
}