NOTE: Currently, only symmetric algorithms are supported
Phalcon\Security\JWT is a namespace that contains components that allow you to issue, parse and validate JSON Web Tokens as described in RFC 7915. These components are:
An example of using the component is:
English (US)
Czech
German
Greek
Persian
French
Indonesian
Italian
Korean
Japanese
Mongolian
Dutch
Polish
Portuguese, Brazilian
Russian
Serbian (Cyrillic)
Thai
Turkish
Ukrainian
Chinese Simplified<?php
use Phalcon\Security\JWT\Builder;
use Phalcon\Security\JWT\Signer\Hmac;
use Phalcon\Security\JWT\Token\Parser;
use Phalcon\Security\JWT\Validator;
// Defaults to 'sha512'
$signer = new Hmac();
// Builder object
$builder = new Builder($signer);
$now = new DateTimeImmutable();
$issued = $now->getTimestamp();
$notBefore = $now->modify('-1 minute')->getTimestamp();
$expires = $now->modify('+1 day')->getTimestamp();
$passphrase = 'QcMpZ&b&mo3TPsPk668J6QH8JA$&U&m2';
// Setup
$builder
->setAudience('https://target.phalcon.io') // aud
->setContentType('application/json') // cty - header
->setExpirationTime($expires) // exp
->setId('abcd123456789') // JTI id
->setIssuedAt($issued) // iat
->setIssuer('https://phalcon.io') // iss
->setNotBefore($notBefore) // nbf
->setSubject('my subject for this claim') // sub
->setPassphrase($passphrase) // password
;
// Phalcon\Security\JWT\Token\Token object
$tokenObject = $builder->getToken();
// The token
echo $tokenObject->getToken();
// Token split into different lines for readability
//
// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiIsImN0eSI6ImFwcGxpY2F0aW9uXC9qc29uIn0.
// eyJhdWQiOlsiaHR0cHM6XC9cL3RhcmdldC5waGFsY29uLmlvIl0sImV4cCI6MTYxNDE4NTkxN
// ywianRpIjoiYWJjZDEyMzQ1Njc4OSIsImlhdCI6MTYxNDA5OTUxNywiaXNzIjoiaHR0cHM6XC
// 9cL3BoYWxjb24uaW8iLCJuYmYiOjE2MTQwOTk0NTcsInN1YiI6Im15IHN1YmplY3QgZm9yIHR
// oaXMgY2xhaW0ifQ.
// LdYevRZaQDZ2lul4CCQ5DymeP2ubcapTtgeezOZGIq7Meu7rFF1pv32b-AMWOxCS63CQz_jpm
// BPlPyOeEAkMbg
// $tokenReceived is what we received
$tokenReceived = getMyTokenFromTheApplication();
$audience = 'https://target.phalcon.io';
$now = new DateTimeImmutable();
$issued = $now->getTimestamp();
$notBefore = $now->modify('-1 minute')->getTimestamp();
$expires = $now->getTimestamp();
$id = 'abcd123456789';
$issuer = 'https://phalcon.io';
// Defaults to 'sha512'
$signer = new Hmac();
$passphrase = 'QcMpZ&b&mo3TPsPk668J6QH8JA$&U&m2';
// Parse the token
$parser = new Parser();
// Phalcon\Security\JWT\Token\Token object
$tokenObject = $parser->parse($tokenReceived);
// Phalcon\Security\JWT\Validator object
$validator = new Validator($tokenObject, 100); // allow for a time shift of 100
// Throw exceptions if those do not validate
$validator
->validateAudience($audience)
->validateExpiration($expires)
->validateId($id)
->validateIssuedAt($issued)
->validateIssuer($issuer)
->validateNotBefore($notBefore)
->validateSignature($signer, $passphrase)
;
The above example gives a general view on how the component can be used to generate, parse and validate JSON Web Tokens.
There are several utility components that live in the Phalcon\Security\JWT\Token namespace, that help with the issuing, parsing and validating JWT tokens
Phalcon\Security\JWT\Token\Enum is a class that contains several constants. These constants are the strings defined in RFC 7915. You can use them if you wish or instead use their string equivalents.
<?php
class Enum
{
/**
* Headers
*/
const TYPE = "typ";
const ALGO = "alg";
const CONTENT_TYPE = "cty";
/**
* Claims
*/
const AUDIENCE = "aud";
const EXPIRATION_TIME = "exp";
const ID = "jti";
const ISSUED_AT = "iat";
const ISSUER = "iss";
const NOT_BEFORE = "nbf";
const SUBJECT = "sub";
}
Phalcon\Security\JWT\Token\Item is used internally to store a payload as well as its encoded state. Such payload can be the claims data or the headers data. By using this component, we can easily extract the necessary information for each Token.
Phalcon\Security\JWT\Token\Signature is similar to the Phalcon\Security\JWT\Token\Item, but it only holds teh signature hash as well as its encoded value.
Phalcon\Security\JWT\Token\Token is the component responsible for storing and calculating the JWT token. It accepts the headers, claims (as Phalcon\Security\JWT\Token\Item objects) and signature objects in its constructor and exposes:
getPayload: Returns the payloadgetToken: Returns the tokenFor a token abcd.efgh.ijkl, getPayload will return abcd.efgh and getToken will return abcd.efgh.ijkl.
In order to create a JWT token, we need to supply a Signing algorithm. By default, the builder uses “none” (Phalcon\Security\JWT\Signer\None). You can however use the HMAC signer (Phalcon\Security\JWT\Signer\Hmac). Also, for further customization, you can utilize the supplied Phalcon\Security\JWT\Signer\SignerInterface interface.
<?php
use Phalcon\Security\JWT\Signer\Hmac;
$signer = new Hmac();
None
This signer is provided mostly for development purposes. You should always sign your JWT tokens.
HMAC
The HMAC signer supports the sha512, sha384, and sha256 algorithms. If none is supplied, the sha512 is automatically selected. If you supply a different algorithm, a Phalcon\Security\JWT\Exceptions\UnsupportedAlgorithmException will be raised. The algorithm is set in the constructor.
<?php
use Phalcon\Security\JWT\Signer\Hmac;
$signer = new Hmac();
$signer = new Hmac('sha512');
$signer = new Hmac('sha384');
$signer = new Hmac('sha256');
$signer = new Hmac('sha111'); // exception
The component utilizes the [hmac_equals][hmac_equals] and [hash_hmac][hash_hmac] PHP methods internally to verify and sign the payload. It exposes the following methods:
public function getAlgHeader(): string
Returns a string identifying the algorithm. For the HMAC algoritms it will return:
| Algorithm | getAlgHeader |
|---|---|
sha512 |
HS512 |
sha384 |
HS384 |
sha256 |
HS256 |
public function sign(string $payload, string $passphrase): string
Returns the hash of the payload using the passphrase
public function verify(string $source, string $payload, string $passphrase): bool
Verifies that the hashed source string is the same as the hash of the payload with the passphrase.
A Builder component (Phalcon\Security\JWT\Builder) is available, utilizing chained methods, and ready to be used to create JWT tokens. All you have to do is instantiate the Builder object, configure your token and call getToken(). This will return a Phalcon\Security\Token\Token object which contains all the necessary information for your token. When instantiating the builder component, you have to supply the signer class. In the example below we use the Phalcon\Security\JWT\Signer\Hmac signer.
All setters in this component are chainable.
<?php
use Phalcon\Security\JWT\Builder;
use Phalcon\Security\JWT\Signer\Hmac;
// Defaults to 'sha512'
$signer = new Hmac();
// Builder object
$builder = new Builder($signer);
public function __construct(SignerInterface $signer): Builder
Constructor
public function init(): Builder
Initializes the object - useful when you want to reuse the same builder
public function getAudience()
Returns the aud contents
public function getClaims(): array
Returns the claims as an array
public function getContentType(): ?string
Returns the content type (cty - headers)
public function getExpirationTime(): ?int
Returns the exp contents
public function getHeaders(): array
Returns the headers as an array
public function getId(): ?string
Returns the jti contents (ID of this JWT)
public function getIssuedAt(): ?int
Returns the iat contents
public function getIssuer(): ?string
Returns the iss contents
public function getNotBefore(): ?int
Returns the nbf contents
public function getSubject(): ?string
Returns the sub contents
public function getToken(): Token
Returns the token
public function getPassphrase(): string
Returns the supplied passphrase
public function setAudience($audience): Builder
Sets the audience (aud). If the parameter passed is not an array or a string, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function setContentType(string $contentType): Builder
Sets the content type (cty - headers)
public function setExpirationTime(int $timestamp): Builder
Sets the audience (exp). If the $timestamp is less than the current time, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function setId(string $id): Builder
Sets the id (jti).
public function setIssuedAt(int $timestamp): Builder
Sets the issued at time (iat).
public function setIssuer(string $issuer): Builder
Sets the issuer (iss).
public function setNotBefore(int $timestamp): Builder
Sets the audience (nbf). If the $timestamp is greater than the current time, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function setSubject(string $subject): Builder
Sets the subject (sub).
public function setPassphrase(string $passphrase): Builder
Sets the passphrase. If the $passphrase is weak, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
private function setClaim(string $name, $value): Builder
Sets a claim value in the internal collection.
<?php
use Phalcon\Security\JWT\Builder;
use Phalcon\Security\JWT\Signer\Hmac;
use Phalcon\Security\JWT\Token\Parser;
use Phalcon\Security\JWT\Validator;
// Defaults to 'sha512'
$signer = new Hmac();
// Builder object
$builder = new Builder($signer);
$now = new DateTimeImmutable();
$issued = $now->getTimestamp();
$notBefore = $now->modify('-1 minute')->getTimestamp();
$expires = $now->modify('+1 day')->getTimestamp();
$passphrase = 'QcMpZ&b&mo3TPsPk668J6QH8JA$&U&m2';
// Setup
$builder
->setAudience('https://target.phalcon.io') // aud
->setContentType('application/json') // cty - header
->setExpirationTime($expires) // exp
->setId('abcd123456789') // JTI id
->setIssuedAt($issued) // iat
->setIssuer('https://phalcon.io') // iss
->setNotBefore($notBefore) // nbf
->setSubject('my subject for this claim') // sub
->setPassphrase($passphrase) // password
;
// Phalcon\Security\JWT\Token\Token object
$tokenObject = $builder->getToken();
// The token
echo $tokenObject->getToken();
// Token split into different lines for readability
//
// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiIsImN0eSI6ImFwcGxpY2F0aW9uXC9qc29uIn0.
// eyJhdWQiOlsiaHR0cHM6XC9cL3RhcmdldC5waGFsY29uLmlvIl0sImV4cCI6MTYxNDE4NTkxN
// ywianRpIjoiYWJjZDEyMzQ1Njc4OSIsImlhdCI6MTYxNDA5OTUxNywiaXNzIjoiaHR0cHM6XC
// 9cL3BoYWxjb24uaW8iLCJuYmYiOjE2MTQwOTk0NTcsInN1YiI6Im15IHN1YmplY3QgZm9yIHR
// oaXMgY2xhaW0ifQ.
// LdYevRZaQDZ2lul4CCQ5DymeP2ubcapTtgeezOZGIq7Meu7rFF1pv32b-AMWOxCS63CQz_jpm
// BPlPyOeEAkMbg
In order to validate a token you will need to create a new Phalcon\Security\JWT\Validator object. The object can be constructed using a Phalcon\Security\JWT\Token\Token object and an offset in time to handle time/clock shifts of the sending and receiving computers.
In order to parse the JWT received and convert it to a Phalcon\Security\JWT\Token\Token object, you will need to use a Phalcon\Security\JWT\Token\Parser object and parse it.
// Parser
$parser = new Parser();
// Parse the token received
$tokenObject = $parser->parse($tokenReceived);
// Create the validator
$validator = new Validator($tokenObject, 100); // allow for a time shift of 100
After that, you can start calling the validate* methods with the necessary parameters to validate the token received. If no exceptions are thrown, the token is valid.
public function __construct(Token $token, int $timeShift = 0)
Constructor
public function setToken(Token $token): Validator
Sets the token object.
public function validateAudience(string $audience): Validator
Validates the audience. If it is not included in the token’s aud, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function validateExpiration(int $timestamp): Validator
Validates the expiration time. If the exp value stored in the token is less than now, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function validateId(string $id): Validator
Validates the id. If it is not the same as the jti value stored in the token, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function validateIssuedAt(int $timestamp): Validator
Validates the issued at time. If the iat value stored in the token is greater than now, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function validateIssuer(string $issuer): Validator
Validates the issuer. If it is not the same as the iss value stored in the token, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function validateNotBefore(int $timestamp): Validator
Validates the not before time. If the nbf value stored in the token is greater than now, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
public function validateSignature(SignerInterface $signer, string $passphrase): Validator
Validates the signature of the token. If the signature is not valid, a Phalcon\Security\JWT\Exceptions\ValidatorException will be thrown.
<?php
use Phalcon\Security\JWT\Signer\Hmac;
use Phalcon\Security\JWT\Token\Parser;
use Phalcon\Security\JWT\Validator;
// Token split into different lines for readability
//
// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiIsImN0eSI6ImFwcGxpY2F0aW9uXC9qc29uIn0.
// eyJhdWQiOlsiaHR0cHM6XC9cL3RhcmdldC5waGFsY29uLmlvIl0sImV4cCI6MTYxNDE4NTkxN
// ywianRpIjoiYWJjZDEyMzQ1Njc4OSIsImlhdCI6MTYxNDA5OTUxNywiaXNzIjoiaHR0cHM6XC
// 9cL3BoYWxjb24uaW8iLCJuYmYiOjE2MTQwOTk0NTcsInN1YiI6Im15IHN1YmplY3QgZm9yIHR
// oaXMgY2xhaW0ifQ.
// LdYevRZaQDZ2lul4CCQ5DymeP2ubcapTtgeezOZGIq7Meu7rFF1pv32b-AMWOxCS63CQz_jpm
// BPlPyOeEAkMbg
// $tokenReceived is what we received
$tokenReceived = getMyTokenFromTheApplication();
$audience = 'https://target.phalcon.io';
$now = new DateTimeImmutable();
$issued = $now->getTimestamp();
$notBefore = $now->modify('-1 minute')->getTimestamp();
$expires = $now->getTimestamp();
$id = 'abcd123456789';
$issuer = 'https://phalcon.io';
// Defaults to 'sha512'
$signer = new Hmac();
$passphrase = 'QcMpZ&b&mo3TPsPk668J6QH8JA$&U&m2';
// Parse the token
$parser = new Parser();
// Phalcon\Security\JWT\Token\Token object
$tokenObject = $parser->parse($tokenReceived);
// Phalcon\Security\JWT\Validator object
$validator = new Validator($tokenObject, 100); // allow for a time shift of 100
// Throw exceptions if those do not validate
$validator
->validateAudience($audience)
->validateExpiration($expires)
->validateId($id)
->validateIssuedAt($issued)
->validateIssuer($issuer)
->validateNotBefore($notBefore)
->validateSignature($signer, $passphrase)
;
Any exceptions thrown in the Security component will be of the namespace Phalcon\Security\JWT\*. Puede usar esta excepción para capturar selectivamente sólo las excepciones lanzadas desde este componente. There are two exceptions raised. First if you supply the wrong algoritm string when instantiating the Phalcon\Security\JWT\Signer\Hmac component. This exception is Phalcon\Security\JWT\Exceptions\UnsupportedAlgorithmException.
The second exception is thrown when validating a JWT. This exception is Phalcon\Security\JWT\Exceptions\ValidatorException.
<?php
use Phalcon\Mvc\Controller;
use Phalcon\Security\JWT\Builder;
use Phalcon\Security\JWT\Exceptions\ValidatorException;
use Phalcon\Security\JWT\Signer\Hmac;
use Phalcon\Security\JWT\Validator;
class IndexController extends Controller
{
public function index()
{
try {
$signer = new Hmac();
$builder = new Builder($signer);
$expiry = strtotime('+1 day');
$issued = strtotime('now') + 100;
$notBefore = strtotime('-1 day');
$passphrase = '&vsJBETaizP3A3VX&TPMJUqi48fJEgN7';
return $builder
->setAudience('my-audience')
->setExpirationTime($expiry)
->setIssuer('Phalcon JWT')
->setIssuedAt($issued)
->setId('PH-JWT')
->setNotBefore($notBefore)
->setSubject('Mary had a little lamb')
->setPassphrase($passphrase)
->getToken()
;
$validator = new Validator($token);
$validator->validateAudience("unknown");
} catch (Exception $ex) {
echo $ex->getMessage(); // Validation: audience not allowed
}
}
}