feat: add authentication documentation for REANA JupyterLab extension

Author: tomondre

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

@@ -0,0 +1,39 @@
+# Authentication
+
+## Token Reuse
+
+The REANA JupyterLab extension automatically reuses your existing VRE-issued JWT access token - the same one that authenticated your current JupyterLab session. **No additional login or authentication steps are required** to start using REANA through the extension.
+
+## Verifying Access
+
+You can verify that authentication is working properly by:
+
+1. Opening the REANA sidebar tab in JupyterLab
+2. Checking if you can see your workflows listed
+3. Opening 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.
+
+## 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 manually configure the connection to a different REANA instance by:
+
+1. Opening the REANA sidebar tab
+2. Clicking on the connection settings icon
+3. Entering a custom server URL and/or access token
+
+This is useful if you need to connect to a different REANA instance than the default one configured for VRE.
+
+## 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.*

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

@@ -5,6 +5,18 @@ 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 will be taken through the OAuth 2.0 device flow process where you'll need to enter the provided code on the authorization page to complete the authentication.
+
+> **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 +104,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/reana.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, accessed and refreshed (or not) during a user session.
+
+### 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 (UI extension vs CLI)
+UI / 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 at spawn (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.
+```
+:::