From 99e443942e24d6491f17cdf7539331f0fb4271a7 Mon Sep 17 00:00:00 2001 From: Asti Date: Wed, 12 Jun 2024 21:13:02 +0530 Subject: [PATCH] Adds AuthMS Drawio and resolves documentation issues --- cli/DEVELOPER.md | 91 +++++++- docker/README.md | 27 +++ docs/admin/cli.md | 52 +++-- docs/admin/servers/auth.md | 21 ++ docs/developer/oauth/AUTHMS.drawio | 337 +++++++++++++++++++++++++++++ mkdocs-github.yml | 1 - mkdocs.yml | 1 - 7 files changed, 503 insertions(+), 27 deletions(-) create mode 100644 docs/developer/oauth/AUTHMS.drawio diff --git a/cli/DEVELOPER.md b/cli/DEVELOPER.md index 13371e88a..c0a3127c6 100644 --- a/cli/DEVELOPER.md +++ b/cli/DEVELOPER.md @@ -46,6 +46,76 @@ The CLI has two layers of code: is responsible for. It also has helper functions that can be used across the CLI. +### TOML File + +The base configuration file used by the CLI is +the _dtaas.toml_ file. + +This is divided into 3 sections: + +- The Global variables: + +```toml +name = "Digital Twin as a Service (DTaaS)" +version = "0.1.0" +owner = "The INTO-CPS-Association" +git-repo = "https://github.com/into-cps-association/DTaaS.git" +``` + +These define the name, version, owner and git-repo of the DTaaS instance. +Currently, these aren't directly used in the CLI and serve the purpose +of documentation and reference. + +- Common Instance Variables + +```toml +[common] +# absolute path to the DTaaS application directory +server-dns = "localhost" +path = "/home/Desktop/DTaaS" +``` + +The _path_ variable is used globally by the CLI. +It is required while creating new workspace files, +to run bash commands and create new docker services. + +The _server-dns_ variable is used to decide if +the DTaaS instance is a localhost instance or a server +deploy instance. In the case of server deploy, +it is used to define the routes of the server type +docker compose services appropriately. + +- Users variables + +```toml +[users] +# matching user info must present in this config file +add = ["username1","username2", "username3"] +delete = ["username2", "username3"] + +[users.username1] +email = "username1@gitlab.foo.com" +``` + +This section firstly has two important lists, add and delete. +The new users to be created, or current users to be removed +from the instance using the CLI are fetched from here in the code. + +Additionally, each unique _user_ identified by their _username_ +has an _email_ variable, which should have the email of the user +as registered on the Gitlab instance. This is currently NOT IN USE. +It is aimed to be incorporated in future versions. + +- Website Client variables + +```toml +[client.web] +config = "/home/Desktop/DTaaS/env.local.js" +``` + +These variables are currently not in use, and will be incorporated +in future work. + ## Setup ```bash @@ -112,4 +182,23 @@ and publish your package to PyPI using poetry: ```bash poetry publish -``` \ No newline at end of file +``` + +## Future work + +The final aim for the CLI is to be the standard way that +admins setup, manage, and interact with the DTaaS instance. +Although the base structure for the CLI is set up and +the commands to manage users have been incorporated, we are +a long way from our final aim. + +The following are the next steps for the CLI: + +- Incorporating the AuthMS _conf_ file rules + in the user management commands. + +- [Bug fix] Currently users with usernames containing + a '.' in it aren't handled well by the CLI and result in errors. + This is because '.' is a special character for labels in docker compose. + We need to include such usernames, simply by internally replacing + '.' instances in usernames by '-' or '_'. \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index 86dc970f0..328863b40 100644 --- a/docker/README.md +++ b/docker/README.md @@ -112,6 +112,33 @@ the publication of images to Docker Hub. :stop_sign: This publishing step is managed only by project maintainers. Regular developers can skip this step. +The DTaaS development team publishes reusable packages which are then +put together to form the complete DTaaS application. + +The packages are published on +[github](https://github.com/orgs/INTO-CPS-Association/packages?repo_name=DTaaS), +[npmjs](https://www.npmjs.com/org/into-cps-association), and +[docker hub](https://hub.docker.com/u/intocps) repositories. + +The packages on +[github](https://github.com/orgs/INTO-CPS-Association/packages?repo_name=DTaaS) +are published more frequently but are not user tested. +The packages on [npmjs](https://www.npmjs.com/org/into-cps-association) +and [docker hub](https://hub.docker.com/u/intocps) +are published at least once per release. +The regular users are encouraged to use the packages from npm and docker. + +A brief explanation of the packages is given below. + +| Package Name | Description | Documentation for | Availability | +|:----|:----|:----|:----| +| dtaas-web | React web application | [container image](client/docker.md) | [docker hub](https://hub.docker.com/r/intocps/dtaas-web) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/container/dtaas-web) | +| libms |Library microservice | [npm package](servers/lib/npm.md) | [npmjs](https://www.npmjs.com/package/@into-cps-association/libms) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/npm/libms) | +| | | [container image](servers/lib/docker.md) | [docker hub](https://hub.docker.com/r/intocps/libms) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/container/libms) | +| runner | REST API wrapper for multiple scripts/programs | [npm package](../user/servers/execution/runner/README.md) | [npmjs](https://www.npmjs.com/package/@into-cps-association/runner) and [github](https://github.com/INTO-CPS-Association/DTaaS/pkgs/npm/runner) | +| ml-workspace-minimal (fork of [ml-workspace](https://github.com/ml-tooling/ml-workspace)) | User workspace | not available | [docker hub](https://hub.docker.com/r/intocps/ml-workspace-minimal/tags). Please note that this package is **highly experimental** and only v0.15.0-b2 is usable now. | + + ### React Website ```sh diff --git a/docs/admin/cli.md b/docs/admin/cli.md index 49b5f0791..1bfb9079e 100644 --- a/docs/admin/cli.md +++ b/docs/admin/cli.md @@ -74,39 +74,43 @@ Then simply: dtaas admin user add ``` -#### Caveat +#### Caveats -This brings up the containers, without the AuthMS authentication. +1. '.' are a special character. Currently, usernames which have + '.'s in them cannot be added properly through the CLI. + This is an active issue that will be resolved in future releases. -- Currently the _email_ fields for each user in - _dtaas.toml_ are not in use, and are not necessary - to fill in. These emails must be configured manually - for each user in the - deploy/docker/conf.server files and the _traefik-forward-auth_ - container must be restarted. This is done as follows: +2. This brings up the containers, without the AuthMS authentication. -- Go to the _docker_ directory + - Currently the _email_ fields for each user in + _dtaas.toml_ are not in use, and are not necessary + to fill in. These emails must be configured manually + for each user in the + deploy/docker/conf.server files and the _traefik-forward-auth_ + container must be restarted. This is done as follows: -```bash -cd /deploy/docker -``` + - Go to the _docker_ directory -- Add three lines to the `conf.server` file + ```bash + cd /deploy/docker + ``` -```txt -rule.onlyu3.action=auth -rule.onlyu3.rule=PathPrefix(`/user3`) -rule.onlyu3.whitelist = user3@emailservice.com -``` + - Add three lines to the `conf.server` file -Run the appropritate command for a server installation: + ```txt + rule.onlyu3.action=auth + rule.onlyu3.rule=PathPrefix(`/user3`) + rule.onlyu3.whitelist = user3@emailservice.com + ``` -```bash -docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth -``` + Run the appropritate command for a server installation: + + ```bash + docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth + ``` -The new users are now added to the DTaaS -instance, with authorization enabled. + The new users are now added to the DTaaS + instance, with authorization enabled. ### Delete users diff --git a/docs/admin/servers/auth.md b/docs/admin/servers/auth.md index 9cbf36905..b09a7094c 100644 --- a/docs/admin/servers/auth.md +++ b/docs/admin/servers/auth.md @@ -143,6 +143,15 @@ account should be included in the whitelist. This restricts access of the resource, allowing only users mentioned in the whitelist. +## User management + +DTaaS provides an easy way to add +and remove additional users from your +DTaaS instance. + +All such user management can be +done via the [DTaaS CLI](../cli.md) + ## Limitation The rules in _conf.*_ file are not dynamically loaded into @@ -153,3 +162,15 @@ All the existing user sessions get invalidated when the **traefik-forward-auth** restarts. Use a simple command on the terminal. + +- For a local instance: + +```bash +docker compose -f compose.server.yml --env-file .env up -d --force-recreate traefik-forward-auth +``` + +- For a server instance: + +```bash +docker compose -f compose.server.yml --env-file .env.server up -d --force-recreate traefik-forward-auth +``` diff --git a/docs/developer/oauth/AUTHMS.drawio b/docs/developer/oauth/AUTHMS.drawio new file mode 100644 index 000000000..63b42da4b --- /dev/null +++ b/docs/developer/oauth/AUTHMS.drawio @@ -0,0 +1,337 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/mkdocs-github.yml b/mkdocs-github.yml index 58d36cede..22deecdd6 100644 --- a/mkdocs-github.yml +++ b/mkdocs-github.yml @@ -77,7 +77,6 @@ nav: - Client: developer/client/client.md - Library Microservice: developer/servers/lib/lib-ms.md - Testing: developer/testing/intro.md - - Publish NPM Packages: developer/npm-packages.md - Bugs: bugs.md - Thanks: thanks.md - License: diff --git a/mkdocs.yml b/mkdocs.yml index 083354cc6..621d3052e 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,7 +77,6 @@ nav: - Client: developer/client/client.md - Library Microservice: developer/servers/lib/lib-ms.md - Testing: developer/testing/intro.md - - Publish NPM Packages: developer/npm-packages.md - Bugs: bugs.md - Thanks: thanks.md - License: