The LittleApps\LittleJWT\Validation\Validator
instance provides methods to specify checks to be performed on a JWT or token. This is the received by the callback sent to validateToken
and validateJWT
methods (as documented in the Validating page)
The following is a list of available rules:
Checks that the 'alg' claim is one of the specified algorithms.
Parameter | Type | Description |
---|---|---|
$algorithms |
array |
Algorithm keys to check for (HS256, RS256, etc.) |
$inHeader |
bool |
Checks the 'alg' claim in the header (if true ) or in the payload (if false ). (Default: true ) |
// Checks the 'alg' claim in the header is HS256.
$validator->algorithms(['HS256']);
// Checks the 'alg' claim in the payload is HS256.
$validator->algorithms(['HS256'], false);
Checks that the JWT is not blacklisted.
The Blacklist Manager page has more information on configuring the blacklist.
Parameter | Type | Description |
---|---|---|
$driver |
string null |
The blacklist driver to use. If null , the blacklist driver specified in the config file is used. (Default: null ) |
$before |
bool |
If true , this check is performed others. If false , this check is ran before or after other checks. (Default: true ) |
// Checks the JWT is not blacklisted and then checks that the 'abc' claim equals 'def'.
$validator
->allowed()
->equals('abc', 'def');
// Checks the JWT is not in the database blacklist either before or after checking the 'abc' claim equals 'def'.
$validator
->allowed('database', false)
->equals('abc', 'def');
Checks that claims with keys exist in header or payload.
Parameter | Type | Description |
---|---|---|
$keys |
array |
The claim keys to check if they exist in the header or payload. |
$strict |
bool |
If true , the JWT can only have the specified keys in the header or payload. (Default: false ) |
$inHeader |
bool |
If true , checks the claim keys exist in the header. If false , checks the payload. (default: false ) |
$before |
bool |
If true , this check is performed others. If false , this check is ran before or after other checks. (Default: true ) |
// Checks the JWT payload has the keys 'abc' and 'xyz'.
$validator->contains(['abc', 'xyz']);
// Checks the JWT payload ONLY has the keys 'abc' and 'xyz'.
$validator->contains(['abc', 'xyz'], true);
Allows a custom check to be done using a custom callback that receives a JWT instance and returns a boolean value. See The JWT for more information on the JWT.
Parameter | Type | Description |
---|---|---|
$callback |
callable |
Callback that receives the JWT as a parameter and returns true or false . |
use LittleApps\LittleJWT\JWT\JWT;
// Checks the JWT has at least 1 payload claim.
$validator->(function(JWT $jwt) {
return $jwt->getPayload()->count() >= 1;
});
Allows a custom claim check to be done using a custom callback that receives the claim value and returns a boolean value. The claim value is deserialized before being sent to the callback.
Parameter | Type | Description |
---|---|---|
$key |
string |
Claim key |
$callback |
callable |
Callback that receives the claim value, key, and JWT instance. |
$inHeader |
bool |
If true, checks claim in header. (default: false ) |
// Checks the 'abc' payload claim value is all uppercase
$validator->claimCallback('abc', function($value) {
return strtoupper($value) === $value;
});
Checks value of claim with key equals expected.
Parameter | Type | Description |
---|---|---|
$key |
string |
Claim key |
$expected |
mixed |
Expected value. |
$strict |
bool |
If true, performs type comparison. (default: true ) |
$inHeader |
bool |
If true, checks claim in header. (default: false ) |
// Checks the claim with key 'abc' equals 'def'
$validator->equals('abc', 'def');
// Checks the claim with key 'abc' equals 1, '1', or true.
$validator->equals('abc', 1, false);
Checks that the claim date/time is in the future.
Parameter | Type | Description |
---|---|---|
$key |
string |
Claim key |
$leeway |
int |
Leeway (in seconds) to allow after claims set date/time. (default: 0) |
$inHeader |
bool |
If true, checks claim in header. (default: false ) |
// Checks the date/time for the 'exp' payload claim is in the future.
$validator->future('exp');
// Checks the date/time for the 'exp' payload claim is in the future +/- 3600 seconds.
$validator->future('exp', 3600);
Checks value of claim is one of the expected values
Parameter | Type | Description |
---|---|---|
$key |
string |
Claim key |
$haystack |
array |
Expected values |
$strict |
bool |
If true, performs type comparison. (default: true ) |
$inHeader |
bool |
If true, checks claim in header. (default: false ) |
// Checks the 'abc' payload claim is 'cba' or 'def'
$validator->oneOf('abc', ['cba', 'def']);
// Checks the 'abc' payload claim is 1, '1', true, or 'cba'
$validator->oneOf('abc', [1, 'cba'], false);
Checks that the claim date/time is in the past.
Parameter | Type | Description |
---|---|---|
$key |
string |
Claim key |
$leeway |
int |
Leeway (in seconds) to allow before claims set date/time. (default: 0) |
$inHeader |
bool |
If true, checks claim in header. (default: false ) |
// Checks the date/time for the 'iat' payload claim is in the past.
$validator->past('iat');
// Checks the date/time for the 'iat' payload claim is in the past +/- 3600 seconds.
$validator->past('exp', 3600);
Securely checks value of claim with key equals expected. The comparison uses the hash_equals
function to prevent timing attacks .
Parameter | Type | Description |
---|---|---|
$key |
string |
Claim key |
$expected |
mixed |
Expected value. |
$inHeader |
bool |
If true, checks claim in header. (default: false ) |
// Securely checks the 'abc' payload claim equals 'def'.
$validator->secureEquals('abc', 'def');
Checks if the JWT has a valid signature using the default or a custom JSON Web Key (JWK). For more information on setting JWKs, see JSON Web Keys (JWKs).
Parameter | Type | Description |
---|---|---|
$jwk |
Jose\Component\Core\JWK null |
JWK instance to use. If null, the default JWK is used. (Default: null ) |
$before |
bool |
If true , this check is performed others. If false , this check is ran before or after other checks. (Default: true ) |
You can use the default JWK:
use LittleApps\LittleJWT\Facades\LittleJWT;
use LittleApps\LittleJWT\Validation\Validator;
$passes = LittleJWT::validateToken($token, function (Validator $validator) {
// Checks the JWT signature is valid using the default JWK before performing other checks.
$validator->valid();
});
You can use a different JWK:
use LittleApps\LittleJWT\Facades\LittleJWT;
use LittleApps\LittleJWT\Validation\Validator;
use Jose\Component\KeyManagement\JWKFactory;
$jwk = JWKFactory::createFromSecret(/* ... */);
// Checks the JWT signature is valid using the specified JWK before performing other checks.
$passes = LittleJWT::validateToken($token, function (Validator $validator) use ($jwk) {
$validator->valid($jwk);
});
// Checks the JWT signature is valid using the JWK associated with LittleJWT before performing other checks.
$passes = LittleJWT::withJwk($jwk)->validateToken($token, function (Validator $validator) {
$validator->valid();
});
Besides using a callback to define a custom rule, you can define a class.
To define a custom rule that checks entire JWT, create a class that extends the LittleApps\LittleJWT\JWT\Rules\Rule
abstract class:
use LittleApps\LittleJWT\JWT\Rules\Rule;
class MyRule extends Rule
{
/**
* Checks if JWT passes rule.
*
* @param \LittleApps\LittleJWT\JWT\JWT $jwt
* @return bool True if JWT passes rule check.
*/
public function passes(JWT $jwt)
{
// Check the $jwt here and return true or false.
}
/**
* Gets the error message for when the rule fails.
*
* @return string
*/
public function message()
{
return 'This is the error message to use if the rule does not pass.';
}
}
Add the rule to the Validator instance:
$validator->addRule(new MyRule);
To define a custom rule that checks a claim value, create a class that extends the LittleApps\LittleJWT\JWT\Rules\Claims\Rule
abstract class:
use LittleApps\LittleJWT\JWT\Rules\Claims\Rule;
class MyClaimRule extends Rule
{
/**
* Checks that a claim is valid, if it exists.
*
* @param JWT $jwt
* @param mixed $value
* @return bool
*/
protected function checkClaim(JWT $jwt, $value)
{
// Check the $value here and return true or false.
}
/**
* Formats a message for a claim check.
*
* @return string
*/
protected function formatMessage()
{
return "Claim with key ':key' is invalid.";
}
}
Add the rule to the Validator instance:
$validator->addRule(new MyClaimRule);
Similar to The Builder, method chaining can be done to specify multiple rules:
$validator
->valid() // Checks the signature is valid.
->equals('abc', 'def'); // Checks claim 'abc' in payload equals 'def'
The validation will not perform any further checks once one of the checks fails with stop on failure. This is enabled by default.
Parameter | Type | Description |
---|---|---|
$enabled |
bool |
If true, validation stops when first rule fails. (default: true ) |
This can be enabled or disabled with the stopOnFailure()
method:
// Enables stop on failure
$validator->stopOnFailure(true);
// Disables stop on failure
$validator->stopOnFailure(false);