topics: auth: document utility scripts and OAuth2 clients

2 files changed, 179 insertions, 0 deletions

diff --git a/topics/authentication/cli_utility_scripts.gmi b/topics/authentication/cli_utility_scripts.gmi
new file mode 100644
index 0000000..65d93e0
--- /dev/null
+++ b/topics/authentication/cli_utility_scripts.gmi
@@ -0,0 +1,121 @@
+# CLI Utility Scripts
+
+This documents the various utility scripts that are provided with the project
+whose purposes are to support the operation of the application in one way or
+another.
+
+To get a list of the available scripts/flask commands that can be run, do:
+
+```sh
+FLASK_APP="main.py" flask --help
+```
+
+With that, you should get a list of commands, which as of 2023-05-26 are:
+
+```sh
+. . . output truncated to save space ...
+
+Commands:
+  apply-migrations     Apply the dabasase migrations.
+  assign-system-admin  Assign user with ID `user_id` administrator role.
+  init-dev-clients     Initialise a development client for OAuth2 sessions.
+  init-dev-users       Initialise development users for OAuth2 sessions.
+  routes               Show the routes for the app.
+  run                  Run a development server.
+  shell                Run a shell in the app context.
+```
+
+*NB*: You can simply do `export FLASK_APP="main.py"` at the beginning of your
+shell session and then just run the commands without prepending with the
+`FLASK_APP="main.py"` declaration.
+
+## Setting a User as System Administrator
+
+Once you have registered the user with the new (as of 2023-05-26)
+auth(entic|oris)ation system, you can then proceed to specify that the user is
+going to be a system administrator of the system.
+
+You will need to retrieve the users identifier (UUID) from the system; say the
+UUID you get for the user is `5b15ef01-a9d7-4ee4-9a38-fe9dd1d871b8`, you can
+then set that user as a system administrator by running:
+
+```sh
+FLASK_APP="main.py" flask assign-system-admin 5b15ef01-a9d7-4ee4-9a38-fe9dd1d871b8
+```
+
+You can retrieve the user ID from the (SQLite) database, with something like:
+
+```sh
+$ sqlite3 /home/frederick/genenetwork/gn3_files/db/auth.db
+SQLite version 3.40.0 2022-11-16 12:10:08
+Enter ".help" for usage hints.
+sqlite> SELECT * FROM users;
+0ad1917c-57da-46dc-b79e-c81c91e5b928|test@development.user|Test Development User
+9c5d4ddf-c361-4133-add3-9ab9845bb9f2|fredtest02@gmail.com|A New Group Member
+b4a8ed7a-a878-4884-94e0-26d3fe0c56a3|fredleader@gmail.com|Frederick the Group Leader
+```
+
+## Make Existing Data Publicly Visible
+
+This will only act on any existing data that is not already linked with a user
+group in the new auth system.
+
+This can be run using flask with
+
+```sh
+FLASK_APP="main.py" flask make-data-public
+```
+
+which will use the application's configuration settings for the
+auth(entic|oris)ation database and the MariaDB database.
+
+You could also run the script directly with:
+
+```sh
+python3 -m scripts.migrate_existing_data AUTHDBPATH MYSQLDBURI
+```
+
+where `AUTHDBPATH` and `MYSQLDBURI` are replaced with the appropriate values,
+e.g.
+
+```sh
+python3 -m scripts.migrate_existing_data \
+    /home/frederick/genenetwork/gn3_files/db/auth.db \
+    mysql://webqtlout:webqtlout@127.0.0.1:3307/db_webqtl
+```
+
+## List Available Routes
+
+```sh
+FLASK_APP="main.py" flask routes
+```
+
+## Drop Into a Python Shell
+
+```sh
+FLASK_APP="main.py" flask shell
+```
+
+## Development Scripts
+
+The commands in this section are meant for easing development and are not to be
+run in a production environment.
+
+### Setting up a Sample User for Development
+
+```sh
+FLASK_APP="main.py" flask init-dev-users
+```
+
+That will initialise your development database with a development user with the
+following details:
+
+- User ID: 0ad1917c-57da-46dc-b79e-c81c91e5b928
+- Email: test@development.user
+- Password: testpasswd
+
+### Setting up Sample OAuth2 Client for Development
+
+```sh
+FLASK_APP="main.py" flask init-dev-clients
+```
diff --git a/topics/authentication/oauth2_clients.gmi b/topics/authentication/oauth2_clients.gmi
new file mode 100644
index 0000000..36f5eee
--- /dev/null
+++ b/topics/authentication/oauth2_clients.gmi
@@ -0,0 +1,58 @@
+# OAuth2
+
+The new authorisation system is made up of two layers:
+
+* Client authorisation
+* User authentication/authorisation
+
+This document will concern itself mostly with "Client Authorisation".
+
+## Client Authorisation
+
+The authentication/authorisation system will (probably) find use in the entire
+suite of applications that are under the Genenetwork umbrella.
+
+The relevant applications (as of 27 May 2023) are:
+
+=> https://github.com/genenetwork/genenetwork3 Genenetwork3
+  Serves as both the authorisation server and the API server.
+=> https://github.com/genenetwork/genenetwork2 Genenetwork 2
+   Will eventually be the main user-facing UI making requests to GN3 for data and computational requests.
+=> https://gitlab.com/fredmanglis/gnqc_py QC and Data Upload
+   Provides a means to upload new data into the Genenetwork database. It does perform some quality-control on the data before upload. Currently, this application is not available to the general public due to the potential to mess up the data. Once the auth system has been running a while, and the major bugs quashed, this will be integrated into the other system and allow users to upload their own data.
+
+In this case, the GN2 and QC applications would be clients to GN3 (as the auth
+server), and will have specific scopes of access.
+
+As such, we need to register the clients that can access the authorisation
+server.
+
+If you try to access the authorisation server, or for that matter, the API
+server with a client that is not registered, you will receive an error message
+of the form:
+
+```json
+{
+    "error": "invalid_client",
+    "error_description": "No client found for the given CLIENT_ID and CLIENT_SECRET."
+}
+```
+
+### Registering a new OAuth2 Client
+
+* **TODO**: Implement client registration then provide docs here.
+
+**NOTES**:
+
+* Collect appropriate client data and register (provide means)
+* Get registered client's "CLIENT ID" and "CLIENT SECRET" values
+* Configure values on client
+
+## User Authentication/Authorisation
+
+A user will make use of (an) authorised client(s) (see 'Client Authorisation'
+section above) to access the authorisation and API servers.
+
+Once the user has authenticated (provided valid authentication credentials),
+they will be able to access the resources in the system according to the roles
+and privileges that they are authorised for.