diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 000000000..78cd9d8f5 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,35 @@ +cff-version: 1.2.0 +message: "If you use this software, please cite it as below." +authors: +- family-names: "Talasila" + given-names: "Prasad" + orcid: "https://orcid.org/0000-0002-8973-2640" +title: "Digital Twin as a Service" +version: 0.3.0 +date-released: 2023-11-08 +url: "https://github.com/into-cps-association/DTaaS" +preferred-citation: + type: article + authors: + - family-names: "Talasila" + given-names: "Prasad" + orcid: "https://orcid.org/0000-0002-8973-2640" + - family-names: "Gomes" + given-names: "Cláudio" + orcid: "https://orcid.org/0000-0000-0000-0000" + - family-names: "Mikkelsen" + given-names: "Peter Høgh" + orcid: "https://orcid.org/0000-0003-2321-758X" + - family-names: "Gil" + given-names: "Santiago" + orcid: "https://orcid.org/0000-0002-1789-531X" + - family-names: "Kamburjan" + given-names: "Eduard" + orcid: "https://orcid.org/0000-0002-0996-2543" + - family-names: "Larsen" + given-names: "Peter Gorm" + orcid: "https://orcid.org/0000-0002-4589-1500" + conference-paper: "The 2023 IEEE International Conference on Digital Twin" + month: 8 + title: "Digital Twin as a Service (DTaaS): A Platform for Digital Twin Developers and Users" + year: 2023 \ No newline at end of file diff --git a/docs/user/examples/examples.drawio b/docs/user/examples/examples.drawio index 91072df68..685b8c348 100755 --- a/docs/user/examples/examples.drawio +++ b/docs/user/examples/examples.drawio @@ -1,6 +1,6 @@ - + - + @@ -401,6 +401,319 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/user/examples/index.md b/docs/user/examples/index.md index 744715590..95fe9d98e 100644 --- a/docs/user/examples/index.md +++ b/docs/user/examples/index.md @@ -26,5 +26,6 @@ to use the examples in the following order. 1. [Water Tank Fault Injection](./water_tank_FI/README.md) 1. [Water Tank Model Swap](./water_tank_swap/README.md) 1. [Desktop Robotti and RabbitMQ](./drobotti-rmqfmu/README.md) +1. [Three Water Tanks with DT Manager Framework](./three-tank/README.md) :material-download: [DTaaS examples](https://github.com/INTO-CPS-Association/DTaaS-examples) diff --git a/docs/user/examples/three-tank/README.md b/docs/user/examples/three-tank/README.md new file mode 100644 index 000000000..b57feed5d --- /dev/null +++ b/docs/user/examples/three-tank/README.md @@ -0,0 +1,153 @@ +# Three-Tank System Digital Twin + +## Overview + +The three-tank system is a simple case study allows us to represent a system +that is composed of three individual components that are coupled in +a cascade as follows: The first tank is connected to the input of +the second tank, and the output of the second tank is connected to +the input of the third tank. + +![Three-tank graphical representation](./three-tank.png) + +This example contains only the simulated components for +demonstration purposes; therefore, there is no configuration for +the connection with the physical system. + +The three-tank system case study is managed using the ```DTManager```, +which is packed as a jar library in the tools, and run from a java main file. +The ```DTManager``` uses Maestro as a slave for co-simulation, +so it generates the output of the co-simulation. + +The main file can be changed according to the application scope, i.e., +the ```/workspace/examples/tools/three-tank/TankMain.java``` +can be manipulated to get a different result. + +The ```/workspace/examples/models/three-tank/``` folder contains +the ```Linear.fmu``` file, which is a non-realistic model for a tank +with input and output and the ```TankSystem.aasx``` file for +the schema representation with Asset Administration Shell. +The three instances use the same ```.fmu``` file and the same schema +due to being of the same object class. +The ```DTManager``` is in charge of reading the values from +the co-simulation output. + +## Example Structure + +![Three-tank system architecture with DT Manager](./dt-structure.png) + +## Digital Twin Configuration + +This example uses two models, two tools, one data, and one script. +The specific assets used are: + +| Asset Type | Names of Assets | Visibility | Reuse in Other Examples | +|:---|:---|:---|:---| +| Model | Linear.fmu | Private | No | +| | TankSystem.aasx | Private | No | +| Tool | DTManager-0.0.1-Maestro.jar (wraps Maestro) | Common | Yes | +| | maestro-2.3.0-jar-with-dependencies.jar (used by DTManager) | Common | Yes | +| | TankMain.java (main script) | Private | No | +| Data | outputs.csv | Private | No | + +This DT has multiple configuration files. The _coe.json_ and +_multimodel.json_ are used by Maestro tool. The _tank1.conf_, _tank2.conf_ +and _tank3.conf_ are the config files for three different instances of +one model (Linear.fmu). + +## Lifecycle Phases + +The lifecycles that are covered include: + +| Lifecycle Phase | Completed Tasks | +| --------- | ------- | +| Create | Installs Java Development Kit for Maestro tool | +| Execute | The DT Manager executes the three-tank digital twin and produces output in ```data/three-tank/output``` directory | +| Terminate | Terminating the background processes and cleaning up the output | + +## Run the example + +To run the example, change your present directory. + +```bash +cd /workspace/examples/digital twins/three-tank +``` + +If required, change the execute permission of lifecycle scripts +you need to execute, for example: + +```bash +chmod +x lifecycle/create +``` + +Now, run the following scripts: + +### Create + +Installs Open Java Development Kit 11 and pip dependencies. +Also creates ```DTManager``` tool (DTManager-0.0.1-Maestro.jar) from source code. + +```bash +lifecycle/create +``` + +### Execute + +Execute the three-tank digital twin using DTManager. DTManager in-turn runs +the co-simulation using Maestro. Generates the co-simulation output.csv file +at `/workspace/examples/data/three-tank/output`. + +```bash +lifecycle/execute +``` + +### Terminate + +Stops the Maestro running in the background. Also stops any other +jvm process started during **execute** phase. + +```bash +lifecycle/terminate +``` + +### Clean + +Removes the output generated during execute phase. + +```bash +lifecycle/terminate +``` + +## Examining the results + +Executing this Digital Twin will generate a co-simulation output, +but the results can also be monitored from updating +the```/workspace/examples/tools/three-tank/TankMain.java``` with +a specific set of ```getAttributeValue``` commands, such as shown in +the code. + +That main file enables the online execution of the Digital Twin and +its internal components. + +The output of the co-simulation is generated to +the ```/workspace/examples/data/three-tank/output``` folder. + +In the default example, the co-simulation is run for 10 seconds in +steps of 0.5 seconds. +This can be modified for a longer period and different step size. +The output stored in ```outputs.csv``` contains the level, in/out flow, +and leak values. + +No data from the physical twin are generated/used. + +## References + +More information about the DT Manager is available at: + +```txt +D. Lehner, S. Gil, P. H. Mikkelsen, P. G. Larsen and M. Wimmer, +"An Architectural Extension for Digital Twin Platforms to Leverage +Behavioral Models," 2023 IEEE 19th International Conference on +Automation Science and Engineering (CASE), Auckland, New Zealand, +2023, pp. 1-8, doi: 10.1109/CASE56687.2023.10260417. +``` diff --git a/docs/user/examples/three-tank/dt-structure.png b/docs/user/examples/three-tank/dt-structure.png new file mode 100644 index 000000000..b0604c1bb Binary files /dev/null and b/docs/user/examples/three-tank/dt-structure.png differ diff --git a/docs/user/examples/three-tank/three-tank.png b/docs/user/examples/three-tank/three-tank.png new file mode 100644 index 000000000..6091379ce Binary files /dev/null and b/docs/user/examples/three-tank/three-tank.png differ diff --git a/mkdocs-github.yml b/mkdocs-github.yml index 3deee0e89..28e962a61 100644 --- a/mkdocs-github.yml +++ b/mkdocs-github.yml @@ -54,6 +54,7 @@ nav: - Water Tank Fault Injection: user/examples/water_tank_FI/README.md - Water Tank Model Swap: user/examples/water_tank_swap/README.md - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md + - Three Water Tanks: user/examples/three-tank/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/mkdocs.yml b/mkdocs.yml index b7a8809d5..b6b5035aa 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,6 +54,7 @@ nav: - Water Tank Fault Injection: user/examples/water_tank_FI/README.md - Water Tank Model Swap: user/examples/water_tank_swap/README.md - Desktop Robotti and RabbitMQ: user/examples/drobotti-rmqfmu/README.md + - Three Water Tanks: user/examples/three-tank/README.md - Codebase: https://github.com/INTO-CPS-Association/DTaaS-examples - FAQ: FAQ.md - Developer: diff --git a/script/docs.sh b/script/docs.sh index 4978519a6..6058537a3 100755 --- a/script/docs.sh +++ b/script/docs.sh @@ -50,4 +50,4 @@ mv site/index.html . rm -rf site git add . -git commit -m "docs for ${COMMIT_HASH} commit" \ No newline at end of file +git commit --no-verify -m "docs for ${COMMIT_HASH} commit" \ No newline at end of file diff --git a/servers/auth/README.md b/servers/auth/README.md index 3019f2ac4..a96304a5b 100644 --- a/servers/auth/README.md +++ b/servers/auth/README.md @@ -12,6 +12,88 @@ Within docker, images of the following container are used: This is an example version of any microservice that should lie behind the OAuth. +## Ready Reckoner + +You need an +[instance-wide authentication type](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-an-instance-wide-application) +on Gitlab. If you use as your authentication provider, +you can only authenticate a single user. For the table below, +has been used as example URL of OAuth provider + +| Gitlab Variable Name | Variable name in compose.yml | Default Value | +| :------------------- | :------------------------------------ | :----------------------------------------| +| OAuth Provider | PROVIDERS_GENERIC_OAUTH_AUTH_URL | | +| | PROVIDERS_GENERIC_OAUTH_TOKEN_URL | | +| | PROVIDERS_GENERIC_OAUTH_USER_URL | | +| Application ID | PROVIDERS_GENERIC_OAUTH_CLIENT_ID | | +| Secret | PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET | | +| Callback URL | | | +| Scopes | | read_user | +| Logout URL for demo | | | +|| + +## Configure Authentication Rules + +The Traefik forward auth microservices requires configuration rules to manage +authentication for different URL paths. +The `conf` file can be used to configure the specific rules. +There are broadly three kinds of URLs: + +### Public Path Without Authentication + +To setup a public page, an example is shown below. + +```text +rule.noauth.action=allow +rule.noauth.rule=Path(`/public`) +``` + +Here, 'noauth' is the rule name, and should be changed to suit rule use. +Rule names should be unique for each rule. +The 'action' property is set to "allow" to make the resource public. +The 'rule' property defines the path/route to reach the resource. + +### Common to All Users + +To setup a common page that requires Gitlab OAuth, +but is available to all users of the Gitlab instance: + +```text +rule.all.action=auth +rule.all.rule=Path(`/os`) +``` + +The 'action' property is set to "auth", to enable Gitlab +OAuth before the resource can be accessed. + +### Selective Access + +Selective Access refers to the scenario of allowing access to a URL path +for a few users. To setup selective access to a page: + +```text +rule.onlyu1.action=auth +rule.onlyu1.rule=Path(`/user1`) +rule.onlyu1.whitelist = user1@localhost +``` + +The 'whitelist' property of a rule defines a comma separated list +of email IDs that are allowed to access the resource. +While signing in users can sign in with either their username or email ID +as usual, but the email ID corresponding to the +account should be included in the whitelist. + +This restricts access of the resource, +allowing only users mentioned in the whitelist. + +### Limitation + +The rules in _conf_ file are not dynamically loaded into +the **traefik-forward-auth** microservice. Any change in the _conf_ file requires +retart of **traefik-forward-auth** for the changes to take effect. +All the existing user sessions get invalidated when +the **traefik-forward-auth** restarts. + ## Run the example You should have docker setup to be able to run this. @@ -22,36 +104,50 @@ Docker Desktop for Linux is preferred. - This service works based on 2 files, servers/auth/compose.yml and servers/auth/conf. - In the compose.yml, under the traefik-forward-auth service volumes, - please replace the correct file path for - servers/auth/conf file (on the left hand side of ':'). -- Also fill in the CLIENT_ID, CLIENT_SECRET fields. + please replace the correct absolute file path for + servers/auth/conf file in the volume mapping of + **traefik-forward-auth** container.. +- Also fill in the OAUTH details in compose.yml as per the table given above. - No other changes should be made to compose.yml. -- Run: +- Finally, run: -```bash -docker compose up -d --remove-orphans -``` + ```bash + docker compose up -d --remove-orphans + ``` -The microservice is now running. +The microservices start up and provide access to +the following URL paths. + +| URL Path | Access Granted to | +|:------------|:---------------| +| | everyone including unauthenticated users | +| | user1 and user2 | +| | user1 | +| | user2 | +|| ## View the example -- Try heading over to . - This is a public, accessible to all, copy of the webserver. - It still passes through the AuthServer (traefik-forward-auth), - however this Path is set to allow access to all, - instead of any authentication. - You should be able to see this page with any email ID/ even without signing in. +### Public + +Try heading over to . +This is a public, accessible to all, copy of the webserver. +It still passes through the AuthServer (traefik-forward-auth), +however this Path is set to allow access to all, +instead of any authentication. +You should be able to see this page without even signing in. + +### Authenticated users - Head over to . This page requires Gitlab OAuth and is not public. - You will be redirected to Gitlab. Sign in if you aren't already signed in. - user1 (user1@localhost) /user2 (user2@localhost) + _user1 (user1@localhost) / user2 (user2@localhost)_ accounts can be used to sign into the Gitlab instance. - On Gitlab you will be asked to authorize sharing some - account data with a "AuthTry" application. - Click on the "Authorize" button. + account data for the application. + Click on the **Authorize** button. - You will be redirect to the whoami server page showing information about your system. Any account that passes the Gitlab OAuth or @@ -92,51 +188,8 @@ The microservice is now running. - You will automatically be able to see this page, without any Auth process/ new access tokens. - This page is still visible even though you have logged out of Gitlab. - This is because you haven't logged out of the OAuth. - -## Configuration - -The conf file can be used to configure the specific rules. - -- To setup a public page, an example is shown below. - - ```text - rule.noauth.action=allow - rule.noauth.rule=Path(`/public`) - ``` - - Here, 'noauth' is the rule name, and should be changed to suit rule use. - Rule names should be unique for each rule. - The 'action' property is set to "allow" to make the resource public. - The 'rule' property defines the path/route to reach the resource. - -- To setup a common page that requires Gitlab OAuth, - but is available to all users of the Gitlab instance: - - ```text - rule.all.action=auth - rule.all.rule=Path(`/os`) - ``` - - The 'action' property is set to "auth", to enable Gitlab - OAuth before the resource can be accessed. - -- To setup selective access to a page: - - ```text - rule.onlyu1.action=auth - rule.onlyu1.rule=Path(`/user1`) - rule.onlyu1.whitelist = user1@localhost - ``` - - The 'whitelist' property of a rule defines a comma separated list - of email IDs that are allowed to access the resource. - While signing in users can sign in with either their username or email ID - as usual, but the email ID corresponding to the - account should be included in the whitelist. - - This restricts access of the resource, - allowing only users mentioned in the whitelist. + This is because you haven't logged out of the OAuth session + managed by traefik forward auth. ## Adding/Removing a service @@ -226,15 +279,14 @@ access to the dummy service. behind this Authentication, only accesible through the Traefik reverse proxy. - Dynamic rule addition is also an open issue. -- Please refer to - . - This microservice is based on this repository. +- The Traefik Forward Auth code is available + [online](https://github.com/thomseddon/traefik-forward-auth). ## Disclaimer -The server currently has a 8 second timeout on requests. -This might cause some requests to timeout, -usually due to internet connectivity -and recieve a 503 - Service Unavailable. -Please try again in case this happens. -This is an open issue. +There is an 8 second timeout on OAuth requests sent to Gitlab. +If the OAuth signin process is not complete before eight seconds, +Gitlab cancels the signin request and gives +_503 - Service Unavailable_ message. +The timelimit variable has not been found in gitlab.rb config file; +timelimit is probably built into Gitlab code. diff --git a/servers/auth/compose.yml b/servers/auth/compose.yml index 20de649d2..dd120e2d3 100644 --- a/servers/auth/compose.yml +++ b/servers/auth/compose.yml @@ -53,9 +53,9 @@ services: - /home/astitva/Desktop/DTaaS/servers/auth/conf:/rules environment: - DEFAULT_PROVIDER=generic-oauth - - PROVIDERS_GENERIC_OAUTH_AUTH_URL=https://maestro.cps.digit.au.dk/oauth/authorize - - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=https://maestro.cps.digit.au.dk/oauth/token - - PROVIDERS_GENERIC_OAUTH_USER_URL=https://maestro.cps.digit.au.dk/api/v4/user + - PROVIDERS_GENERIC_OAUTH_AUTH_URL=https://gitlab.foo.com/oauth/authorize + - PROVIDERS_GENERIC_OAUTH_TOKEN_URL=https://gitlab.foo.com/oauth/token + - PROVIDERS_GENERIC_OAUTH_USER_URL=https://gitlab.foo.com/api/v4/user - PROVIDERS_GENERIC_OAUTH_CLIENT_ID=xxxx - PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET=xxxx - PROVIDERS_GENERIC_OAUTH_SCOPE=read_user