From f09911dcb590164f12ab5c21243d54ecb70b64c0 Mon Sep 17 00:00:00 2001
From: Alessandro Cerioni <acerioni@grandlyon.com>
Date: Thu, 5 Dec 2019 15:21:13 +0100
Subject: [PATCH] Yet another update!

- Improved skeleton
- Improved Authentication Service documentation
---
 docs/components/core/legacy-auth.md           |  1 +
 .../middlewares/legacy-auth-middleware.md     | 12 ++++
 .../off-the-shelf-apps/api-gateway.md         |  6 ++
 docs/components/services/authentication.md    | 63 +++++++++++--------
 .../services/legacy-auth-middleware.md        | 42 -------------
 docs/components/specific-apps/admin-gui.md    |  6 +-
 docs/components/specific-apps/web-app.md      |  4 +-
 docs/index.md                                 |  3 +-
 .../accessibility.md                          |  4 +-
 docs/miscellaneous/nestjs-micro-services.md   | 13 ++++
 docs/miscellaneous/security.md                |  6 ++
 docs/overview/index.md                        | 15 +++--
 mkdocs.yml                                    | 25 +++++---
 13 files changed, 111 insertions(+), 89 deletions(-)
 create mode 100644 docs/components/core/legacy-auth.md
 create mode 100644 docs/components/middlewares/legacy-auth-middleware.md
 delete mode 100644 docs/components/services/legacy-auth-middleware.md
 rename docs/{accessibility => miscellaneous}/accessibility.md (97%)
 create mode 100644 docs/miscellaneous/nestjs-micro-services.md
 create mode 100644 docs/miscellaneous/security.md

diff --git a/docs/components/core/legacy-auth.md b/docs/components/core/legacy-auth.md
new file mode 100644
index 0000000..b641de0
--- /dev/null
+++ b/docs/components/core/legacy-auth.md
@@ -0,0 +1 @@
+# Legacy AUTH
diff --git a/docs/components/middlewares/legacy-auth-middleware.md b/docs/components/middlewares/legacy-auth-middleware.md
new file mode 100644
index 0000000..41e6048
--- /dev/null
+++ b/docs/components/middlewares/legacy-auth-middleware.md
@@ -0,0 +1,12 @@
+
+# Legacy Authentication Middleware
+
+## Features
+
+## Dependencies
+
+## Endpoints
+
+## Implementation
+
+The service is implemented using the [NestJS](https://nestjs.com/) framework. We refer the reader to the [NestJS-based micro-services](../../miscellaneous/nestjs-micro-services.md) page for further details concerning the latter framework and the features it provides.
diff --git a/docs/components/off-the-shelf-apps/api-gateway.md b/docs/components/off-the-shelf-apps/api-gateway.md
index e69de29..cb6977b 100644
--- a/docs/components/off-the-shelf-apps/api-gateway.md
+++ b/docs/components/off-the-shelf-apps/api-gateway.md
@@ -0,0 +1,6 @@
+# API Gateway
+
+### TODO
+
+* Explain the reasons why Kong was chosen
+* Explain which features are used, in particular the AUTHN layer
diff --git a/docs/components/services/authentication.md b/docs/components/services/authentication.md
index 3dc3315..0c17ed4 100644
--- a/docs/components/services/authentication.md
+++ b/docs/components/services/authentication.md
@@ -1,46 +1,55 @@
-
 # Authentication service
 
-## What it does
-
-This service provides two endpoints relative to the authentication of a user:
+## Features
 
-* A login endpoint that will allow a user to authenticate itself using its credentials (a username and an encrypted password). When the credentials are correct it will generate a JSON Web Token and set it as a cookie for the domain name specified in the configuration of the service. An xsrf token will also be returned in the response. Both the cookie and the xsrf token will be needed to make authenticated calls later.
+This service allows users to login to / logout from the Web Portal. Establishing an authenticated session is a prerequisite for managing user rights to restricted-access resources.
 
-* A logout endpoint, which signs out the user by deprecating the cookie set with the login endpoint.
+## Dependencies
 
-This service also provides endpoints to retrieve and update a user profile.
+The service relies on
 
-## How it works
+* the [API Gateway](../off-the-shelf-apps/api-gateway.md), in particular its Admin API;
+* external identity providers, which actually store user profiles and can verify user credentials. Despite being designed to potentially support different identity providers, in the present implementation only the [Legacy AUTH Identity Provider](../core/legacy-auth.md) is supported. A [middleware](../middlewares/legacy-auth-middleware.md) was developed, so as to facilitate the interaction between this service and the Legacy AUTH Identity Provider.
 
 ![authentication-service](../../assets/authentication-service.png)
 
-The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. It depends on two other services:
 
-* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
-* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens
+## Endpoints
+
+This service provides five **endpoints**:
+
+1. A **login** endpoint per identity provider (just one in the present implementation, namely `/login/legacy`), allowing users to authenticate using a username/password pair. In case the identity provider confirms that user credentials are correct, a couple of cookies are set:
+    1. an HTTP-only cookie including an **access token**, including in turn a JSON Web Token (JWT), signed by the API Gateway, namely Kong.
+    2. a cookie including an **XSRF token** (generated as a version 4 UUID).
+
 
-## API documentation
+    Both the access token and the XSRF token are needed to issue authenticated requests. We refer the reader to a [dedicated page](../../miscellaneous/security.md) for further information about security.
 
-NestJS provides a [swagger module](https://docs.nestjs.com/recipes/swagger) that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`.
+2. A **logout** endpoint, `/logout`, which signs out the user by deprecating the cookie set by the login endpoint.
 
-## Service health
+3. An **user info** endpoint, allowing one to fetch an user profile.
 
-NestJS provides a [health module](https://github.com/nestjs/terminus) based on Terminus, that gives you the opportunity to declare predefined or custom health indicators. It exposes the health status of the service at `/health`.  
-This service will return a `200` http status code when all indicators are healthy. Otherwise it will return a `503` http status code. 
+4. An **user info update** endpoint, `/user/update` allowing one to update an user profile.
 
-For this service we declared two health indicators that verify that: 
-* the Kong API gateway is up
-* the legacy authentication middleware is up
+5. An **health** endpoint, `/health`, returning a `200` HTTP Status Code in case the service is healthy, `503` in the opposite case. For this service to be healthy, two conditions must be fulfilled:
+    * the [API Gateway](../off-the-shelf-apps/api-gateway.md) must be up;
+    * the [Legacy AUTH Middleware](../middlewares/legacy-auth-middleware.md) must be up.
 
-## Stats
 
-We are using a Node module called [swagger-stats](http://swaggerstats.io/).  
-It traces API calls, monitors API performance and usage statistics. It exposes the metrics in different formats, such as Prometheus format, so you may use Prometheus and Graphana for API monitoring and alerting.  
-Those metrics are available at `/swagger-stats/metrics`.
+## Implementation
 
-For more information about this module, visit the [official swagger-stat page](http://swaggerstats.io/docs.html).
+The service is implemented using the [NestJS](https://nestjs.com/) framework. We refer the reader to the [NestJS-based micro-services](../../miscellaneous/nestjs-micro-services.md) page for further details concerning the latter framework and the features it provides.
 
-## Docker
-It is possible to run this service using Docker containers, using the `docker-compose.yml` and `Dockerfile` files.  
-For more information, refer to the project [authentication-service][add a link]
\ No newline at end of file
+### TO FURTHER DEVELOP
+
+* What's the interplay between this service and Kong? Let's provide sequence diagrams!
+* How is the access token generated and signed?
+* What is the difference between the cookie expiration time and that of the JWT for the Legacy Middleware?
+
+
+<!-- ## How it works
+
+The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. It depends on two other services:
+
+* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
+* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens -->
diff --git a/docs/components/services/legacy-auth-middleware.md b/docs/components/services/legacy-auth-middleware.md
deleted file mode 100644
index a4d7c1d..0000000
--- a/docs/components/services/legacy-auth-middleware.md
+++ /dev/null
@@ -1,42 +0,0 @@
-
-# Legacy Authentication middleware
-
-## What it does
-
-
-
-## How it works
-
-<!-- ![legacy-auth-middleware-service](../../assets/legacy-auth-middleware-service.png) -->
-
-The entrypoint of the service is a REST API provided by a [NestJS](https://github.com/nestjs/nest) application. 
-
-<!-- It depends on two other services:
-
-* The Legacy Authentication Middleware to verify the identity of the user and retrieve its profile (called through our api gateway: Kong)
-* The Admin API of Kong to get the user specific secrets in order to sign the JSON Web Tokens -->
-
-## API documentation
-
-NestJS provides a [swagger module](https://docs.nestjs.com/recipes/swagger) that can be easily integrated. Using specific annotations alongside your endpoints declaration, this module will automatically generates a swagger documentation, reachable at `/api-doc`.
-
-## Service health
-
-NestJS provides a [health module](https://github.com/nestjs/terminus) based on Terminus, that gives you the opportunity to declare predefined or custom health indicators. It exposes the health status of the service at `/health`.  
-This service will return a `200` http status code when all indicators are healthy. Otherwise it will return a `503` http status code. 
-
-<!-- For this service we declared two health indicators that verify that: 
-* the Kong API gateway is up
-* the legacy authentication middleware is up -->
-
-## Stats
-
-We are using a Node module called [swagger-stats](http://swaggerstats.io/).  
-It traces API calls, monitors API performance and usage statistics. It exposes the metrics in different formats, such as Prometheus format, so you may use Prometheus and Graphana for API monitoring and alerting.  
-Those metrics are available at `/swagger-stats/metrics`.
-
-For more information about this module, visit the [official swagger-stat page](http://swaggerstats.io/docs.html).
-
-## Docker
-It is possible to run this service using Docker containers, using the `docker-compose.yml` and `Dockerfile` files.  
-For more information, refer to the project [legacy-auth-middleware][add a link]
\ No newline at end of file
diff --git a/docs/components/specific-apps/admin-gui.md b/docs/components/specific-apps/admin-gui.md
index 2edf8f7..7cd0892 100644
--- a/docs/components/specific-apps/admin-gui.md
+++ b/docs/components/specific-apps/admin-gui.md
@@ -4,7 +4,7 @@
 
 The Admin GUI is a web user interface dedicated to admin users.
 
-It let them administrate the database of different services such as resources (resources, formats, projections), partners, reuse... 
+It let them administrate the database of different services such as resources (resources, formats, projections), partners, reuse...
 
 It also has a section that provides logs of the datasets indexation jobs. It can be usefull to track indexation errors, execution time for each task...
 
@@ -22,7 +22,7 @@ npm install -g @angular/cli
 
 Open the `/src/assets/config/config.json` file and update the configuration in order to match yours.
 
-For more explainations on how the configuration system works refer to the dedicated [section](../miscellaneous/multi-environments-docker-build-for-angular.md).
+For more explainations on how the configuration system works refer to the dedicated [section](../../miscellaneous/multi-environments-docker-build-for-angular.md).
 
 
 
@@ -80,4 +80,4 @@ docker-compose --project-name admin-gui up
 
 ## Authentication
 
-It uses the same authentication methods as the portail data web app, so if you have an account you will be able to log in. However only a user belongging to the admin group will be able to create, modify and delete entities. The groups are managed by the api gateway, for more information refer to the [Authentication and Authorization](../miscellaneous/authentication&authorization.md) section.
\ No newline at end of file
+It uses the same authentication methods as the portail data web app, so if you have an account you will be able to log in. However only a user belongging to the admin group will be able to create, modify and delete entities. The groups are managed by the api gateway, for more information refer to the [Authentication and Authorization](../../miscellaneous/authentication&authorization.md) section.
diff --git a/docs/components/specific-apps/web-app.md b/docs/components/specific-apps/web-app.md
index 8f31fb3..66c7600 100644
--- a/docs/components/specific-apps/web-app.md
+++ b/docs/components/specific-apps/web-app.md
@@ -5,7 +5,7 @@ Organize a folders and files structure inside a project is never an easy task, a
 We think that at the beginning we should just not overthink about it, choose one way to do it, keep to it, until a natural re-organization will happen if needed.   
 Here is our `/src` folder structure:
 
-![folers structure](../assets/folders.png)
+![folers structure](../../assets/folders.png)
 
 * `src/app`: where the Angular code is located. With time we organized this part in different modules taking care on one main functionnality each. Inside one module each component has its own folder with one `.ts`, one `.scss` and one `html` file.   
 * `/src/assets`: contains all the images, favicon, svg, fonts, Mapbox style files.
@@ -52,4 +52,4 @@ So we used...Elasticsearch. It is super fast and even have geographical research
 
 ## Credits
 
-## Licence
\ No newline at end of file
+## Licence
diff --git a/docs/index.md b/docs/index.md
index 7a8e1d8..aa3c4b9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,2 +1 @@
-# Welcome to the functional documentation of portail-data
-
+# Welcome!
diff --git a/docs/accessibility/accessibility.md b/docs/miscellaneous/accessibility.md
similarity index 97%
rename from docs/accessibility/accessibility.md
rename to docs/miscellaneous/accessibility.md
index 3f7da67..4cea8e1 100644
--- a/docs/accessibility/accessibility.md
+++ b/docs/miscellaneous/accessibility.md
@@ -25,7 +25,7 @@ npm install -g pa11y-ci
 Then create a **.pa11y1** json file.
 ```
 {
-  "urls": [ 
+  "urls": [
     "https://data.beta.grandlyon.com/fr/accueil"
   ]
 }
@@ -38,4 +38,4 @@ pay11-ci
 It is also possible to save the report as a json file:
 ```
 pay11-ci --json > report.json
-```
\ No newline at end of file
+```
diff --git a/docs/miscellaneous/nestjs-micro-services.md b/docs/miscellaneous/nestjs-micro-services.md
new file mode 100644
index 0000000..34964ee
--- /dev/null
+++ b/docs/miscellaneous/nestjs-micro-services.md
@@ -0,0 +1,13 @@
+# NestJS-based micro-services
+
+## An overview of NestJS
+
+...
+
+## API documentation
+
+NestJS provides a [swagger module](https://docs.nestjs.com/recipes/swagger) that can be easily integrated. By using dedicated annotations alongside the various endpoint declarations, the developer can provide the module information to automatically generate a swagger documentation, reachable at `/api-doc`.
+
+## Health checks
+
+NestJS provides a health module based on [Terminus](https://github.com/nestjs/terminus), allowing developers to declare predefined and/or custom health indicators. By default, the health status of a given NestJS service is available through the `/health` endpoint.
diff --git a/docs/miscellaneous/security.md b/docs/miscellaneous/security.md
new file mode 100644
index 0000000..271354b
--- /dev/null
+++ b/docs/miscellaneous/security.md
@@ -0,0 +1,6 @@
+# Security
+
+## XSRF Token
+
+
+## User password encryption
diff --git a/docs/overview/index.md b/docs/overview/index.md
index 4e65c33..5897af8 100644
--- a/docs/overview/index.md
+++ b/docs/overview/index.md
@@ -14,7 +14,7 @@ package "data.grandlyon.com" {
 @enduml
 ```
 
-In this respect, the Web Portal is just one of the various Core's clients, in the same way as 3rd-party client applications:
+In this respect, the Web Portal is just one among the (hopefully) many Core's clients, in the same way as 3rd-party client applications:
 
 ```plantuml
 @startuml
@@ -106,7 +106,7 @@ A6 | Postfix | [Link](http://www.postfix.org/) | SMTP Server
 
 ID | Name | Repo | Doc | Usage | Deps
 --- | --- | --- | --- | --- | ---
-M1 | Legacy AUTH | ... | ... | Facilitating the interaction between the Web Portal Authentication Service (S1) and the AUTHN/AUTHZ Service (C1) hosted by data.grandlyon.com's Core macro-component |  C1
+M1 | Legacy AUTH | ... | ... | Facilitating the interaction between the Web Portal Authentication Service (S1) and the AUTHN/AUTHZ Service (C1) hosted by data.grandlyon.com's Core macro-component |  C1, S5
 
 ### Proxies
 
@@ -125,6 +125,13 @@ ID | Name | Repo | Doc | Usage | Deps
 I1 | Editorial Content | ... | ... | Indexing the posts and pages edited in Ghost | A2
 I2 | Metadata and Data | ... | ... | Indexing the metadata and data hosted, respectively, by data.grandlyon.com's catalog (C3) and database (C4) | C3, C4
 
+### Tools
+
+ID | Name | Repo | Doc | Usage | Deps
+--- | --- | --- | --- | --- | ---
+T1 | MinIO master-slave replication tool | ... | ... | Replicating/mirroring the assets stored in one "master" instance of MinIO to some other "slave" instances | A5
+
+
 
 ### Services
 
@@ -132,11 +139,11 @@ In alphabetical order:
 
 ID | Name | Repo | Doc | Usage | Deps
 --- | --- | --- | --- | --- | ---
-S1 | Authentication | ...  | ... | Allowing users to create accounts and to perform logins and logouts | M1, S5
+S1 | Authentication | ...  | [Link](../components/services/authentication.md) | Allowing users to create accounts and to perform logins and logouts | A3, S5
 S2 | Changelog | [Link](https://gitlab.alpha.grandlyon.com/refonte-data/service-changelog)  | ... | Keeping track of the new features available to users throughout the developments|
 S3 | Credits | ... | ... | Catalog of the Open Source initiatives powering the data.grandlyon.com project | S6 |
 S4 | CSV Catalog Downloader | ... | ... |  Allowing users to download cached CSV exports of the metadata catalog | C3 |
-S5 | Mail | ... | [Link](../features/services/mail.md) | Sending e-mails to both end- and back-office users | A6
+S5 | Mail | ... | [Link](../components/services/mail.md) | Sending e-mails to both end- and back-office users | A6
 S6 | Media Library | ... | ... | Managing the images shown across the various pages of the Web Portal (organizations, posts, ...) |
 S7 | Organizations | ... | ... | A catalog of the partners of the data.grandlyon.com, typically Data Providers | S6
 S8 | Resources Helper | ... | ... | Assisting users in the composition of custom queries against the Core APIs |
diff --git a/mkdocs.yml b/mkdocs.yml
index 005d6c2..91a5d34 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -22,33 +22,44 @@ markdown_extensions:
         server: http://www.plantuml.com/plantuml
 
 nav:
+    - Home: index.md
     - Overview: overview/index.md
     - Features: features/index.md
     - Architecture: architecture/index.md
     - Components:
       - Core Components:
-        - Off-the-shelf applications:
-          - API Gateway: components/off-the-shelf-apps/api-gateway.md
-          - Headless CMS: components/off-the-shelf-apps/cms.md
-          - Search Engine: components/off-the-shelf-apps/elasticsearch.md
-        # - Middlewares:
+        - Legacy AUTH: components/core/legacy-auth.md
+      - Off-the-shelf applications:
+        - API Gateway: components/off-the-shelf-apps/api-gateway.md
+        - Headless CMS: components/off-the-shelf-apps/cms.md
+        - Search Engine: components/off-the-shelf-apps/elasticsearch.md
+      - Middlewares:
+        - Legacy AUTH: components/middlewares/legacy-auth-middleware.md
         # - Proxies:
       - Indexers:
         - Metadata and Data: components/indexers/metadata-and-data.md
         - Editorial Content: components/indexers/editorial-content.md
       - Services:
         - Authentication: components/services/authentication.md
+        - CSV Catalog Downloader: components/services/csv-catalog-downloader.md
+        - Mail: components/services/mail.md
+        - Media Library: components/services/media-library.md
         - Organizations: components/services/organizations.md
         - Resources: components/services/resources.md
       - Specific applications:
         - Web App: components/specific-apps/web-app.md
         - Admin GUI: components/specific-apps/admin-gui.md
     - Administration: administration/admin-tools.md
+    - Deployment:
+      - 2019 deployment of the first public beta version: deployment/beta-deployment.md
     - Monitoring: monitoring/monitoring.md
-    #- Authentication & Authorization: miscellaneous/authentication&authorization.md
     - Other:
+      - Security: miscellaneous/security.md
+      - NestJS-based micro-services: miscellaneous/nestjs-micro-services.md
+      - Accessibility: miscellaneous/accessibility.md
+      - AUTHN & AUTHZ: miscellaneous/authentication&authorization.md
       - Gitflow: miscellaneous/gitflow-ci-cd.md
       - VSCode: miscellaneous/vscode-settings.md
       - SASS recommendation: miscellaneous/sass-recommendation.md
       - Webapp-auth: miscellaneous/webapp-auth.md
-      - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular
+      - Multi-environment docker build for Angular app: miscellaneous/multi-environments-docker-build-for-angular.md
-- 
GitLab