From dca7f915b011d427046e5d3c5b0ec44309736abe Mon Sep 17 00:00:00 2001 From: Yohann Dupont Date: Mon, 22 Jul 2024 17:07:38 +0200 Subject: [PATCH] Convert md title in rst format --- Resources/doc/10-web-token.rst | 48 ++++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 20 deletions(-) diff --git a/Resources/doc/10-web-token.rst b/Resources/doc/10-web-token.rst index 862f6dbd..58ee6ba4 100644 --- a/Resources/doc/10-web-token.rst +++ b/Resources/doc/10-web-token.rst @@ -8,8 +8,8 @@ use of encrypted tokens and key rotations. This feature is only available with PHP 8.1+ and Symfony 6.1+. - -# Dependency Installation: +Dependency Installation: +======================== To enable this feature, you must install the following dependencies: @@ -17,7 +17,8 @@ To enable this feature, you must install the following dependencies: composer require web-token/jwt-bundle -## About Algorithms +About Algorithms +---------------- There are two type of signature algorithms: symmetric and asymmetric. @@ -29,9 +30,11 @@ Asymmetric algorithms are slower, but because keys are asymmetric you can allow for validating the tokens without allowing them to forge new ones. This is commonly used when tokens are meant to be processed by third parties. -# Migrating Configuration +Migrating Configuration +======================= -## Automatic Migration +Automatic Migration +------------------- A migration command is available when working with the debug mode enabled (dev environment). @@ -47,11 +50,13 @@ After running the migration tool, your signature keyset will contain the key is but formatted as a JWK (Json Wek Key). In addition, two random keys are added. These keys are not used and will be dropped when rotating the keyset. -## Manual Migration +Manual Migration +---------------- If you want to migrate your configuration manually, you can follow the next steps. -### Signature Key and Keyset +Signature Key and Keyset +~~~~~~~~~~~~~~~~~~~~~~~~ The signature private key and the signature public keyset are mandatory for using the Web-Token library. You can generate them using the following commands. Please use the one that corresponds to your algorithm. @@ -74,7 +79,8 @@ You can generate them using the following commands. Please use the one that corr # Then, we rotate the keyset to add signautre private key to the keyset. ./jose.phar keyset:rotate `cat config/jwt/signature.jwkset` `cat config/jwt/signature.jwk` > config/jwt/signature.jwkset -### Bundle Configuration +Bundle Configuration +~~~~~~~~~~~~~~~~~~~~ The bundle configuration is very similar to the one used by the previous version of the bundle. You just have to replace the ``lexik_jwt_authentication.encoder.***`` encoder by the ``lexik_jwt_authentication.encoder.web_token`` encoder. @@ -96,7 +102,6 @@ Then, you have to set the access token issuance and verification parameters. allowed_algorithms: ['RS256'] keyset: 'env(file:SIGNATURE_KEYSET)' - In the example, we use the environment variables to retrieve the signature key and keyset. .. code-block:: yaml @@ -110,8 +115,8 @@ In the example, we use the environment variables to retrieve the signature key a We recommend using the environment variables to store the signature key and keyset instead of files. - -# Encryption Support +Encryption Support +================== With WebTokenBundle, you can encrypt your tokens. The tokens will only be readable by the applications that have the private key to decrypt them. @@ -127,16 +132,16 @@ The output will be the updated configuration for the bundle. bin/console lexik:jwt:enable-encryption - -# Key Rotation +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) +To ease the key manipulations, you should consider installing `JWT App `_. +You just have to download the last stable release from `the releases page `_ and set the PHAR file as executable. .. code-block:: sh @@ -151,7 +156,8 @@ The objective is to rotate the keyset by adding a new key and removing the oldes 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 +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. @@ -164,7 +170,8 @@ Hereafter few examples of RSA (``RS***``/``PS***``), OCT (``HS***``), EC (``ES** ./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 +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. @@ -173,10 +180,11 @@ The rotation is done by adding the new key at beginiing of the keyset and removi ./jose.phar keyset:rotate `cat config/jwt/signature.jwkset` `cat config/jwt/signature.jwk` > config/jwt/signature.jwkset -## Encryption Key and Keyset +Encryption Key and Keyset +------------------------- Encryption keys are managed in the same way as signature keys. -The differences are as follows: +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). +* You must use the correct algorithm for the key type (RSA, OCT, EC, OKP). \ No newline at end of file