klsoft/yii3-jwt-auth

The package provides a Yii 3 authentication method based on a JWT token.

1.0.0 2026-02-09 05:37 UTC

Requires

• php: >=8.1
• firebase/php-jwt: ~7.0.2
• yiisoft/auth: ^3.0

MIT

• api
• Authentication
• jwt
• keycloak
• yii3

README

The package provides a Yii 3 authentication method based on a JWT token.

See also:

• YII3-KEYCLOAK-AUTHZ - The package provides Keycloak authorization for the web service APIs of Yii 3
• PHP-KEYCLOAK-CLIENT - A PHP library that can be used to secure web applications with Keycloak

Requirement

• PHP 8.1 or higher.

Installation

composer require klsoft/yii3-jwt-auth

How to use

1. Implement Klsoft\Yii3JwtAuth\JwksRepositoryInterface

Example:

namespace MyNamespace;

use Yiisoft\Cache\CacheInterface;
use Klsoft\Yii3JwtAuth\JwksRepositoryInterface;

final class JwksRepository implements JwksRepositoryInterface
{
    private const JWKS = 'jwks';

    public function __construct(
        private string         $jwksUrl,
        private int            $jwksCacheDuration,
        private CacheInterface $cache)
    {
    }

    public function getKeys(): ?array
    {
        $keys = $this->cache->getOrSet(
            JwksRepository::JWKS,
            function () {
                $options = [
                    'http' => [
                        'method' => 'GET'
                    ],
                ];
                $responseData = file_get_contents($this->jwksUrl, false, stream_context_create($options));
                if (!empty($responseData)) {
                    return json_decode($responseData, true);
                }
                return [];
            },
            $this->jwksCacheDuration);

        if (empty($keys)) {
            $this->cache->remove(JwksRepository::JWKS);
            return null;
        } else {
            return $keys;
        }
    }
}

2. Add the JWKS URL to param.php

Example:

return [
    'jwksUrl' => 'http://localhost:8080/realms/myrealm/protocol/openid-connect/certs',
    'jwksCacheDuration' => 60 * 3
];

3. Register dependencies

Example:

use Yiisoft\Auth\IdentityRepositoryInterface;
use Yiisoft\Auth\AuthenticationMethodInterface;
use Yiisoft\Cache\CacheInterface;
use Yiisoft\Cache\Cache;
use Yiisoft\Cache\ArrayCache;
use Klsoft\Yii3JwtAuth\JwksRepositoryInterface;
use Yiisoft\Definitions\Reference;

IdentityRepositoryInterface::class => IdentityRepository::class,
CacheInterface::class => [
        'class' => Cache::class,
        '__construct()' => [
            'handler' => new ArrayCache()
        ],
],
JwksRepositoryInterface::class => [
        'class' => JwksRepository::class,
        '__construct()' => [
            'jwksUrl' => $params['jwksUrl'],
            'jwksCacheDuration' => $params['jwksCacheDuration'],
            'cache' => Reference::to(CacheInterface::class)
        ]
],
AuthenticationMethodInterface::class => HttpJwtAuth::class

4. Add Authentication to the application middlewares.

Example:

use Yiisoft\Auth\Middleware\Authentication;

Application::class => [
        '__construct()' => [
            'dispatcher' => DynamicReference::to([
                'class' => MiddlewareDispatcher::class,
                'withMiddlewares()' => [
                    [
                        Authentication::class,
                        FormatDataResponseAsJson::class,
                        static fn() => new ContentNegotiator([
                            'application/xml' => new XmlDataResponseFormatter(),
                            'application/json' => new JsonDataResponseFormatter(),
                        ]),
                        ErrorCatcher::class,
                        static fn(ExceptionResponderFactory $factory) => $factory->create(),
                        RequestBodyParser::class,
                        Router::class,
                        NotFoundMiddleware::class,
                    ],
                ],
            ]),
        ],
    ]