Update for auth.md for refresh token and support to mermaid charts in…

… pdf (#10656)

* WIP for support of mermaid charts

* Minor fixes to mdocks file

* Restored all old flowcharts

* Improved doc

* Fixed path to scss

* Added effective documentation

* added pycache to gitignore

* More minor fixes to PDF

.gitignore

@@ -26,3 +26,5 @@ debug.log
 .vscode/settings.json
 site
 .DS_Store
+venv
+__pycache__

docs/developer-guide/documentation-guidelines.md

@@ -31,9 +31,20 @@ Install [**Python 3**](https://www.python.org/downloads/) and **pip** following
 
 ### 2. Libraries installation
 
-Install **all** the libraries/plugins in `docs/requirements.txt` using **_pip_** while matching the exact version present.
+Usage of a virtual environment is recommended to avoid conflicts with other python projects.
+With the following commands you can create a virtual environment and install the required libraries, and so execute the documentation build and development without affecting the global python environment.
 
-`pip install -r docs/requirements.txt`
+```sh
+python -m venv venv
+source venv/bin/activate
+pip install -r docs/requirements.txt
+```
+
+On next sessions, you can activate the virtual environment with the command `source venv/bin/activate`.
+
+If you want to deactivate the virtual environment, you can use the command `deactivate`.
+
+If you want to install the libraries globally, you can use the command `pip install -r docs/requirements.txt` with the virtual environment deactivated.
 
 ### 3. Build the documentation
 

docs/developer-guide/integrations/auth.md

@@ -4,7 +4,27 @@ In this section you can see the implementation details about the login / logout
 
 ## Standard MapStore login
 
-<img src="../img/standard-mapstore-login.png" class="ms-docimage"  style="max-width: 400px"/>
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Browser
+    participant Backend
+    Browser ->>+ Backend: /session/login<br />(username, password)
+    Note over Backend: create session
+    Backend -->>- Browser: {access_token, refresh_token}
+    Browser --) Backend: /users/user/details
+    Backend --) Browser:  {User: <...>}
+    Note over Browser: LOGIN_SUCCESS
+    loop Token refresh
+        Browser --) Backend: /session/refresh
+        Backend --) Browser: {access_token: <token>, refresh_token: <r_token>}
+        Note over Browser: REFRESH_SUCCESS
+    end
+    Browser --)+ Backend: Logout
+    Note over Backend: delete session
+    Backend --)- Browser: <res>
+    Note over Browser: LOGOUT
+```
 
 ### Configure session timeout
 
@@ -43,4 +63,37 @@ Disabling the refresh token (setting `restSessionService.autorefresh` to `false`
 
 ## OpenID MapStore Login
 
-<img src="../img/openid-mapstore-login.png" class="ms-docimage" style="max-width: 400px"/>
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Browser
+    participant Backend
+    participant OpenIDProvider
+    Browser ->> Backend: /openid/<OpenIDProvider>/login
+    Backend -->> Browser: redirect to OpenIDProvider
+    Browser ->>+ OpenIDProvider: Authenticate
+    OpenIDProvider -->>- Browser: redirect to callback (Backend entry point)
+    Browser ->>+ Backend:  /openid/<OpenIDProvider>/callback
+    Note over Backend: Create User
+    Backend -->>- Browser: redirect to homepage  <br /> (set-cookie <identifier>set-cookie <authprovider>)
+    Browser --) Backend: /openid/<authProvider>/tokens?identifier=<identifier>
+    Backend --) Browser:  {access_token: <token>, refresh_token: <r_token>}
+    Browser --) Backend: /users/user/details
+    Backend --) Browser:  {User: <...>}
+    Note over Browser: LOGIN_SUCCESS
+    loop Token refresh
+        Browser --) Backend: /session/refresh
+
+        loop Refresh retry 3 times max
+            Backend --) OpenIDProvider: Refresh
+            OpenIDProvider --) Backend: {access_token, refresh_token (optional)}
+        end
+        Backend --) Browser: {access_token: <token>, refresh_token: <r_token>}
+        Note over Browser: REFRESH_SUCCESS
+    end
+    Browser --)+ Backend: Logout
+    Backend --) OpenIDProvider: Logout
+    OpenIDProvider --) Backend: <res>
+    Backend --)- Browser: <res>
+    Note over Browser: LOGOUT
+```

docs/developer-guide/integrations/geoserver.md

@@ -7,7 +7,20 @@ MapStore can share users, groups an roles with GeoServer. This type of integrati
 This guide explains how to share users, groups and roles between MapStore and GeoServer.
 Applying this configurations will allow users logged in MapStore to be recognized by GeoServer. So security rules about restrictions on services, layers and so on can be correctly applied to MapStore users (also using [GeoFence](https://docs.geoserver.org/latest/en/user/extensions/geofence-server/index.html)).
 
-<img src="../img/mapstore-geoserver-users-integration.png" class="ms-docimage"/>
+```mermaid
+sequenceDiagram
+    actor User
+    participant GeoServer
+    participant MapStore
+    participant UserGroup Service/Role Service
+    User ->>+ GeoServer:  OGC Request <br />(w/authkey)
+    GeoServer ->>+ MapStore: authkey
+    MapStore ->>- GeoServer: username
+    GeoServer ->>+ UserGroup Service/Role Service: username
+    UserGroup Service/Role Service ->>- GeoServer: User(groups, roles)
+    Note over GeoServer: Filter/Allow/Deny data access <br /> by Resource Access Manager
+    GeoServer ->>- User: data
+```
 
 !!! note
     **UserGroup Service/Role Service** can be *MapStore database* or *LDAP* depending on the setup you prefer.

docs/developer-guide/integrations/infrastructure-setups.md

@@ -4,16 +4,42 @@ Accordingly with your infrastructure, there are several setups you can imagine w
 
 ## MapStore-GeoServer integration
 
-<img src="../img/mapstore-geoserver-integration.png" class="ms-docimage"/>
+```mermaid
+flowchart TB
+      MapStore -->|"Resources <br/> (e.g. maps)"| DB[(MapStore<br/> Database)]
+      MapStore -->| Users, Groups, Roles| DB[(MapStore<br/> Database)]
+      GeoServer --> |Users, Groups, Roles| DB
+      GeoServer <--> |authkey| MapStore
+```
 
 ## MapStore-LDAP + MapStore-GeoServer
 
-<img src="../img/mapstore-ldap-mapstore-geoserver.png" class="ms-docimage"/>
+```mermaid
+flowchart TB
+    MapStore -->| Users, Groups, Roles| DB[(MapStore<br/> Database)]
+    MapStore -->|"Resources <br/> (e.g. maps)"| DB[(MapStore<br/> Database)]
+    GeoServer <--> |authkey| MapStore
+    DB <--> | sync on login | LDAP[(LDAP)]
+    GeoServer --> |Users, Groups, Roles| DB
+```
 
 ## MapStore-GeoServer + MapStore-LDAP + GeoServer-LDAP
 
-<img src="../img/mapStore-geoserver-mapstore-ldap-geoserver-ldap.png" class="ms-docimage"/>
+```mermaid
+flowchart TB
+    MapStore -->|"Resources <br/> (e.g.maps)"| DB[(MapStore<br/> Database)]
+    MapStore -->| Users, Groups, Roles| DB
+    GeoServer <--> |authkey| MapStore
+    GeoServer --> |Users, Groups, Roles| LDAP
+    DB <--> | sync on login | LDAP[(LDAP)]
+```
 
 ## MapStore-GeoServer + MapStore-LDAP (direct) + GeoServer-LDAP
 
-<img src="../img/mapStore-geoserver-mapstore-ldap-direct-geoserver-ldap.png" class="ms-docimage"/>
+```mermaid
+flowchart TB
+    MapStore -->|"Resources <br/> (e.g. maps)"| DB[(MapStore<br/> Database)]
+    GeoServer <--> |authkey| MapStore
+    MapStore -->| Users, Groups, Roles| LDAP[(LDAP)]
+    GeoServer --> |Users, Groups, Roles| LDAP
+```

docs/developer-guide/integrations/users/openId.md

@@ -94,6 +94,10 @@ oidcOAuth2Config.internalRedirectUri=http://localhost:8080/mapstore
 - `oidcOAuth2Config.rolesClaim`: (*optional*) the role claims. If a claim contains roles, you can map them to MapStore roles. The roles can be only `ADMIN` or `USER`. If the claim is not present, the default role will be `USER`.
 - `oidcOAuth2Config.groupsClaim`: (*optional*) the group claims. If a claim contains groups, you can map them to MapStore groups. If the claim is not present, no group will be assigned (except the default `everyone` group).
 - `oidcOAuth2Config.globalLogoutEnabled`: (*optional*): if true (and the server supports it) invokes global logout on MapStore logout
+- `oidcOAuth2Config.scopes`: (*optional*): allows to customize the scopes to request. If empty, MapStore will use the one present in the discovery document.
+- `oidcOAuth2Config.maxRetry`: (*optional*) the maximum number of retry attempts for the OpenID Connect authentication process. Default is `3`.
+- `oidcOAuth2Config.initialBackoffDelay`: (*optional*) the initial delay (in milliseconds) before retrying the OpenID Connect authentication process. Default is `1000` (1 second).
+- `oidcOAuth2Config.backoffMultiplier`: (*optional*) the multiplier to apply to the delay for each retry attempt. Default is `2.0`.
 
 !!! note
     The only mandatory claim is the `email` or what you indicated in `oidcOAuth2Config.principalKey`. The `rolesClaim` and `groupsClaim` configurations are optional. If you don't need to map roles or groups, you can omit them. At the moment, there is no mapping for roles and groups for the generic OIDC provider. If you need to map roles and groups, you can use the `keycloak` provider.

docs/print_template/styles.scss

@@ -0,0 +1,13 @@
+/* reduces the max height of the charts
+   to fit the page better */
+img {
+    max-height: 500px;
+    display: block;
+    margin: 0 auto;
+}
+/* fix icons in admonitions */
+.md-typeset .admonition-title:before{
+    position: absolute;
+    left: 10px;
+    top: 10px;
+}

docs/requirements.txt

@@ -4,3 +4,4 @@ jinja2==3.1.4
 Markdown==3.4.4
 WeasyPrint==52.5
 mkdocs-with-pdf==0.9.3
+mkdocs-kroki-plugin==0.9.0

docs/theme/css/extra.css

@@ -97,4 +97,4 @@ li.md-tabs__item:hover{
     margin-right: 4px;
     background-position: center;
     background-repeat: no-repeat;
-}
+}

mkdocs.yml

@@ -89,7 +89,7 @@ nav:
       - Printing a Map: 'user-guide/print.md'
       - Importing and Exporting Files: 'user-guide/import.md'
       - Catalog Services: 'user-guide/catalog.md'
-      - Performing Measurments: 'user-guide/measure.md'
+      - Performing Measurements: 'user-guide/measure.md'
       - Annotations: 'user-guide/annotations.md'
       - Map Views: 'user-guide/map-views.md'
       - Street View: 'user-guide/street-view.md'
@@ -119,7 +119,7 @@ nav:
       - Map Toolbar: 'user-guide/content-map-toolbar.md'
       - Web Page Toolbar: 'user-guide/content-web-toolbar.md'
       - Media Editor: 'user-guide/media-editor-window.md'
-      - Configue the map: 'user-guide/configure-map.md'
+      - Configure the map: 'user-guide/configure-map.md'
 
   - Developer Guide:
     - Requirements: 'developer-guide/requirements.md'
@@ -176,10 +176,20 @@ nav:
       - Advanced Project Customization: 'developer-guide/advanced-project-customization.md'
     - Communicating with MapStore:
       - API usage: 'developer-guide/API-usage.md'
-      - MapViewer query paramaters: 'developer-guide/map-query-parameters.md'
+      - MapViewer query parameters: 'developer-guide/map-query-parameters.md'
 plugins:
   - search
-  - with-pdf:
+  # kroki is used to support mermaid charts in also in pdf.
+  # See https://kroki.io/.
+  - kroki: # https://pypi.org/project/mkdocs-kroki-plugin/
+      FencePrefix: ''
+      # HttpMethod set to POST pre-loads the images.
+      # USing GET the charts will be generated on the fly, so the rendering will be slower, but
+      # when not visualizing the charts, no request will be made to the kroki server.
+      HttpMethod: 'POST'
+      FileTypeOverrides:
+        mermaid: png
+  - with-pdf: # https://pypi.org/project/mkdocs-with-pdf/
       author: GeoSolutionsGroup
       copyright: 'MapStore©'
       #
@@ -191,6 +201,7 @@ plugins:
       toc_level: 3
       output_path: pdf/mapstore_documentation.pdf
       enabled_if_env: ENABLE_PDF_EXPORT
-      debug_html: true
+      debug_html: false # set to true to log the html content of the pdf on the console on build
       show_anchors: true
-      verbose: true
+      verbose: false    # set to true to log the pdf generation steps in detail
+      custom_template_path: 'docs/print_template' # includes custom styles.scss for pdf