feat: add authentication documentation for REANA JupyterLab extension #35

tomondre · 2025-08-14T15:09:09Z

The main updates provide detailed explanations of how authentication tokens are managed, how users can verify or troubleshoot authentication, and the differences between the UI extension and CLI workflows.

Soap2G

Hi @tomondre, good progress!

A few minor comments below.

Soap2G · 2025-08-14T15:15:49Z

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

+
+## 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.


Suggested change

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.

The REANA JupyterLab extension automatically reuses the existing JWT access token issued by the IdP, corresponding to the one that authenticated the current JupyterLab session. **No additional login or authentication steps are required** to start using REANA through the extension.

I was unsure how to mention that the token is VRE requested. The VRE initiates the token request itself, hence I have mentioned like this, but I can see that it is incorrect. I will change it to your suggestion

Thanks! "VRE-issued" it's definitely NOT incorrect (in a sense it is true), but in the perspective of having this documentation usable by a broader audience than the VRE one, I think it's better to generalise the fact that it doesn't matter the token provenance, the only important thing is that it's a valid token :)

Soap2G · 2025-08-14T15:16:45Z

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

+
+## Optional Connection Configuration
+
+You can manually configure the connection to a different REANA instance by:


Suggested change

You can manually configure the connection to a different REANA instance by:

You can still manually configure the connection to a different REANA instance by:

Soap2G · 2025-08-14T15:17:53Z

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

+
+1. Opening the REANA sidebar tab
+2. Clicking on the connection settings icon
+3. Entering a custom server URL and/or access token


Suggested change

3. Entering a custom server URL and/or access token

3. Entering a custom server URL and access token

Soap2G · 2025-08-14T15:20:56Z

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

+No refresh token is stored; only the short‑lived access token is passed.
+
+### Token storage (UI extension vs CLI)
+UI / JupyterLab extension: 


Suggested change

UI / JupyterLab extension:

The UI / JupyterLab extension:

Soap2G · 2025-08-14T15:22:30Z

docs/reana.md

+Waiting for authorization...
+```
+
+> **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.


Suggested change

> **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.

:::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.

:::

Also, please have a look at https://github.com/vre-hub/vre-hub.github.io/actions/runs/16969223016/job/48101346774?pr=35

Just ping if you need any Docusaurus related help

This change ensures all packages are the same version to avoid dependency conflicts.

garciagenrique · 2025-08-15T09:45:15Z

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

+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.


Is the unauthorized feature developed and implemented ?

The "unauthorized" message is my assumption for an error message that could appear if something goes wrong.
This PR contains documentation about multiple things that have not been developed and implemented, and I had to assume and think through some of the issues/challenges that may arise. Do you think it could be useful to make the docs more abstract and this paragraph to avoid specific values?

garciagenrique

Small comments, otherwise looks fine to me ! Good job @tomondre !

garciagenrique · 2025-08-15T09:46:17Z

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

+
+## Token Reuse
+
+The REANA JupyterLab extension automatically reuses the existing JWT access token issued by the IdP, corresponding to the one that authenticated the current JupyterLab session. **No additional login or authentication steps are required** to start using REANA through the extension.


add something like "...the current JupyterLab session - in the case of the VRE, the ESCAPE INDIGO IAM"

garciagenrique · 2025-08-15T09:49:35Z

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

+
+You can still manually configure the connection to a different REANA instance by:
+
+1. Opening the REANA sidebar tab


Open Reana JupyterLab by clicking on the REANA icon in the JupyterLab sidebar.

garciagenrique · 2025-08-15T09:49:52Z

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

+You can still manually configure the connection to a different REANA instance by:
+
+1. Opening the REANA sidebar tab
+2. Clicking on the connection settings icon


garciagenrique · 2025-08-15T09:53:10Z

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

+
+1. Opening the REANA sidebar tab
+2. Clicking on the connection settings icon
+3. Entering a custom server URL and access token


Enter a REANA server URL and the REANA access token.

garciagenrique · 2025-08-15T09:54:06Z

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

+2. Clicking on the connection settings icon
+3. Entering a custom server URL and access token
+
+This is useful if you need to connect to a different REANA instance than the default one configured for VRE.


This sentence doesn't add any relevant information.

Please change it with the last paragraph of the page you removed:

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.

garciagenrique · 2025-08-15T10:00:15Z

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:


Please add a link for oauth2.0 so that people can educate themselves, for example
https://auth0.com/intro-to-iam/what-is-oauth-2
or https://oauth.net/2/
(I prefer first link, more user-friendly. Thoughts @Soap2G)

garciagenrique · 2025-08-15T10:01:14Z

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, accessed and refreshed (or not) during a user session.


user friendly explanatory link for JWT too, please.

garciagenrique · 2025-08-15T10:02:32Z

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

+No refresh token is stored; only the short‑lived access token is passed.
+
+### Token storage (UI extension vs CLI)
+The UI / JupyterLab extension: 


By UI you mean the Jupyterlba extension, right ? In this case remove UI to avoid misunderstandings, please

garciagenrique · 2025-08-15T10:03:55Z

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

+- 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).


change it with written "during the spawning of the user session"

garciagenrique · 2025-08-15T10:04:36Z

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

+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


Add a point at the end of the sentence, please

…sion

feat: add authentication documentation for REANA JupyterLab extension

2b3f0bb

tomondre force-pushed the auth-docs branch from 9406627 to 2b3f0bb Compare August 14, 2025 15:13

tomondre marked this pull request as ready for review August 14, 2025 15:13

Soap2G reviewed Aug 14, 2025

View reviewed changes

tomondre added 2 commits August 15, 2025 10:19

feat: update authentication documentation

a008661

fix: pin @docusaurus/theme-live-codeblock dependency to version 3.8.0

66db37d

This change ensures all packages are the same version to avoid dependency conflicts.

garciagenrique reviewed Aug 15, 2025

View reviewed changes

garciagenrique requested changes Aug 15, 2025

View reviewed changes

feat: enhance authentication documentation for REANA JupyterLab exten…

6e40c68

…sion


		## 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.


		## Optional Connection Configuration

		You can manually configure the connection to a different REANA instance by:

	You can manually configure the connection to a different REANA instance by:
	You can still manually configure the connection to a different REANA instance by:

	3. Entering a custom server URL and/or access token
	3. Entering a custom server URL and access token


		You can still manually configure the connection to a different REANA instance by:

		1. Opening the REANA sidebar tab

feat: add authentication documentation for REANA JupyterLab extension #35

Are you sure you want to change the base?

feat: add authentication documentation for REANA JupyterLab extension #35

Uh oh!

Conversation

tomondre commented Aug 14, 2025

Uh oh!

Soap2G left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Soap2G Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

garciagenrique left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Soap2G Aug 15, 2025 •

edited

Loading