diff --git a/docs/admin/docker/README.md b/docs/admin/docker/README.md deleted file mode 100644 index 2bc946a44..000000000 --- a/docs/admin/docker/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# Install DTaaS using Docker - -This guide explains how to install the docker-based version -of DTaaS software. - -## Prerequisites - -**[Docker](https://www.docker.com/)** - It is important to have docker installed on your system/ server. We highly recommend using [Docker Desktop](https://www.docker.com/products/docker-desktop/). - -**[Gitlab Instance](https://about.gitlab.com/install/)** - DTaaS Authorization uses Gitlab OAuth2.0 authentication. Thus, to enable user authentication and authorization for your DTaaS instance, you will need a Gitlab Instance. You can bring up a private instance (recommended), or you can use [gitlab.com](www.gitlab.com) itself. - -## Steps - -### Clone the DTaaS repository: - -```bash -git clone https://github.com/INTO-CPS-Association/DTaaS.git -``` - -### Setup Gitlab Applications - -Refer to [Gitlab Application Setup Documentation](https://github.com/into-cps-association/dtaas/docs/admin/docker/gitlab.md). - -### Set the Client env file - -Refer to the [Client Setup Documentation](https://github.com/into-cps-association/dtaas/docs/admin/docker/client.md). - -### Set the environment variables - -- Switch to the docker directory: - -``` -cd /docker -``` - -- Setup the _.env_ file : This file contains - variables that need to be set to your specific - use case. - - | URL Path | Example |Access Granted to | - |:------------|:---------------|:---------------| - | DTAAS_DIR | '/home/Desktop/DTaaS' | Full path to the DTaaS directory. This is an absolute path with no trailing slash. | - | SERVER_DNS | _foo.com_ or _localhost_ | The server DNS, if you are deploying with a dedicated server. Remember not use http(s) at the beginning of the DNS string | - | OAUTH_URL | _gitlab.foo.com_ | The URL of your Gitlab instance | - | CLIENT_ID | 'xx' | The ID of your OAuth application | - | CLIENT_SECRET | 'xx' | The Secret of your OAuth application | - | OAUTH_SECRET | 'random-secret-string' | Any private random string | - | username1 | 'user1' | The gitlab instance username of a user of DTaaS | - | username2 | 'user2' | The gitlab instance username of a user of DTaaS | - | CLIENT_CONFIG | '/Users//DTaaS/deploy/config/client/env.js' | Full path to env.js file for client | - diff --git a/docs/admin/docker/client.md b/docs/admin/docker/client.md deleted file mode 100644 index cb32da821..000000000 --- a/docs/admin/docker/client.md +++ /dev/null @@ -1,77 +0,0 @@ -# Client Environment Setup - -The DTaaS Client website requires certain environment variables to be hosted. -These are set in a _.js_ file. You can find and use such files given in -_/deploy/config/client_ directory. - -See the definitions and examples below: - -```js -if (typeof window !== 'undefined') { -window.env = { - REACT_APP_ENVIRONMENT: "prod | dev", - REACT_APP_URL: "URL for the gateway", - REACT_APP_URL_BASENAME: "Base URL for the client website"(optional), - REACT_APP_URL_DTLINK: "Endpoint for the Digital Twin", - REACT_APP_URL_LIBLINK: "Endpoint for the Library Assets", - REACT_APP_WORKBENCHLINK_VNCDESKTOP: "Endpoint for the VNC Desktop link", - REACT_APP_WORKBENCHLINK_VSCODE: "Endpoint for the VS Code link", - REACT_APP_WORKBENCHLINK_JUPYTERLAB: "Endpoint for the Jupyter Lab link", - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: - "Endpoint for the Jupyter Notebook link", - REACT_APP_CLIENT_ID: 'AppID genereated by the gitlab OAuth provider', - REACT_APP_AUTH_AUTHORITY: 'URL of the private gitlab instance', - REACT_APP_REDIRECT_URI: 'URL of the homepage for the logged in users of the website', - REACT_APP_LOGOUT_REDIRECT_URI: 'URL of the homepage for the anonymous users of the website', - REACT_APP_GITLAB_SCOPES: 'OAuth scopes. These should match with the scopes set in gitlab OAuth provider', -}; -}; - -// Example values with no base URL. Trailing and ending slashes are optional. -if (typeof window !== 'undefined') { -window.env = { - REACT_APP_ENVIRONMENT: 'prod', - REACT_APP_URL: 'https://foo.com/', - REACT_APP_URL_BASENAME: '', - REACT_APP_URL_DTLINK: '/lab', - REACT_APP_URL_LIBLINK: '', - REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', - REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', - REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', - REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0', - REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', - REACT_APP_REDIRECT_URI: 'https://foo.com/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/', - REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', -}; -}; - - -// Example values with "bar" as basename URL. -//Trailing and ending slashes are optional. -if (typeof window !== 'undefined') { -window.env = { - REACT_APP_ENVIRONMENT: "dev", - REACT_APP_URL: 'https://foo.com/', - REACT_APP_URL_BASENAME: 'bar', - REACT_APP_URL_DTLINK: '/lab', - REACT_APP_URL_LIBLINK: '', - REACT_APP_WORKBENCHLINK_VNCDESKTOP: '/tools/vnc/?password=vncpassword', - REACT_APP_WORKBENCHLINK_VSCODE: '/tools/vscode/', - REACT_APP_WORKBENCHLINK_JUPYTERLAB: '/lab', - REACT_APP_WORKBENCHLINK_JUPYTERNOTEBOOK: '', - REACT_APP_CLIENT_ID: '934b98f03f1b6f743832b2840bf7cccaed93c3bfe579093dd0942a433691ccc0', - REACT_APP_AUTH_AUTHORITY: 'https://gitlab.foo.com/', - REACT_APP_REDIRECT_URI: 'https://foo.com/bar/Library', - REACT_APP_LOGOUT_REDIRECT_URI: 'https://foo.com/bar', - REACT_APP_GITLAB_SCOPES: 'openid profile read_user read_repository api', -}; -}; -``` -Setup the variables in an appropriate _.js_ file, and note down the path of -this file. This path needs to be set in the _/docker/.env_ file. -For a _localhost_ setup, you can directly use the sample -_/deploy/config/client/env.local.js_ to test your setup. However, -we recommend eventually creating a Gitlab client application, and -setting the *REACT_APP_CLIENT_ID* to the ID of this application. \ No newline at end of file diff --git a/docs/admin/docker/gitlab-app-1.png b/docs/admin/docker/gitlab-app-1.png deleted file mode 100644 index 8f15e0259..000000000 Binary files a/docs/admin/docker/gitlab-app-1.png and /dev/null differ diff --git a/docs/admin/docker/gitlab.md b/docs/admin/docker/gitlab.md deleted file mode 100644 index d8cda6954..000000000 --- a/docs/admin/docker/gitlab.md +++ /dev/null @@ -1,40 +0,0 @@ -# Gitlab Applications Setup - -## Gitlab Client Auth App - -- Login to your Gitlab instance as an admin. - Head over to the Admin area. - -- Go to the Applications tab. Click on "Add - a new application" on the top right. - - ![Add a new application](gitlab-app-1.png) - -- Write a suitable name for the application, - and add _{server-dns}/Library_ to the Redirect URI section. Keep the Trusted & Confidential - checkboxes unticked. - - ![](image.png) - -- Select the 5 required scopes: api, read_user, - read_repository, openid, profile. Click on - Save Application. - -- Copy the Application ID displayed, and click - on continue. Your application is now created. - -## Gitlab Server Auth App - -This step isn't required for a _localhost_ deploy which doesn't need user authentication. -Follow the steps if you require user authentication. - -- Follow similar steps as the previous section - to create a new Gitlab application. - -- Give this application a unique name, and add - *{server_dns}/_oauth* to the Redirect URI section. Keep the Trusted & Confidential - checkboxes unticked. - -- Select the read_user scope. Click on Save - Application. Note down both the Application ID, - and Secret shown. Your application is now created. diff --git a/docs/admin/docker/image.png b/docs/admin/docker/image.png deleted file mode 100644 index 79b37c9c8..000000000 Binary files a/docs/admin/docker/image.png and /dev/null differ diff --git a/docs/admin/host.md b/docs/admin/host.md index c82a9502e..a2be6516d 100644 --- a/docs/admin/host.md +++ b/docs/admin/host.md @@ -17,10 +17,27 @@ In the new application configuration, there are two OAuth2 applications. The installation requirements to run this docker version of the DTaaS are: -- DNS name for the server -- docker with compose plugin -- User accounts on a gitlab instance -- OAuth2 application registrations +### Docker with Compose Plugin + +[Docker](https://www.docker.com/)** - It is important to have docker installed on your system/ server. We highly recommend using [Docker Desktop](https://www.docker.com/products/docker-desktop/). + +### Domain name + +The DTaaS software is a web application and is preferably hosted +on a server with a domain name like _foo.com_. +However, it is possible to install the software on your computer +and use access it at _localhost_. + +### Reverse Proxy + +The installation setup recommends that the _foo.com_ server is behind a reverse +proxy / load balancer that provides https termination. You can still use +the DTaaS software even if you do not have this reverse proxy. + +### OAuth Provider + +**[Gitlab Instance](https://about.gitlab.com/install/)** - DTaaS Authorization uses Gitlab OAuth2.0 authentication. Thus, to enable user authentication and authorization for your DTaaS instance, you will need a Gitlab Instance. You can bring up a private instance (recommended), or you can use [gitlab.com](www.gitlab.com) itself. + ### Create User Accounts diff --git a/docs/developer/docker/docker.md b/docs/developer/docker/docker.md new file mode 100644 index 000000000..9e14d5ba2 --- /dev/null +++ b/docs/developer/docker/docker.md @@ -0,0 +1,95 @@ +# Docker workflow for DTaaS + +This readme will explain the building and use of different docker files +for use in development and installation of the DTaaS software. + +**NOTE**: A local docker and docker-compose installation is a pre-requisite +for using docker workflows. + +## Folder Structure + +There are two dockerfiles for building the containers: + +- **client.dockerfile**: Dockerfile for building + the client application container. +- **libms.dockerfile**: Dockerfile for building the library microservice container. + +There is a specific compose file for development: + +- **compose.dev.yml:** Docker Compose configuration for development environment. + +## Build and Publish Docker Images + +### Users + +Build and publish the docker images. This step is required only for +the publication of images to Docker Hub. This publishing step is managed +only by project maintainers. Regular users can skip this step. + +```sh +docker login -u -p +docker build -t intocps/libms:latest -f ./docker/libms.dockerfile . +docker tag intocps/libms:latest intocps/libms:version +docker push intocps/libms:latest +docker push intocps/libms:version + +docker build -t intocps/dtaas-web:latest -f ./docker/client.dockerfile . +docker tag intocps/dtaas-web:latest intocps/dtaas-web:version +docker push intocps/dtaas-web:latest +docker push intocps/dtaas-web:version +``` + +To tag version 0.3.1 for example, use + +```sh +docker tag intocps/dtaas-web:latest intocps/dtaas-web:0.3.1 +``` + +### Developers + +Use of docker images is handy for developers as well. It is suggested +that developers build the required images locally on their computer and +use them for development purposes. The images can be built using + +```sh +docker-compose -f compose.dev.yml build +``` + +## Running Docker Containers + +Follow these steps to use the application with docker. + +The DTaaS application requires multiple configuration files. The list of +configuration files to be modified are given for each scenario. + +### Development Environment + +This scenario is for software developers. + +The configuration files to be updated are: + +1. docker/dev/.env + please see [docker README](../README.md) for help + with updating this config file) +1. docker/conf.local + please see [server docs](../docs/admin/servers/auth.md) for help + with updating this config file) +1. client/config/local.js + please see [client config](../../docs/admin/client/CLIENT.md) for help + with updating this config file) +1. servers/lib/config/.env.default + please see [lib config](../../docs/admin/servers/lib/LIB-MS.md) for help + with updating this config file) + +The docker commands need to be executed from this directory (`docker/dev`). +The relevant docker commands are: + +```bash +docker-compose -f compose.dev.yml up -d #start the application +docker-compose -f compose.dev.yml down #terminate the application +``` + +### Access the Application + +You should access the application through the PORT mapped to the Traefik container. +e.g. `localhost` diff --git a/docs/developer/docker/oauth.md b/docs/developer/docker/oauth.md new file mode 100644 index 000000000..c5727cba6 --- /dev/null +++ b/docs/developer/docker/oauth.md @@ -0,0 +1,146 @@ +# Traefik Forward Auth + +The traefik gateway is used to serve the DTaaS. All the services +provided as part of the application are secured at the traefik gateway. +The security is based on [Traefik forward-auth](https://github.com/thomseddon/traefik-forward-auth). + +An illustration of the docker containers used and the authorization +setup is shown here. + +![traefik oauth](./traefik-oauth.png) + +The **traefik forward-auth** can use any OAuth2 provider, but within the DTaaS +gitlab is used as authorization provider. +You will use +the OAuth the web / server application +authorization flow. + +Here are the steps to get started: + +**1. Choose Your GitLab Server:** + +- You need to set up OAuth authorization on a GitLab server. + The commercial gitlab.com is not suitable for multi-user authorization + (DTaaS requires this), so you'll need an on-premise GitLab instance. +- You can use + [GitLab Omnibus Docker for this purpose](https://docs.gitlab.com/ee/install/docker.html). +- Configure the OAuth application as an + [instance-wide authorization type](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-an-instance-wide-application). + Select option to generate client secret and also selection option + for trusted application. + +**2. Determine Your Website's Hostname:** + +- Before setting up OAuth on GitLab, decide on the hostname for your website. + It's recommended to use a self-hosted GitLab instance, which you will use in + other parts of the DTaaS application. + +**3. Callback and Logout URLs:** + +- For the web / server authorization flow to function correctly, you need two URLs: + a callback URL and a logout URL. + - The callback URL informs the OAuth provider of the + page where + signed-in users should be redirected. It is the landing + homepage of the DTaaS application. + (either or ) + - The logout URL is the URL for signout of gitlab and clear authorization + within traefik-forward auth. + (either or ). + The logout URL is to help users logout of traefik forward-auth. The logout + URL should not be entered into Gitlab OAuth application setup. + +**4. OAuth Application Creation:** + +- During the creation of the OAuth application on GitLab, you need to specify + the scope. Choose _read_user_ scope. + +**5. Application Credentials:** + +- After successfully creating the OAuth application, GitLab generates + an _application ID_ and _client secret_. + Both these values are long string of HEX values that you will need for + your configuration files. + +**6. Required Information from OAuth Application:** + +- You will need the following information from the OAuth application + registered on GitLab: + +|GitLab Variable Name|Variable Name in .env of docker compose file |Default Value| +|---|---|---| +|OAuth Provider|OAUTH_URL|[https://gitlab.foo.com/](https://gitlab.foo.com/)| +|Application ID|CLIENT_ID| _xx_ | +|Application Secret|CLIENT_SECRET| _xx_ | +|Callback URL|(to be directly entered in Gitlab OAuth registration)|| +|Forward-auth secret|OAUTH_SECRET|_random-secret-string_ (password for forward-auth, can be changed to your preferred string) | +|Scopes| read_user || + +## Development Environment + +The development environment does not required traefik forward-auth. + +## Configure Authorization Rules for Traefik Forward-Auth + +The Traefik forward-auth microservices requires configuration rules to manage +authorization 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 Authorization + +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(`/common`) +``` + +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 +restart of **traefik-forward-auth** for the changes to take effect. +All the existing user sessions get invalidated when +the **traefik-forward-auth** restarts. + +Use a simple command on the terminal. \ No newline at end of file diff --git a/docs/developer/docker/traefik-oauth.png b/docs/developer/docker/traefik-oauth.png new file mode 100644 index 000000000..95a7ae391 Binary files /dev/null and b/docs/developer/docker/traefik-oauth.png differ diff --git a/docs/user/website/gitlab-auth-1.png b/docs/user/website/gitlab-auth-1.png new file mode 100644 index 000000000..6907a12d1 Binary files /dev/null and b/docs/user/website/gitlab-auth-1.png differ diff --git a/docs/user/website/gitlab-auth-2.png b/docs/user/website/gitlab-auth-2.png new file mode 100644 index 000000000..2d47136ad Binary files /dev/null and b/docs/user/website/gitlab-auth-2.png differ diff --git a/docs/user/website/gitlab-sso-3.png b/docs/user/website/gitlab-sso-3.png index e44dca11a..3a8d234cb 100755 Binary files a/docs/user/website/gitlab-sso-3.png and b/docs/user/website/gitlab-sso-3.png differ diff --git a/docs/user/website/index.md b/docs/user/website/index.md index 9ffbf4076..c23eca63c 100644 --- a/docs/user/website/index.md +++ b/docs/user/website/index.md @@ -3,38 +3,62 @@ This page contains a screenshot driven preview of the website serving the DTaaS software platform. -## Login to enter the DTaaS software platform +## Visit the DTaaS software instance -![Login](login.png) +Start off by simply visiting the website +of the DTaaS instance for which you are a user. -The screen presents with HTTP authorization form. You can enter the user -credentials. If the DTaaS is being served over HTTPS secure communication -protocol, the username and password are secure. +![Visit the URL](visit-dtaas-1.png) -## Start the Authorization +## Redirected to Authorization -You are now logged into the DTaaS server. The DTaaS uses third-party authorization +You will be redirected to the Gitlab +Authorization for DTaaS. + +![Gitlab Sign on](gitlab-auth-1.png) + +Enter your email/username and password. +If the email ID registered with DTaaS, is +the same as your Google Login email ID, you +can also opt to sign in using Google. + +You will be redirected to the OAuth +Application page. + +## Permit DTaaS Server to Use Gitlab + +![Server Auth Permission](gitlab-auth-2.png) + +Click on Authorize to allow the OAuth +application to access the information +connected to your Gitlab account. This +is a necessary step. + +You are now logged into the DTaaS server. +You will be redirected to the login page +of the DTaaS website. + +The DTaaS website uses +an additional layer of security - +the third-party authorization protocol known as [OAuth](https://auth0.com/docs/get-started/authorization-and-authorization-flow/authorization-code-flow-with-proof-key-for-code-exchange-pkce). This protocol provides secure access to a DTaaS installation if users have a working active accounts at the selected OAuth -service provider. The DTaaS uses Gitlab as OAuth provider. +service provider. This also uses Gitlab as OAuth provider. + ![Gitlab signin button](gitlab-sso-1.png) You can see the Gitlab signin button. A click on this button takes you to -Gitlab instance providing authorization for DTaaS. - -## Authorize at Gitlab - -The username and password authorization takes place on the gitlab website. -Enter your username and password in the login form. - -![Gitlab login form](gitlab-sso-2.png) +Gitlab instance providing authorization for DTaaS. You will not need to sign in to +Gitlab again, unless you have explicitly +logged out +of your Gitlab account. -## Permit DTaaS to Use Gitlab +## Permit DTaaS Website to Use Gitlab -The DTaaS application needs your permission to use your Gitlab account for +The DTaaS website needs your permission to use your Gitlab account for authorization. Click on **Authorize** button. ![Gitlab OAuth permission](gitlab-sso-3.png) diff --git a/docs/user/website/visit-dtaas-1.png b/docs/user/website/visit-dtaas-1.png new file mode 100644 index 000000000..59e8ec4d3 Binary files /dev/null and b/docs/user/website/visit-dtaas-1.png differ