Skip to content

Commit

Permalink
Forgot the other half
Browse files Browse the repository at this point in the history
  • Loading branch information
Jir4 committed Jul 22, 2024
1 parent dcbe26a commit 20ee074
Showing 1 changed file with 0 additions and 60 deletions.
60 changes: 0 additions & 60 deletions Resources/doc/10-web-token.rst
Original file line number Diff line number Diff line change
Expand Up @@ -140,66 +140,6 @@ you certainly want to rotate your keys on a regular basis.
Key rotation is a good practice preventing attackers guessing your keys and forging
tokens with elevated rights.

To ease the key manipulations, you should consider installing `JWT App <https://github.com/web-token/jwt-app>`__.
You just have to download the last stable release from `the releases page <https://github.com/web-token/jwt-app/releases>`__
and set the PHAR file as executable.

.. code-block:: sh
chmod +x jose.phar
In the following example, we will consider:
\* The signature private key is stored in the ``config/jwt/signature.jwk`` file,
\* The signature public keyset is stored in the ``config/jwt/signature.jwkset`` file.

The objective is to rotate the keyset by adding a new key and removing the oldest one.
The new private key will be stored in the ``config/jwt/signature.jwk`` file,
and the new public keyset will be updated.

Signature Private Key
---------------------

The new signature private key shall be compatible with the algorithm declared in the configuration.
For example, if you use the ``RS256`` algorithm, you must generate a RSA private key.
Hereafter few examples of RSA (``RS***``/``PS***``), OCT (``HS***``), EC (``ES***``) adn OKP (``ED***``) and private key generations:

.. code-block:: sh
./jose.phar key:generate:rsa --random_id --use=sig --alg=RS256 --size 4096 > config/jwt/signature.jwk
./jose.phar key:generate:oct --random_id --use=sig --alg=HS256 256 > config/jwt/signature.jwk
./jose.phar key:generate:ec --random_id --use=sig --alg=ES256 P-256 > config/jwt/signature.jwk
./jose.phar key:generate:okp --random_id --use=sig --alg=ED256 Ed25519 > config/jwt/signature.jwk
Signature Public Keyset
-----------------------

Now that you have a new private key, you can rotate the public keyset.
The rotation is done by adding the new key at beginiing of the keyset and removing the oldest (last) one.

.. code-block:: sh
./jose.phar keyset:rotate `cat config/jwt/signature.jwkset` `cat config/jwt/signature.jwk` > config/jwt/signature.jwkset
Encryption Key and Keyset
-------------------------

Encryption keys are managed in the same way as signature keys.
The differences are as follows:
\* You must use different files for the private and public keys (e.g. ``encryption.jwk`` and ``encryption.jwkset``),
\* You must use the ``enc`` key usage,
\* You must use the correct algorithm for the key type (RSA, OCT, EC, OKP).
.. code-block:: sh
bin/console lexik:jwt:enable-encryption
Key Rotation
============

Among all the features offered by the Web-Token library,
you certainly want to rotate your keys on a regular basis.
Key rotation is a good practice preventing attackers guessing your keys and forging
tokens with elevated rights.

To ease the key manipulations, you should consider installing `JWT App <https://github.com/web-token/jwt-app>`_.
You just have to download the last stable release from `the releases page <https://github.com/web-token/jwt-app/releases>`_
and set the PHAR file as executable.
Expand Down

0 comments on commit 20ee074

Please sign in to comment.