diff options
| -rw-r--r-- | README.md | 119 |
1 files changed, 119 insertions, 0 deletions
@@ -1,12 +1,125 @@ # GeneNetwork Auth +[](https://ci.genenetwork.org/jobs/gn-auth) +[](https://ci.genenetwork.org/jobs/gn-auth-pylint) +[](https://ci.genenetwork.org/jobs/gn-auth-mypy) + This project is for the GeneNetwork Authentication/Authorisation server to be used across the entire suite of the GeneNetwork services. +## Configuration + +## Installation + +## Migrations + +**NOTE**: Do not create migration scripts manually. Use the processes indicated below. + +### Authentication/Authorisation Migrations + +The migration scripts for the authentication and authorisation system are in the *migrations/auth* folder in the root of the repository. + +To create an new migration script for the, do: + +```bash +$ yoyo new -m "<description of the migration>" ./migrations/auth/ +``` + +The command will ask whether you want to save the migration configuration, e.g. + +```bash +$ yoyo new --config=yoyo.auth.ini -m "testing a new migration" +Error: could not open editor! +Created file ./migrations/auth/20221103_02_HBzwk-testing-a-new-migration.py +Save migration configuration to yoyo.ini? +This is saved in plain text and contains your database password. + +Answering 'y' means you do not have to specify the migration source or database connection for future runs [yn]: +``` + +If you specify `y` then a file named yoyo.ini will be created in your current working directory, and you can refer to it to avoid providing the `./migrations/auth` explicitly. + +Now you can open and edit the scripts to provide the appropriate SQL statements to update or rollback your schema. + +### Running the Migrations + +To apply the migrations, you can do something like: + +```bash +$ yoyo apply --database="sqlite:////tmp/test-auth.db" ./migrations/auth/ + +[20221103_01_js9ub-initialise-the-auth-entic-oris-ation-database] +Shall I apply this migration? [Ynvdaqjk?]: Y + +[20221103_02_sGrIs-create-user-credentials-table] +Shall I apply this migration? [Ynvdaqjk?]: Y + +[20221108_01_CoxYh-create-the-groups-table] +Shall I apply this migration? [Ynvdaqjk?]: Y + +[20221108_02_wxTr9-create-privileges-table] +Shall I apply this migration? [Ynvdaqjk?]: Y +... +``` + +If you have previously initialised the yoyo config file, you can put the database uri in the configuration file and just provide it to avoid the prompt to save the configuration. + +As a convenience, and to enable the CI/CD to apply the migrations automatically, I have provided a flask cli command that can be run with: + +```bash +$ export FLASK_APP=main.py +$ flask apply-migrations +``` + +This expects that the following two configuration variables are set in the application: + +* `AUTH_MIGRATIONS`: path to the migration scripts +* `AUTH_DB`: path to the sqlite database file (will be created if absent) + +To enable you to run the OAuth2 server without HTTPS, you need to setup the +following environment variable(s): + +* `export AUTHLIB_INSECURE_TRANSPORT=true`: Allows you to run the Authlib server + without HTTPS on your development machine. + +## Running + +### Development + +To run the application during development: + +```sh +export FLASK_DEBUG=1 +export FLASK_APP="main.py" +export AUTHLIB_INSECURE_TRANSPORT=true +export GN_AUTH_CONF="${HOME}/genenetwork/configs/gn_auth_conf.py" +flask run --port=8081 +``` + +replace the `GN_AUTH_CONF` file with the correct path for your environment. + +### Production + +You can run the application on production with GUnicorn with something like: + +```sh +gunicorn --bind 0.0.0.0:8081 --workers 6 --keep-alive 6000 --max-requests 10 \ + --max-requests-jitter 5 --timeout 1200 wsgi:app +``` ## Checks +Running checks ensures the code is good, and the application actually does what +it is expected to do. + +The checks we do are +- Lint-checks +- Type-checks +- Unit tests + ### Linting ```bash @@ -25,3 +138,9 @@ mypy --show-error-codes . export AUTHLIB_INSECURE_TRANSPORT=true pytest -k unit_test ``` + +## OAuth2 + +This application acts as an OAuth2 server, allowing the client applications to +authenticate and access the API endpoints with the appropriate authorisation +levels. |