Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The following pages will help you to migrate from spomky-labs/jose and spomky-labs/jose-bundle to that new framework.
The header checker manager is part of the checker component (web-token/jwt-checker
).
spomky-labs/jose
and this framework works a similar way thus migration is very easy. The main differences are:
There are two managers: one for the claims, one for the headers.
The manager needs at least one Token Support handler.
You will find JWS
and JWE
Token Supports in the web-token/jwt-signature
and web-token/jwt-encryption
components respectively.
Checkers must implement the Jose\Component\Checker\HeaderChecker
interface.
Before
After
Please note that the header crit
is always checked.
The JWS object, signature algorithms and token serializers are part of the signature component (web-token/jwt-signature
). Claim and header checkers are decoupled and can be found in the checker component (web-token/jwt-checker
).
Why are signature and checker components not together? The main reason is that when you issue signed tokens, you do not need any checker. Those components are decoupled to avoid the installation of unnecessary files.
The signature and loading processes have been completely reviewed.
In the examples below, we suppose we already have a JWK object ($key
).
Before
After
Before
After
Please note that it is important to check the token header before the verification of the signature. It will help you to reject tokens signed with unsupported algorithms.
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
After
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
.
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.
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.
These parameters can be injected a usual:
Associated service configuration:
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.
Before
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:
Create a request factory service
Configure the bundles:
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:
Configure a key set in the bundle configuration
The associated service will be jose.key_set.microsoft_keys
.
The JWE object, encryption algorithms and token serializers are part of the encryption component (web-token/jwt-encryption
). Claim and header checkers are decoupled and can be found in the checker component (web-token/jwt-checker
).
Why are encryption and checker components not together? The main reason is that when you issue encrypted tokens, you do not need any checker. Those components are decoupled to avoid the installation of unnecessary files.
The encryption and decryption processes have been completely reviewed.
In the examples below, we suppose we already have a JWK object ($key
).
Before
After
Before
After
Please note that it is important to check the token header before the decryption of the token. It will help you to reject tokens signed with unsupported algorithms or for other audiences.
The JWK object is part of the core component (web-token/jwt-core
). The may change concern the construction of the object. Its use is very similar.
Before
After
The claim checker manager is part of the checker component (web-token/jwt-checker
).
spomky-labs/jose
and this framework works a similar way thus migration is very easy. The main differences are:
There are two managers: one for the claims, one for the headers.
The manager only accepts an associative array. Conversion from a string to that array have to be done.
Checkers must implement the Jose\Component\Checker\ClaimChecker
interface.
Before
After