update docs (#1999)

bihealth · Oct 10, 2024 · 2249198 · 2249198
1 parent b3bab7f
commit 2249198
Show file tree

Hide file tree

Showing 11 changed files with 33 additions and 17 deletions.
diff --git a/docs_manual/source/_include/oidc_irods_token.rst b/docs_manual/source/_include/oidc_irods_token.rst
@@ -0,0 +1,6 @@
+.. note::
+
+    If you log into SODAR using a single sign-on provider, you will have to
+    generate a SODAR API token and use the token as your password when accessing
+    iRODS and iRODS file links. You can create your API token in the
+    :ref:`API Tokens <ui_api_tokens>` view.
diff --git a/docs_manual/source/_static/sodar_ui/irods_info.png b/docs_manual/source/_static/sodar_ui/irods_info.png
diff --git a/docs_manual/source/_static/sodar_ui/irods_status.png b/docs_manual/source/_static/sodar_ui/irods_status.png
diff --git a/docs_manual/source/_static/sodar_ui/login.png b/docs_manual/source/_static/sodar_ui/login.png
diff --git a/docs_manual/source/_static/sodar_ui/user_profile.png b/docs_manual/source/_static/sodar_ui/user_profile.png
diff --git a/docs_manual/source/admin_settings.rst b/docs_manual/source/admin_settings.rst
@@ -110,8 +110,9 @@ iRODS Settings
 ``IRODS_CERT_PATH``
     iRODS certificate path on server (string).
 ``IRODS_SODAR_AUTH``
-    Enable local basic auth endpoint for iRODS if an external LDAP/AD server is
-    not used (boolean, default: ``False``).
+    Enable local basic auth endpoint for iRODS. **NOTE:** This **must** be set
+    ``True`` if OIDC is enabled, or if both OIDC and LDAP auth are disabled
+    (boolean, default: ``False``).
 
 .. warning::
 

diff --git a/docs_manual/source/data_transfer_irods.rst b/docs_manual/source/data_transfer_irods.rst
@@ -47,6 +47,8 @@ You will be prompted for your password, which is the same one you use to access
 this web site. After this, you should be successfully logged on to iRODS and can
 access data on the storage in your terminal.
 
+.. include:: _include/oidc_irods_token.rst
+
 See `iRODS documentation <https://docs.irods.org/master/icommands/user/>`_
 for iCommands reference.
 

diff --git a/docs_manual/source/ext_tool_cyberduck.rst b/docs_manual/source/ext_tool_cyberduck.rst
@@ -28,6 +28,8 @@ https://cyberduck.io/download/
    onto the Cyberduck window. A new dialog should appear. Fill in your
    SODAR username and password in the respective fields.
 
+   .. include:: _include/oidc_irods_token.rst
+
    .. image:: _static/ext_tool_cyberduck/Cyberduck_new_profile.png
 
 

diff --git a/docs_manual/source/ext_tool_igv_opening.rst b/docs_manual/source/ext_tool_igv_opening.rst
@@ -23,6 +23,8 @@ your Charite or MDC user name (in lower case) followed by either ``@CHARITE``
 for Charite users or ``@MDC-BERLIN`` for MDC users. You have to use your
 Charite/MDC password for login.
 
+.. include:: _include/oidc_irods_token.rst
+
 .. image:: _static/ext_tool_igv/IGV_Open_Session.png
     :width: 75%
     :align: center

diff --git a/docs_manual/source/ui_irods_info.rst b/docs_manual/source/ui_irods_info.rst
@@ -8,6 +8,12 @@ This view displays the status of the SODAR iRODS server.
 SODAR. You can use this information to verify that the iRODS file server is up
 and running in case of data access problems.
 
+.. figure:: _static/sodar_ui/irods_info.png
+    :align: center
+    :scale: 75%
+
+    iRODS Info view with server status
+
 In this view you can generate your personal iRODS configuration by clicking the
 :guilabel:`Download Configuration` button. See :ref:`data_transfer_irods`
 for more information on connecting to iRODS and data transfers.
@@ -17,8 +23,4 @@ you with the same user name and password you use to access SODAR. However, to
 access any project data in iRODS you will need to be explicitly granted project
 access in SODAR.
 
-.. figure:: _static/sodar_ui/irods_status.png
-    :align: center
-    :width: 50%
-
-    iRODS server status
+.. include:: _include/oidc_irods_token.rst
diff --git a/docs_manual/source/ui_login.rst b/docs_manual/source/ui_login.rst
@@ -11,14 +11,15 @@ The login view presents a simple form for logging into the system.
 
     SODAR login view
 
-When connected to multiple authentication sources, use your usual user name
-followed by ``@DOMAIN`` of your home organization and your password in your
-organization. For example, at BIH, you are expected to use ``@CHARITE`` or
-``@MDC-BERLIN``.
+When connecting to SODAR with your organization's account, use your usual user
+name followed by ``@DOMAIN`` of your home organization and your password. For
+example, for the SODAR instance at BIH, you are expected to use ``@CHARITE`` or
+``@MDC-BERLIN`` in your user name.
 
-At other sites, your administrator should have setup an appropriate messages
-such as the one for BIH that you see above.
-
-If enabled, you can also see a separate button for single sign-on. Clicking this
-button will take you to the single sign-on service used at your organization,
-where you will be prompted to provide your credentials.
+If the site has single sign-on enabled, you can find a button for the single
+sign-on provider below the regular login form. By default this button is labeled
+:guilabel:`Single Sign-On Login`, but it button may look different depending on
+the service used. Clicking on the button will take you to the single sign-on
+service used at your organization, where you will be prompted to provide your
+login credentials. After a successful login you will be redirected back to
+SODAR.