As JWK, the JWKSet object is also part of the core component (web-token/jwt-core). The constructor also changed in favor of a static method.
You can now create a key set using three ways:
Direct input of values (as before)
A list of JWK objects
A Json object string that represents a key set
Other important changes:
The JWKSet object does not implement \ArrayAccess anymore. However, you still can iterate it (e.g. using foreach).
The JWKSet is immutable. When you add a key, you will get a new object.
The method prependKey has been removed.
You can select a key using parameters (key type, algorithm, key ID...)
Before
<?php
use Jose\Object\JWKSet;
$keyset = new JWKSet(['keys' => [
'71ee230371d19630bc17fb90ccf20ae632ad8cf8' => [
'kid' => '71ee230371d19630bc17fb90ccf20ae632ad8cf8',
'kty' => 'RSA',
'alg' => 'RS256',
'use' => 'sig',
'n' => 'vnMTRCMvsS04M1yaKR112aB8RxOkWHFixZO68wCRlVLxK4ugckXVD_Ebcq-kms1T2XpoWntVfBuX40r2GvcD9UsTFt_MZlgd1xyGwGV6U_tfQUll5mKxCPjr60h83LXKJ_zmLXIqkV8tAoIg78a5VRWoms_0Bn09DKT3-RBWFjk=',
'e' => 'AQAB',
]]]);
json_encode($keyset); // The key as a Json object
$keyset->addKey(new JWK(['kty' => 'none'])); // Add a key
$keyset->removeKey(1); // Remove a key
$keyset->prependKey(new JWK(['kty' => 'none'])); // Prepend a key
$keyset[0]; // Access keys like arrays do
foreach ($keyset as $key) { // Iterate on a key set
...
}
After
<?php
use Jose\Component\Core\JWKSet;
// Create using direct values
$keyset = JWKSet::createFromKeyData(['keys' => [
'71ee230371d19630bc17fb90ccf20ae632ad8cf8' => [
'kid' => '71ee230371d19630bc17fb90ccf20ae632ad8cf8',
'kty' => 'RSA',
'alg' => 'RS256',
'use' => 'sig',
'n' => 'vnMTRCMvsS04M1yaKR112aB8RxOkWHFixZO68wCRlVLxK4ugckXVD_Ebcq-kms1T2XpoWntVfBuX40r2GvcD9UsTFt_MZlgd1xyGwGV6U_tfQUll5mKxCPjr60h83LXKJ_zmLXIqkV8tAoIg78a5VRWoms_0Bn09DKT3-RBWFjk=',
'e' => 'AQAB',
]]]);
// Create using a list of JWK objects
$keyset = JWKSet::createFromKeys([
JWK::create(['kty' => 'none']),
]);
// Create from a JWKSet as a Json object
$keyset = JWKSet::createFromJson('{"keys":{"71ee230371d19630bc17fb90ccf20ae632ad8cf8":{"kid":"71ee230371d19630bc17fb90ccf20ae632ad8cf8","kty":"RSA","alg":"RS256","use":"sig","n":"vnMTRCMvsS04M1yaKR112aB8RxOkW...9DKT3-RBWFjk=","e":"AQAB"}}}');
$keyset->has('71ee230371d19630bc17fb90ccf20ae632ad8cf8'); // Indicates if a key with a key ID (string) or index (integer) is in the key set.
$keyset->get('71ee230371d19630bc17fb90ccf20ae632ad8cf8'); // Retrieve a key with a key ID (string) or index (integer).
$keyset->count(); // Number of keys in the key set.
count($keyset); // Number of keys in the key set.
$keyset->all(); // An array of keys.
$newKeyset = $keyset->with(JWK::create(['kty' => 'none'])); // Adds a key in the key set. The returned key set is a new object (immutability).
$newKeyset = $keyset->without(0); // Removes a key from the key set. The returned key set is a new object (immutability).
$keyset->selectKey('sig', new RS256(), ['kid' => '71ee230371d19630bc17fb90ccf20ae632ad8cf8']);
About The Key Selector
The key selector is able to find a key that fits on several requirements:
First argument: key used either for signature (sig) or encryption (enc).
Second argument: algorithm you would like to use. If the key has no alg parameter but the key type allowed by the algorithm matches, then the key may be selected.
Third argument: an associated list of specific requirements. Can be any key parameter (e.g. kid or custom parameter).
The method returns the key that matches best otherwise null.
Removed Classes
The following classes have been removed.
Jose\Object\JWKSets
Jose\Object\PublicJWKSet
Jose\Object\StorableJWKSet
Jose\Object\RotatableJWKSet
Jose\Object\JKUJWKSet
Jose\Object\X5UJWKSet
There is no replacement classes. The key set modification, rotation or the loading of distant keys (JKU/X5U) should now be done
through the dedicated console/standalone application (see this page),
using the JWKFactory or JKUFactory,
using a custom key manager.
Keys/Key Sets And The Symfony Bundle
Env Var Processor
If you use Symfony 3.4+, you will be able to load a keys and key sets using an environment variable and process it:
It the environment variables are valid keys and key sets, the associated parameters will converted as a JWK or a JWKSet object.
$container->getParameter('private_key_set'); // Will return a JWKSet object
These parameters can be injected a usual:
<?php
declare(strict_types=1);
namespace AppBundle\Service;
use Jose\Component\Core\JWKSet;
final class Foo
{
public function __construct(JWKSet $jwkset)
{
...
}
}
Please note that, contrary to the keys and key sets loaded through the configuration or the Configuration Helper, the one loaded through an environment variable are not listed in the Symfony Debug Toolbar.
JKUFactory / X5UFactory
Before
<?php
use Jose\Factory\JWKFactory;
$jwkset = JWKFactory::createFromJKU('https://www.googleapis.com/oauth2/v3/certs');
After
The use of this feature is drastically different. JKUFactory and X5UFactory are now services that relies on HttPlug to get the key sets.
Make sure the following dependencies are installed:
(web-token/jwt-bundle and web-token/jwt-key-mgmt) or web-token/jwt-framework
php-http/httplug-bundle and at least one adapter (I will use php-http/guzzle6-adapter here)
Do not forget to enable the associated bundles:
new Http\HttplugBundle\HttplugBundle(),
new Jose\Bundle\JoseFramework\JoseFrameworkBundle(),
Create a request factory service
<?php
# app/AppBundle/Service/RequestFactory.php
namespace AppBundle\Service;
use GuzzleHttp\Psr7\Request;
use Http\Message\RequestFactory as Psr7RequestFactory;
final class RequestFactory implements Psr7RequestFactory
{
/**
* {@inheritdoc}
*/
public function createRequest($method, $uri, array $headers = [], $body = null, $protocolVersion = '1.1')
{
return new Request($method, $uri, $headers, $body, $protocolVersion);
}
}
services:
AppBundle\Service\RequestFactory: ~
Configure the bundles:
jose:
jku_factory:
enabled: true # We enable the JKU factory
client: 'httplug.client.my_client' # We indicate the Httplug client to use
request_factory: 'AppBundle\Service\RequestFactory' # See hereafter the corresponding class
httplug:
plugins:
cache: # We use the cache plugin
cache_pool: 'cache.app' # We use the PSR-6 Cache service of the application
config:
default_ttl: 1800 # TTL set to 30 min
clients:
my_client: # Our client based on Guzzle 6. The corresponding service will be `httplug.client.my_client`
factory: 'httplug.factory.guzzle6'
plugins: ['httplug.plugin.cache'] # We enable the cache plugin for that client
When done, there are two possibilities to load JKU/X5U key sets:
Inject the Jose\Component\KeyManagement\JKUFactory or Jose\Component\KeyManagement\X5UFactory and call the loadFromUrl method:
use Jose\Component\Core\JWKSet;
use Jose\Component\KeyManagement\JKUFactory;
class MyClass
{
private $jkuFactory;
public function __construct(JKUFactory $jkuFactory)
{
$this->client = $client;
$this->jkuFactory= $jkuFactory;
}
public function getKeySet(): JWKSet
{
return $this->jkuFactory->loadFromUrl($url);
}
}
