Merge pull request #1023 from akeneo/DXIM-1-JWT-in-uiext-iframe

DXIM-1 Add iframe secret management to doc

Author: JulienVerbrugge

content/extensions/ui-extensions.md

@@ -193,13 +193,87 @@ An iframe (inline frame) is an HTML element that allows you to embed another HTM
 
 For more detailed information, you can refer to the [Mozilla Developer Network (MDN) documentation on iframes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
 
-To ensure the secure embedding of iframes, it is essential to properly configure [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to control the sources from which content can be loaded.
+To configure an `iframe` UI extension, mandatory fields are `name`, `position`, `type`, and `configuration`. Inside `configuration`, mandatory options are `default_label`, `secret` and `url`.
+
+**Ensuring security of embedded iframes**
+
+* Properly configure [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) headers to control the sources from which content can be loaded.
 
 ::: warning
  Please note that if these headers are misconfigured, iframe functionality may not work as intended.
 :::
 
-To configure an `iframe` UI extension, mandatory fields are `name`, `position`, `type`, and `configuration`. Inside `configuration`, mandatory options are `default_label` and `url`.
+* Add a secret to your extension. This secret will be used to generate a JWT token when the iframe is loaded by the PIM system.
+
+**Receiving the JWT Token via ```postMessage```**
+
+First, from your iframe, you must request for the JWT by doing a PostMessage with a payload containing ```type: 'request_jwt'```
+
+Example :
+```js
+    window.parent.postMessage(
+      {
+        type: 'request_jwt'
+      },
+      "*"
+    );
+```
+
+ the PIM will then answer with a postMessage containing the JWT token. The message will be structured as follows:
+
+```json
+{
+  "type": "JWT_TOKEN",
+  "token": "jwt_value"
+}
+```
+
+* The JWT token in the token field is generated using SHA256 encryption based on the secret you provided.
+
+For more information on how JWT tokens are structured and used, you can refer to the associated [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519).
+
+**JWT Token Structure**
+
+The JWT token consists of three main parts: the header, the body (payload), and the signature.
+
+*Header*
+
+* The header typically contains information about the token type and the signing algorithm. In this case, it will look like:
+
+```json
+{
+  "typ": "JWT",
+  "alg": "HS256"
+}
+```
+
+*Payload*
+
+* The payload contains the claims. The JWT token’s will look like this:
+
+```json
+{
+  "jti": "c1b6b9f1-8486-4f9e-9f96-8d1b40fccb65",
+  "iat": 1743410036.116152,
+  "exp": 1743413636.116162,
+  "userId": "1"
+}
+```
+
+* ```jti``` The unique identifier for the token.
+* ```iat``` The issued at time.
+* ```exp``` The expiration time of the token.
+* ```userId``` The PIM user identifier (in this case, ```1```).
+
+*A signature*
+
+* The signature is used to verify that the token is valid and has not been tampered with. It is generated by combining the encoded header and payload, and then signing them with the secret key. The resulting signature might look like:  
+```9WBB7ayP8UnFrOlMrI9NzTj3kxaiXOWJzElyacEKt48```
+
+**Verifying the Signature**
+
+To ensure that the JWT token was issued by Akeneo, you can verify the signature by re-encoding the header and payload and then signing them using the same secret key. This will allow you to confirm that the token is valid and has not been altered.
+
 
 **PostMessage**
 
@@ -272,7 +346,7 @@ An **action** UI extension is designed to perform external tasks in the backgrou
 + **Notification on completion**: A notification will appear once the external server responds to the request, keeping users informed of the task's status.
 + **Timeout**: The PIM HTTP client that communicates with the destination is configured with a timeout of 5 seconds.
 + **POST HTTP method**: The request being sent to the destination is a POST request.
-+ **Signature**: It's possible to configure a [secret](#secret) to sign each request sent to the destination.
++ **Signature**: It's possible to configure a `secret` to sign the body of the POST request sent to the destination (<a href='https://wikipedia.org/wiki/SHA-2'>SHA-512</a> protocol).
 
 Here is a diagram illustrating the workflow:
 [![action-extension-schema.png](../img/extensions/ui-extensions/action-extension-schema.png)](../img/extensions/ui-extensions/action-extension-schema.png)
@@ -396,10 +470,6 @@ This position refers to the list of commands availables after selecting some pro
   For the moment, you can't use UI extensions with more than **500** selected products & product models.
 :::
 
-### Secret
-A secret can be used for UI extensions of type `action`. If it is, this secret is used to sign (with <a href='https://wikipedia.org/wiki/SHA-2'>SHA-512</a> protocol) the body of the POST request sent to the destination.
-
-
 ### Url
 All types of UI extensions must have a configured URL. However, the parameters that are sent—or can be sent—vary depending on the specific type of extension.
 #### Query parameters placeholders