diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Scripts.md | 121 | ||||
| -rw-r--r-- | docs/authentication_and_authorisation/oauth2_clients.md | 64 |
2 files changed, 0 insertions, 185 deletions
diff --git a/docs/Scripts.md b/docs/Scripts.md deleted file mode 100644 index 65d93e0..0000000 --- a/docs/Scripts.md +++ /dev/null @@ -1,121 +0,0 @@ -# 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/docs/authentication_and_authorisation/oauth2_clients.md b/docs/authentication_and_authorisation/oauth2_clients.md deleted file mode 100644 index f9af8f9..0000000 --- a/docs/authentication_and_authorisation/oauth2_clients.md +++ /dev/null @@ -1,64 +0,0 @@ -# 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: - -- [Genenetwork 3](https://github.com/genenetwork/genenetwork3): Serves as both - the authorisation server and the API server. -- [Genenetwork 2](https://github.com/genenetwork/genenetwork2): Will eventually - be the main user-facing UI making requests to GN3 for data and computational - requests. -- [QC and Data Upload](https://gitlab.com/fredmanglis/gnqc_py): 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. |