Add command line tool for user and project management in authenticate…

…d server (asreview#1419)

DEVELOPMENT.md

@@ -176,9 +176,7 @@ Store the JSON file on the server and start the ASReview application from the CL
 ```
 $ python3 -m asreview lab --flask-configfile=<path-to-JSON-config-file>
 ```
-A number of the keys in the JSON file are standard Flask parameters. The keys that are specific for authenticating ASReview 
-
-pare summarised below:
+A number of the keys in the JSON file are standard Flask parameters. The keys that are specific for authenticating ASReview are summarised below:
 *  AUTHENTICATION_ENABLED: if set to `true` the application will start with authentication enabled. If the SQLite database does not exist, one will be created during startup.
 * SECRET_KEY: the secret key is a string that is used to encrypt cookies and is mandatory if authentication is required.
 * SECURITY_PASSWORD_SALT: another string used to hash passwords, also mandatory if authentication is required.
@@ -187,18 +185,66 @@ pare summarised below:
 * EMAIL_CONFIG: configuration of the SMTP email server that is used for email verification. It also allows users to retrieve a new password after forgetting it. Don't forget to enter the reply address (REPLY_ADDRESS) of your system emails. Omit this parameter if system emails for verification and password retrieval are unwanted.
 * OAUTH: an authenticated ASReview application may integrate with the OAuth functionality of Github, Orcid and Google. Provide the necessary OAuth login credentails (for [Github](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app), [Orcid](https://info.orcid.org/documentation/api-tutorials/api-tutorial-get-and-authenticated-orcid-id/) en [Google](https://support.google.com/cloud/answer/6158849?hl=en)). Please note that the AUTHORIZATION_URL and TOKEN_URL of the Orcid entry are sandbox-urls, and thus not to be used in production. Omit this parameter if OAuth is unwanted.
 
-### Converting an unauthenticated application in an authenticated one
+### Converting an unauthenticated application into an authenticated one
+
+Start the application with authentication enabled for the first time. This ensures the creation of the necessary database. To avoid unwanted user input, shutdown the application.
+
+To convert the old unauthenticated projects into authenticated ones, the following steps should be taken:
+
+1. Create user accounts for people to sign in.
+2. Convert project data and link the projects to the owner's user account.
+
+Under the CLI sub commands of the ASReview application a tool can be found that facilitates these procedures:
+
+```
+$ asreview auth-tool --help
+```
+
+#### Creating user accounts
+
+The first step is to create user accounts. This can be done interactively or by using a JSON string to bulk insert the accounts. To add user accounts interactively run the following command:
+```
+$ asreview auth-tool add-users --db-path ~/.asreview/asreview.production.sqlite
+```
+
+Note that the absolute path of the sqlite database has to be provided. Also note that if your app runs in development mode, use the `asreview.development.sqlite` database instead. The tool will prompt you if you would like to add a user account. Type `Y` to continue and enter an email address, name, affiliation (not required) and a password for every person. Continue to add as many users as you would like.
+
+If you would like to bulk insert user accounts use the `--json` option:
+```
+$ asreview auth-tool add-users -j "[{\"email\": \"[email protected]\", \"name\": \"Name of User\", \"affiliation\": \"Some Place\", \"password\": \"1234@ABcd\"}]" --db-path ~/.asreview/asreview.production.sqlite
+```
+The JSON string represents a Python list with a dictionary for every user account with the following keys: `email`, `name`, `affiliation` and `password`. Note that passwords require at least one symbol. These symbols, such as the exclamation mark, may compromise the integrity of the JSON string.
+
+#### Preparing the projects
+
+After creating the user accounts, the existing projects must be stored and linked to a user account in the database. The tool provides the `list-projects` command to prepare for this step in case you would like to bulk store all projects. Ignore the following commands if you prefer to store all projects interactively. 
+
+Without a flag, the command lists all projects:
+```
+$ asreview auth-tool list-projects
+```
+If you add the `--json` flag:
+```
+$ asreview auth-tool list-projects --json
+```
+the tool returns a convenient JSON string that can be used to bulk insert and link projects into the database. The string represents a Python list containing a dictionary for every project. Since the ID of the user account of 
+the owner is initially unknown, the `0` behind every `owner_id` key needs to be replaced with the appropriate owner ID. That ID number can be found if we list all user accounts with the following command:
+```
+$ asreview auth-tool list-users --db-path ~/.asreview/asreview.production.sqlite
+```
 
-At the moment there is a very basic tool to convert your unauthenticated ASReview application into an authenticated one. The following steps sketch a possible approach for the conversion:
+#### Inserting and linking the projects into the database
 
-1. In the ASReview folder (by default `~/.asreview`) you can find all projects that were created by users in the unauthenticated version. Every sub-folder contains a single project. Make sure you can link those projects to a certain user. In other words: make sure you know which project should be linked to which user.
-2. Start the application, preferably with using the config JSON file and setting the ALLOW_ACCOUNT_CREATION to `true`.
-3. Use the backend to create user accounts (done with a POST request to `/auth/signup`, see `/asreview/webapp/api/auth.py`). Make sure a full name is provided for every user account. Once done, one could restart the application with ALLOW_ACCOUNT_CREATION set to `False` if account creation by users is undesired.
-4. Run the `auth_conversion.py` (root folder) script and follow instructions. The script iterates over all project folders in the ASReview folder and asks which user account has to be associated with it. The script will establish the connection in the SQlite database and rename the project folders accordingly.
+Inserting and linking the projects into the database can be done interactively:
+```
+$ asreview auth-tool link-projects --db-path ~/.asreview/asreview.production.sqlite
+```
+The tool will list project by project and asks what the ID of the owner is. That ID can be found in the user list below the project information.
 
-TODO@Jonathan @Peter: I have verified this approach. It worked for me but
-obviously needs more testing. I don't think it has to grow into a bombproof solution, but should be used as a stepping stone for an admin
-with a little bit of Python knowledge who wants to upgrade to an authenticated version. Anyhow: give it a spin: create a couple of projects, rename the folders in the original project_ids and remove from the projects folder. The script should restore all information.
+One can also insert all project information by using the JSON string that was produced in the previous step:
+```
+$ asreview auth-tool link-projects --json "[{\"folder\": \"project-id\", \"version\": \"1.1+51.g0ebdb0c.dirty\", \"project_id\": \"project-id\", \"name\": \"project 1\", \"authors\": \"Authors\", \"created\": \"2023-04-12 21:23:28.625859\", \"owner_id\": 15}]" --db-path ~/.asreview/asreview.production.sqlite
+``` 
 
 ## Documentation
 

asreview/entry_points/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 from asreview.entry_points.algorithms import AlgorithmsEntryPoint
+from asreview.entry_points.auth_tool import AuthTool
 from asreview.entry_points.base import BaseEntryPoint
 from asreview.entry_points.lab import LABEntryPoint
 from asreview.entry_points.lab import WebRunModelEntryPoint