From c3ff77512e74928abfb77dfb9fa231c80dfe7c40 Mon Sep 17 00:00:00 2001
From: Matthias Bernt <m.bernt@ufz.de>
Date: Mon, 19 Feb 2024 19:39:55 +0100
Subject: [PATCH] add documentation on how to use vault keys in file sources

---
 doc/source/admin/special_topics/vault.md      | 41 ++++++++++---------
 .../sample/file_sources_conf.yml.sample       |  3 ++
 .../user_preferences_extra_conf.yml.sample    |  2 +
 3 files changed, 27 insertions(+), 19 deletions(-)

diff --git a/doc/source/admin/special_topics/vault.md b/doc/source/admin/special_topics/vault.md
index 2c104eec37bb..006a4ca86444 100644
--- a/doc/source/admin/special_topics/vault.md
+++ b/doc/source/admin/special_topics/vault.md
@@ -97,29 +97,32 @@ The `user_preferences_extra_conf.yml` can be used to automatically route secrets
 
 ```yaml
 preferences:
-    googledrive:
-        description: Your Google Drive account
+    nextcloud:
+        description: Your NextCloud account
         inputs:
-            - name: client_id
-              label: Client ID
-              type: text
-              required: True
-            - name: client_secret
-              label: Client Secret
-              type: secret
-              store: vault
-              required: True
-            - name: access_token
-              label: Access token
+            - name: password
+              label: password
               type: password
               store: vault
-              required: True
-            - name: refresh_token
-              label: Refresh Token
-              type: secret
-              store: vault
-              required: True
+              required: False
 ```
 
 Note the `store: vault` property, which results in the property being stored in the vault. Note also that if you use `type: password`, the secret is sent to the client front-end,
 but specifying `type: secret` would mean that the values cannot be retrieved by the client, only written to, providing an extra layer of security.
+
+## Configuring file sources to use (user) secrets stored in a vault
+
+In a file source the password could be used as follows:
+
+```yaml
+- type: webdav
+  id: nextcloud
+  label: NextCloud
+  doc: UFZ NextCloud files (configure access in user preferences)
+  url: https://some-nextcloud.org
+  root: /remote.php/dav/files/${user.username}/
+  login: ${user.username}
+  password: ${user.user_vault.read_secret('preferences/ufz-nextcloud/password')}
+```
+
+This example assumes that the NextCloud username is identical to the Galaxy username. If this is not the case also the username could be a user preference that is stored in a vault.
\ No newline at end of file
diff --git a/lib/galaxy/config/sample/file_sources_conf.yml.sample b/lib/galaxy/config/sample/file_sources_conf.yml.sample
index 76b1a8616903..8d4873b37ee5 100644
--- a/lib/galaxy/config/sample/file_sources_conf.yml.sample
+++ b/lib/galaxy/config/sample/file_sources_conf.yml.sample
@@ -12,6 +12,9 @@
   root: ${user.preferences['owncloud|root']}
   login: ${user.preferences['owncloud|username']}
   password: ${user.preferences['owncloud|password']}
+  # for accessing passwords stored in a vault:
+  # password: ${user.user_vault.read_secret('preferences/owncloud/password')}
+
   # By default, the plugin will use temp files to avoid loading entire files into memory. 
   # You can change the directory here or omit to use the default temp directory.
   temp_path: /your/temp/path
diff --git a/lib/galaxy/config/sample/user_preferences_extra_conf.yml.sample b/lib/galaxy/config/sample/user_preferences_extra_conf.yml.sample
index d34243cd0143..f37f30165132 100644
--- a/lib/galaxy/config/sample/user_preferences_extra_conf.yml.sample
+++ b/lib/galaxy/config/sample/user_preferences_extra_conf.yml.sample
@@ -93,6 +93,8 @@ preferences:
             - name: password
               label: Password
               type:  password
+              # for storing the password in a vault (instead of plaintext in the DB)
+              # store: vault
               required: False
 
     invenio: