feat: add authentication documentation for REANA JupyterLab extension

docs/extensions/reana-jupyterlab/usage/authentication.md

@@ -0,0 +1,39 @@
+# Authentication
+
+## Token Reuse
+
+The REANA JupyterLab extension automatically reuses the existing JWT access token issued by the Identity Provider (IdP) that authenticated the current JupyterLab session, ESCAPE INDIGO IAM in the VRE, so no additional login or authentication steps are required.
+
+## Verifying Access
+
+You can verify that authentication is working properly:
+
+1. Open Reana JupyterLab by clicking on the REANA icon in the JupyterLab sidebar
+2. Check if you can see your workflows listed
+3. Open a workflow detail panel to see its contents
+
+If these actions succeed, your authentication is working correctly. If you see "unauthorized" errors or empty lists where you expect content, there may be an authentication issue.
+
+## Authentication Flow
+
+![Authentication Flow](../../../../static/img/reana-extension-auth-flow.png)
+
+*Authentication flow: Your VRE login generates a token that is automatically injected into your container environment and configuration, allowing the extension to access REANA resources on your behalf.*
+
+## Troubleshooting
+
+If you encounter authentication problems:
+
+- **Token expired?** Restart your JupyterLab container to get a fresh token
+- **Still not working?** Re-login to the VRE web interface, then launch a new JupyterLab session
+- **Need different credentials?** Use the connection configuration panel (see below)
+
+## Optional Connection Configuration
+
+You can still manually configure the connection to a different REANA instance:
+
+1. Open Reana JupyterLab by clicking on the REANA icon in the JupyterLab sidebar
+2. Click on the connection settings icon
+3. Enter a REANA server URL and the REANA access token.
+
+After connecting to the REANA server, a notification will appear in the bottom right corner of the screen indicating that the connection was successful. You can now interact with the REANA server from within JupyterLab.

docs/reana.md

@@ -5,6 +5,30 @@ Explore Reana on the software's [official documentation](https://docs.reana.io/)
 
 You can find other examples of differen workflow languages on the [official Reana documentation](https://docs.reana.io/advanced-usage/access-control/rucio/).
 
+# Authentication with reana-client
+
+The REANA client provides a command-line interface for authenticating with the REANA server. You can use the `reana-client auth` command which initiates an OAuth 2.0 device flow authentication:
+
+```bash
+$ reana-client auth
+```
+
+This command will provide you with a URL to visit and a code to enter, allowing you to authenticate through your browser. You can read more about OAuth2.0 and the device flow authentication in the [What is OAuth2.0 docs by auth0](https://auth0.com/intro-to-iam/what-is-oauth-2).
+
+Example output:
+
+```text
+$ reana-client auth
+Go to: https://iam-escape.cloud.cnaf.infn.it/device
+Enter code: ******
+Or open: https://iam-escape.cloud.cnaf.infn.it/device?user_code=******
+Waiting for authorization...
+```
+
+:::warning[Important]
+When using the `reana-client auth` command, please note that the VRE JupyterLab extension may not be automatically updated with your new authentication token. If you're using both the command-line client and the JupyterLab extension, you may need to restart your JupyterLab session for the extension to recognize your new authentication status.
+:::
+
 # Reana - Rucio integration
 
 A functionality to directly upload files from a Rucio RSE to the Reana workspace has been implemented. In this way, users can immediately reproduce an analysis on Reana without having to first download files locally from Rucio and then upload them to the Reana workspace. 
@@ -92,4 +116,4 @@ $ reana-client upload
 $ reana-client start      
 $ reana-client status
 ```
-5. Check the state of your workflow on https://reana-vre.cern.ch/. 
+5. Check the state of your workflow on https://reana-vre.cern.ch/.

docs/tech-docs/services/computing-resources.md

@@ -65,3 +65,33 @@ kubectl exec -i -t deployment/reana-server -n reana -- flask reana-admin token-g
 
 6. Navigate to `reana-vre.cern.ch` and log in with your IAM credentials.
 
+## JupyterLab REANA Extension Authentication
+
+This section explains how the VRE-provided JWT used by the REANA JupyterLab extension is injected and accessed during a user session. For more information about JWTs, see the [JWT documentation](https://auth0.com/docs/secure/tokens/json-web-tokens). 
+
+### Token injection at spawn time
+During user pod creation the VRE spawner:
+- Obtains (or reuses) the user's already validated access token.
+- Injects it as an environment variable (`REANA_ACCESS_TOKEN`).
+- Writes a lightweight config file with the token for `reana-client` CLI.
+
+No refresh token is stored; only the short‑lived access token is passed.
+
+### Token storage (Extension vs CLI)
+The JupyterLab extension: 
+- Reads the injected `REANA_ACCESS_TOKEN` environment variable on request.
+- Uses this token for all API calls to the REANA server.
+
+CLI (`reana-client`):
+- Loads the token from the REANA config file written during the spawning of the user session (or later replaced by running `reana-client auth`, which performs an OAuth 2.0 device flow and rewrites the stored token).
+- Uses this token for CLI commands.
+
+:::tip[Future considerations]
+```
+Authentication improvements:
+
+    - Store refresh tokens in the environment and use them to obtain new access tokens when the current one expires.
+    - Ensure shorter expiry times for access tokens to enhance security.
+    - Implement mechanism that ensure the CLI and UI are always using the same, latest access token.
+```
+:::

package.json

@@ -16,7 +16,7 @@
   "dependencies": {
     "@docusaurus/core": "3.8.0",
     "@docusaurus/preset-classic": "3.8.0",
-    "@docusaurus/theme-live-codeblock": "^3.8.0",
+    "@docusaurus/theme-live-codeblock": "3.8.0",
     "@fortawesome/fontawesome-free": "^6.7.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",

sidebars.js

@@ -96,7 +96,7 @@ const sidebars = {
       type: 'category',
       label: 'Usage',
       items: [
-        'extensions/reana-jupyterlab/usage/connection',
+        'extensions/reana-jupyterlab/usage/authentication',
         'extensions/reana-jupyterlab/usage/workflows',
         'extensions/reana-jupyterlab/usage/create',
       ],