system/ReSeeD-user-management.md

+# ReSeeD user management
+
+⚠️ Note: This page is in the `system` section because ReSeeD still lacks a web interface for user management and thus requires the admin to log in via SSH and create/manage ReSeeD user accounts using the docker shell and rails console.
+
+## Create Users from the Rails Console
+
+We have developed a rake task to register users called [setup_users.rake](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/develop/hyrax/lib/tasks/setup_users.rake). The rake task creates users defined in a JSON file. This task can also be used to update user information or their role.
+
+### Different ways to authenticate in RDMS
+
+Users can authenticate into RDMS by the following means
+
+  * Database authentication (using email id and password)
+
+  * Shibboleth authentication (using SAML id)
+
+  * Orcid authentication (using orcid)
+
+If your user would like to sign in using the database or using Orcid authentication, they need to registered in RDMS before they can sign in.
+
+There is no need to register Shibboleth users using this rake task, except to assign them to appropriate roles. 
+
+### User attributes
+
+The list of possible user attributes are
+
+* email
+
+* password
+
+* name
+
+* saml_id
+
+* orcid
+
+* role
+
+* group_id
+
+### User roles
+
+Users can be assigned to the following roles 
+
+* admin
+* publication_manager
+* CRC1280_manager
+* CRC1280_member
+* CRC1280_group_manager
+* CRC1280_group_member
+
+  Roles `CRC1280_group_manager` and `CRC1280_group_member` also needs the attribute `group_id` for the role to be assigned.
+
+### Preparing the JSON file
+
+See the template file [setup.json.template](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/develop/hyrax/seed/setup.json.template) for an example JSON file.
+
+* Copy the file in `hyrax/seed/setup.json.template` to `hyrax/seed/users.json`
+
+* Modify `users.json` so it has the list of users to create / update.
+
+* For each user
+
+  * The only required attributes are one of email / saml_id / orcid
+
+  * We encourage each user also has their name, to be able to provide a better user experience in the user interface.
+
+  * If no password is provided, a random password will be generated. 
+
+    If a user is going to authenticate using the database, this password would need to be updated by a system administrator from the web rails console, before the user is able to sign in. 
+
+### Running the rake task
+
+To run the rake task, 
+
+* Open a terminal in the web container
+
+  ```
+  docker exec -it rdms-web-1 /bin/bash
+  ```
+
+  Note: The web container could be different for you. Run `docker ps` to get the name of the container
+
+* Run the rake task
+  ```
+  rake rdms:setup_users["/data/seed/users.json","false"]
+  ```
+  The rake task takes two arguments
+  
+  `seedfile` : Path to the JSON file containing the list of users to be added (for example: `/data/seed/users.json`)
+  
+  `update_users` : "true" or "false".  
+      If true, if a user already exists, the values will be updated with those in the JSON file. 
+      If false, only new users will be created. 
+
+**Note**
+
+If the rake task is run more than once using the same JSON file, the task will cycle through the list of users in the JSON file and check they exist. 
+
+* If update is set to true, the user details will be updated. 
+	
+	It could have the unintended consequence of updating a user password, if one is set in the JSON file and it was updated for the user in the mean time.
+	
+* If update is set to false, the task will skip to the next user and carry on. 
+
+  No harm will be caused if the rake task is run more than once when update is false.
+
+### Creating users at start-up
+The rake task [setup_hyrax.rake](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/master/hyrax/lib/tasks/setup_hyrax.rake) which is used to setup the application during docker startup, calls this rake task [setup_users.rake](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/develop/hyrax/lib/tasks/setup_users.rake) to create users at start-up. 
+
+It creates all users listed in the file `hyrax/seed/setup.json`, if the file exists and the user does not exist at start-up.
+
+To prepare the file hyrax/seed/setup.json, copy the template file and modify the user attributes as required. See [Preparing the JSON file](#preparing-the-json-file) for details.
+
+The user details will not be updated. So restarting a container will not overwrite any existing user details.
+
+### Setup.json (prior to v0.3.6)
+
+Previous to release [v0.3.6](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/tags/v0.3.6), the file [hyrax/seed/setup.json](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/aad36d72974b4f8fd2753e91d44e08a7d4e9429e/hyrax/seed/setup.json) was available. This has now been renamed to [setup.json.template](https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/develop/hyrax/seed/setup.json.template) and extended to show how to create all of the different types of users, and roles. If you would like the file previous to release v0.3.6, download it using 
+
+```
+wget https://gitlab.ruhr-uni-bochum.de/researchdata/rdms/-/blob/aad36d72974b4f8fd2753e91d44e08a7d4e9429e/hyrax/seed/setup.json
+```
+
+### `setup.json` used in rdms.cottagelabs
+
+[setup.json](/system/development-notes/setup.json)
+
+## Manage Users on the Rails Console
+
+Note: These commands are entered in the `rails c` console inside the `web` container.
+
+```ruby
+# find user by email address
+sometestvarfoobar = User.find_by_user_key("user@example.net")
+
+# check content of variable
+sometestvarfoobar
+
+# change user's email address:
+sometestvarfoobar.email="user@example.org"
+
+# save changed email address to database
+sometestvarfoobar.save
+
+# delete the user
+sometestvarfoobar.delete
+```
\ No newline at end of file