From ac4f2270cb2c284c6e4d52400a5b635fbdf23a4d Mon Sep 17 00:00:00 2001 From: tchap Date: Wed, 24 Nov 2021 09:53:39 +0100 Subject: [PATCH 1/2] Update mercure.rst regarding JWT token secret :wave: The documentation for the configuration of mercure seems quite wrong: it has a big "caution" block stating that the `MERCURE_JWT_SECRET` should contain an _actual JWT_ ... instead of a secret, which is weird (and definitely not how it works). I propose to remove these (maybe out of date?) parts to prevent further confusion (_I spent a full day examining the actual source to understand what was really needed in the env var_). Also, added a tip on how setting the cookies twice would not work. PS: I created this PR against the 5.3 (current) branch since the 4.4 branch does not have the same paragraphs. Hope it's good. --- mercure.rst | 41 +++++++++-------------------------------- 1 file changed, 9 insertions(+), 32 deletions(-) diff --git a/mercure.rst b/mercure.rst index 9a0c1e9dfea..5e351d69ca5 100644 --- a/mercure.rst +++ b/mercure.rst @@ -111,38 +111,7 @@ the publicly available URL (e.g. ``https://example.com/.well-known/mercure``). The clients must also bear a `JSON Web Token`_ (JWT) to the Mercure Hub to be authorized to publish updates and, sometimes, to subscribe. -This JWT should be stored in the ``MERCURE_JWT_SECRET`` environment variable. - -The JWT must be signed with the same secret key as the one used by -the Hub to verify the JWT (``!ChangeMe!`` in you use the Local Web Server or -Symfony Docker). -Its payload must contain at least the following structure to be allowed to -publish: - -.. code-block:: json - - { - "mercure": { - "publish": [] - } - } - -Because the array is empty, the Symfony app will only be authorized to publish -public updates (see the authorization_ section for further information). - -.. tip:: - - The jwt.io website is a convenient way to create and sign JWTs. - Checkout this `example JWT`_, that grants publishing rights for all *topics* - (notice the star in the array). - Don't forget to set your secret key properly in the bottom of the right panel of the form! - -.. caution:: - - Don't put the secret key in ``MERCURE_JWT_SECRET``, it will not work! - This environment variable must contain a JWT, signed with the secret key. - - Also, be sure to keep both the secret key and the JWTs... secrets! +This token must be signed with the same secret key as the one used by the Hub to verify the JWT (``!ChangeMe!`` in you use the Local Web Server or Symfony Docker), which should be stored in the ``MERCURE_JWT_SECRET`` environment variable. If you don't want to use the provided environment variables, use the following configuration: @@ -482,6 +451,14 @@ And here is the controller:: } } + +.. tip:: + + You cannot use the ``mercure()`` helper and the ``setCookie()`` + method at the same time (it would set the cookie twice on a single request). Choose + either one method or the other. + + Programmatically Generating The JWT Used to Publish --------------------------------------------------- From bd8475661a6f64e0cd121cdf1136b0b6164e1b66 Mon Sep 17 00:00:00 2001 From: tchap Date: Wed, 24 Nov 2021 10:47:51 +0100 Subject: [PATCH 2/2] Remove unneeded JWT reference --- mercure.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/mercure.rst b/mercure.rst index 5e351d69ca5..506d3b25134 100644 --- a/mercure.rst +++ b/mercure.rst @@ -711,7 +711,6 @@ Going further .. _`Symfony Docker`: https://github.com/dunglas/symfony-docker/ .. _`API Platform distribution`: https://api-platform.com/docs/distribution/ .. _`JSON Web Token`: https://tools.ietf.org/html/rfc7519 -.. _`example JWT`: https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjdXJlIjp7InB1Ymxpc2giOlsiKiJdfX0.iHLdpAEjX4BqCsHJEegxRmO-Y6sMxXwNATrQyRNt3GY .. _`IRI`: https://tools.ietf.org/html/rfc3987 .. _`practical UI`: https://twitter.com/ChromeDevTools/status/562324683194785792 .. _`the dedicated API Platform documentation`: https://api-platform.com/docs/core/mercure/