Simple JWT implementation
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Noccy 5a4a2845e4 Update 'README.md'
Fixed code blocks
3 months ago
src Added support for validating token issuer and audience 2 years ago
tests More tests for JwtValidator 2 years ago
.gitignore Initial commit 2 years ago
README.md Update 'README.md' 3 months ago
composer.json Initial commit 2 years ago
phpunit.xml Initial commit 2 years ago

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

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
}