bizley / jwt
JWT integration for Yii 2
Fund package maintenance!
bizley
Installs: 221 126
Dependents: 2
Suggesters: 3
Security: 0
Stars: 67
Watchers: 2
Forks: 86
Open Issues: 0
Type:yii2-extension
Requires
- php: >=8.1
- lcobucci/jwt: ^5.0
- yiisoft/yii2: >=2.0.14 <2.1
Requires (Dev)
- infection/infection: *
- lcobucci/clock: ^3.0
- phpstan/phpstan: *
- phpunit/phpunit: ^10.5
- roave/security-advisories: dev-latest
README
JWT Integration For Yii 2
This extension provides the JWT integration for Yii 2 framework.
This is a fork of sizeg/yii2-jwt package
Available versions
See lcobucci/jwt repo for details about the version.
Installation
Add the package to your composer.json
:
{ "require": { "bizley/jwt": "^4.0" } }
and run composer update
or alternatively run composer require bizley/jwt:^4.0
Basic usage
Add jwt
component to your configuration file.
If your application is both the issuer and the consumer of JWT (the common case, a.k.a. Standard version)
use bizley\jwt\Jwt
component:
[ 'components' => [ 'jwt' => [ 'class' => \bizley\jwt\Jwt::class, 'signer' => ... // Signer ID, or signer object, or signer configuration, see "Available signers" below 'signingKey' => ... // Secret key string or path to the signing key file, see "Keys" below // ... any additional configuration here ], ], ],
If your application just needs some special JWT tools (like validator or parser, a.k.a. Toolset version)
use bizley\jwt\JwtTools
component:
[ 'components' => [ 'jwt' => [ 'class' => \bizley\jwt\JwtTools::class, // ... any additional configuration here ], ], ],
Of course, if you are already using the Standard version component, you don't need to define the Toolset version component, since the former already provides all the tools.
If you are struggling with the concept of API JWT, here is an EXAMPLE of how to quickly put all pieces together.
Available signers
Symmetric:
- HMAC (HS256, HS384, HS512)
Asymmetric:
- RSA (RS256, RS384, RS512)
- ECDSA (ES256, ES384, ES512)
- EdDSA (since 3.1.0)
- BLAKE2B (since 3.4.0)
Signer IDs are available as constants (like Jwt::HS256).
You can also provide your own signer, either as an instance of Lcobucci\JWT\Signer
or by adding its config to signers
and algorithmTypes
and using its ID for signer
.
As stated in
lcobucci/jwt
documentation: Although BLAKE2B is fantastic due to its performance, it's not JWT standard and won't necessarily be offered by other libraries.
Note on signers and minimum bits requirement
Since lcobucci/jwt 4.2.0
signers require the minimum key length to make sure those are properly secured, otherwise
the InvalidKeyProvided
is thrown.
Keys
For symmetric signers signingKey
is required. For asymmetric ones you also need to set verifyingKey
. Keys can be
provided as simple strings, configuration arrays, or instances of Lcobucci\JWT\Signer\Key
.
Configuration array can be as the following:
[ 'key' => /* key content */, 'passphrase' => /* key passphrase */, 'method' => /* method type */, ]
- key (
bizley\jwt\Jwt::KEY
) - string, default''
, start it with@
if it's Yii alias, - passphrase (
bizley\jwt\Jwt::PASSPHRASE
) - string, default''
, - method (
bizley\jwt\Jwt::METHOD
) - string, defaultbizley\jwt\Jwt::METHOD_PLAIN
, available:bizley\jwt\Jwt::METHOD_PLAIN
,bizley\jwt\Jwt::METHOD_BASE64
,bizley\jwt\Jwt::METHOD_FILE
(see https://lcobucci-jwt.readthedocs.io/en/latest/configuration/)
Simple string keys are shortcuts to the following array configs:
-
key starts with
@
orfile://
:[ 'key' => /* given key itself */, 'passphrase' => '', 'method' => \bizley\jwt\Jwt::METHOD_FILE, ]
Detecting
@
at the beginning assumes Yii alias has been provided, so it will be resolved withYii::getAlias()
. -
key doesn't start with
@
norfile://
:[ 'key' => /* given key itself */, 'passphrase' => '', 'method' => \bizley\jwt\Jwt::METHOD_PLAIN, ]
Issuing a token example:
Standard version:
$now = new \DateTimeImmutable(); /** @var \Lcobucci\JWT\Token\UnencryptedToken $token */ $token = Yii::$app->jwt->getBuilder() // Configures the issuer (iss claim) ->issuedBy('http://example.com') // Configures the audience (aud claim) ->permittedFor('http://example.org') // Configures the id (jti claim) ->identifiedBy('4f1g23a12aa') // Configures the time that the token was issued (iat claim) ->issuedAt($now) // Configures the time that the token can be used (nbf claim) ->canOnlyBeUsedAfter($now->modify('+1 minute')) // Configures the expiration time of the token (exp claim) ->expiresAt($now->modify('+1 hour')) // Configures a new claim, called "uid" ->withClaim('uid', 1) // Configures a new header, called "foo" ->withHeader('foo', 'bar') // Builds a new token ->getToken( Yii::$app->jwt->getConfiguration()->signer(), Yii::$app->jwt->getConfiguration()->signingKey() ); $tokenString = $token->toString();
The same in Toolset version:
$now = new \DateTimeImmutable(); /** @var \Lcobucci\JWT\Token\UnencryptedToken $token */ $token = Yii::$app->jwt->getBuilder() ->issuedBy('http://example.com') ->permittedFor('http://example.org') ->identifiedBy('4f1g23a12aa') ->issuedAt($now) ->canOnlyBeUsedAfter($now->modify('+1 minute')) ->expiresAt($now->modify('+1 hour')) ->withClaim('uid', 1) ->withHeader('foo', 'bar') ->getToken( Yii::$app->jwt->buildSigner(/* signer definition */), Yii::$app->jwt->buildKey(/* signing key definition */) ); $tokenString = $token->toString();
See https://lcobucci-jwt.readthedocs.io/en/latest/issuing-tokens/ for more info.
Parsing a token
/** @var non-empty-string $jwt */ /** @var \Lcobucci\JWT\Token $token */ $token = Yii::$app->jwt->parse($jwt);
See https://lcobucci-jwt.readthedocs.io/en/latest/parsing-tokens/ for more info.
Validating a token
You can validate a token or perform an assertion on it (see https://lcobucci-jwt.readthedocs.io/en/latest/validating-tokens/).
For validation use:
/** @var \Lcobucci\JWT\Token | non-empty-string $token */ /** @var bool $result */ $result = Yii::$app->jwt->validate($token);
For assertion use:
/** @var \Lcobucci\JWT\Token | string $token */ Yii::$app->jwt->assert($token);
You MUST provide at least one constraint, otherwise Lcobucci\JWT\Validation\NoConstraintsGiven
exception will be
thrown. There are several ways to provide constraints:
-
directly (Standard version only):
Yii::$app->jwt->getConfiguration()->setValidationConstraints(/* constaints here */);
-
through component configuration:
[ 'validationConstraints' => /* array of instances of Lcobucci\JWT\Validation\Constraint or array of configuration arrays that can be resolved as Constraint instances or anonymous function that can be resolved as array of Constraint instances with signature `function(\bizley\jwt\Jwt|\bizley\jwt\JwtTools $jwt)` where $jwt will be an instance of used component */, ]
Note: By default, this package is not adding any constraints out-of-the-box, you must configure them yourself like in the examples above.
Using component for REST authentication
Configure the authenticator
behavior in the controller.
class ExampleController extends Controller { public function behaviors() { $behaviors = parent::behaviors(); $behaviors['authenticator'] = [ 'class' => \bizley\jwt\JwtHttpBearerAuth::class, ]; return $behaviors; } }
There are special options available:
- jwt - string ID of component (default with
'jwt'
), component configuration array, or an instance ofbizley\jwt\Jwt
orbizley\jwt\JwtTools
, - auth - callable or
null
(default) - anonymous function with signaturefunction (\Lcobucci\JWT\Token $token)
that should return identity of user authenticated with the JWT payload information. If $auth is not provided methodyii\web\User::loginByAccessToken()
will be called instead. - throwException - bool (default
true
) - whether the filter should throw an exception i.e. if the token has an invalid format. If there are multiple auth filters (CompositeAuth) it can make sense to "silent fail" and pass the validation process to the next filter on the composite auth list.
For other configuration options refer to the Yii 2 Guide.
JWT Usage
Please refer to the lcobucci/jwt Documentation.