diff --git a/.gitignore b/.gitignore index e123098707..9dd5ee68e0 100644 --- a/.gitignore +++ b/.gitignore @@ -26,3 +26,5 @@ debug.log .vscode/settings.json site .DS_Store +venv +__pycache__ diff --git a/docs/developer-guide/documentation-guidelines.md b/docs/developer-guide/documentation-guidelines.md index 4b80ebc72b..29f1367ebe 100644 --- a/docs/developer-guide/documentation-guidelines.md +++ b/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 diff --git a/docs/developer-guide/integrations/auth.md b/docs/developer-guide/integrations/auth.md index 8cae0ef7fc..5dae0c0eb3 100644 --- a/docs/developer-guide/integrations/auth.md +++ b/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 - +```mermaid +sequenceDiagram + autonumber + actor Browser + participant Backend + Browser ->>+ Backend: /session/login
(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: , refresh_token: } + Note over Browser: REFRESH_SUCCESS + end + Browser --)+ Backend: Logout + Note over Backend: delete session + Backend --)- Browser: + Note over Browser: LOGOUT +``` ### Configure session timeout @@ -43,4 +63,37 @@ Disabling the refresh token (setting `restSessionService.autorefresh` to `false` ## OpenID MapStore Login - +```mermaid +sequenceDiagram + autonumber + actor Browser + participant Backend + participant OpenIDProvider + Browser ->> Backend: /openid//login + Backend -->> Browser: redirect to OpenIDProvider + Browser ->>+ OpenIDProvider: Authenticate + OpenIDProvider -->>- Browser: redirect to callback (Backend entry point) + Browser ->>+ Backend: /openid//callback + Note over Backend: Create User + Backend -->>- Browser: redirect to homepage
(set-cookie set-cookie ) + Browser --) Backend: /openid//tokens?identifier= + 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 + + loop Refresh retry 3 times max + Backend --) OpenIDProvider: Refresh + OpenIDProvider --) Backend: {access_token, refresh_token (optional)} + end + Backend --) Browser: {access_token: , refresh_token: } + Note over Browser: REFRESH_SUCCESS + end + Browser --)+ Backend: Logout + Backend --) OpenIDProvider: Logout + OpenIDProvider --) Backend: + Backend --)- Browser: + Note over Browser: LOGOUT +``` diff --git a/docs/developer-guide/integrations/geoserver.md b/docs/developer-guide/integrations/geoserver.md index 9ef1d1743f..705bea47d5 100644 --- a/docs/developer-guide/integrations/geoserver.md +++ b/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)). - +```mermaid +sequenceDiagram + actor User + participant GeoServer + participant MapStore + participant UserGroup Service/Role Service + User ->>+ GeoServer: OGC Request
(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
by Resource Access Manager + GeoServer ->>- User: data +``` !!! note **UserGroup Service/Role Service** can be *MapStore database* or *LDAP* depending on the setup you prefer. diff --git a/docs/developer-guide/integrations/img/mapStore-geoserver-mapstore-ldap-direct-geoserver-ldap.png b/docs/developer-guide/integrations/img/mapStore-geoserver-mapstore-ldap-direct-geoserver-ldap.png deleted file mode 100644 index 0c76487b19..0000000000 Binary files a/docs/developer-guide/integrations/img/mapStore-geoserver-mapstore-ldap-direct-geoserver-ldap.png and /dev/null differ diff --git a/docs/developer-guide/integrations/img/mapStore-geoserver-mapstore-ldap-geoserver-ldap.png b/docs/developer-guide/integrations/img/mapStore-geoserver-mapstore-ldap-geoserver-ldap.png deleted file mode 100644 index c9e1c0f662..0000000000 Binary files a/docs/developer-guide/integrations/img/mapStore-geoserver-mapstore-ldap-geoserver-ldap.png and /dev/null differ diff --git a/docs/developer-guide/integrations/img/mapstore-geoserver-integration.png b/docs/developer-guide/integrations/img/mapstore-geoserver-integration.png deleted file mode 100644 index 45e80c275c..0000000000 Binary files a/docs/developer-guide/integrations/img/mapstore-geoserver-integration.png and /dev/null differ diff --git a/docs/developer-guide/integrations/img/mapstore-geoserver-users-integration.png b/docs/developer-guide/integrations/img/mapstore-geoserver-users-integration.png deleted file mode 100644 index 72f68504a8..0000000000 Binary files a/docs/developer-guide/integrations/img/mapstore-geoserver-users-integration.png and /dev/null differ diff --git a/docs/developer-guide/integrations/img/mapstore-ldap-mapstore-geoserver.png b/docs/developer-guide/integrations/img/mapstore-ldap-mapstore-geoserver.png deleted file mode 100644 index 672c7c52ef..0000000000 Binary files a/docs/developer-guide/integrations/img/mapstore-ldap-mapstore-geoserver.png and /dev/null differ diff --git a/docs/developer-guide/integrations/img/openid-mapstore-login.png b/docs/developer-guide/integrations/img/openid-mapstore-login.png deleted file mode 100644 index 18b10068a2..0000000000 Binary files a/docs/developer-guide/integrations/img/openid-mapstore-login.png and /dev/null differ diff --git a/docs/developer-guide/integrations/img/standard-mapstore-login.png b/docs/developer-guide/integrations/img/standard-mapstore-login.png deleted file mode 100644 index 6122968ef7..0000000000 Binary files a/docs/developer-guide/integrations/img/standard-mapstore-login.png and /dev/null differ diff --git a/docs/developer-guide/integrations/infrastructure-setups.md b/docs/developer-guide/integrations/infrastructure-setups.md index b8eabeb505..6d7a414aa4 100644 --- a/docs/developer-guide/integrations/infrastructure-setups.md +++ b/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 - +```mermaid +flowchart TB + MapStore -->|"Resources
(e.g. maps)"| DB[(MapStore
Database)] + MapStore -->| Users, Groups, Roles| DB[(MapStore
Database)] + GeoServer --> |Users, Groups, Roles| DB + GeoServer <--> |authkey| MapStore +``` ## MapStore-LDAP + MapStore-GeoServer - +```mermaid +flowchart TB + MapStore -->| Users, Groups, Roles| DB[(MapStore
Database)] + MapStore -->|"Resources
(e.g. maps)"| DB[(MapStore
Database)] + GeoServer <--> |authkey| MapStore + DB <--> | sync on login | LDAP[(LDAP)] + GeoServer --> |Users, Groups, Roles| DB +``` ## MapStore-GeoServer + MapStore-LDAP + GeoServer-LDAP - +```mermaid +flowchart TB + MapStore -->|"Resources
(e.g.maps)"| DB[(MapStore
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 - +```mermaid +flowchart TB + MapStore -->|"Resources
(e.g. maps)"| DB[(MapStore
Database)] + GeoServer <--> |authkey| MapStore + MapStore -->| Users, Groups, Roles| LDAP[(LDAP)] + GeoServer --> |Users, Groups, Roles| LDAP +``` diff --git a/docs/developer-guide/integrations/users/img/desired-workflow.png b/docs/developer-guide/integrations/users/img/desired-workflow.png deleted file mode 100644 index 12502ae8e8..0000000000 Binary files a/docs/developer-guide/integrations/users/img/desired-workflow.png and /dev/null differ diff --git a/docs/developer-guide/integrations/users/img/initialization.png b/docs/developer-guide/integrations/users/img/initialization.png deleted file mode 100644 index e9e3ac92f5..0000000000 Binary files a/docs/developer-guide/integrations/users/img/initialization.png and /dev/null differ diff --git a/docs/developer-guide/integrations/users/img/keycloakjs-library.png b/docs/developer-guide/integrations/users/img/keycloakjs-library.png deleted file mode 100644 index e27f7c3fb7..0000000000 Binary files a/docs/developer-guide/integrations/users/img/keycloakjs-library.png and /dev/null differ diff --git a/docs/developer-guide/integrations/users/img/login-from-keycloak.png b/docs/developer-guide/integrations/users/img/login-from-keycloak.png deleted file mode 100644 index 75532786e9..0000000000 Binary files a/docs/developer-guide/integrations/users/img/login-from-keycloak.png and /dev/null differ diff --git a/docs/developer-guide/integrations/users/openId.md b/docs/developer-guide/integrations/users/openId.md index 2424c262f3..470a305056 100644 --- a/docs/developer-guide/integrations/users/openId.md +++ b/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. diff --git a/docs/print_template/styles.scss b/docs/print_template/styles.scss new file mode 100644 index 0000000000..8766cfac4b --- /dev/null +++ b/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; +} diff --git a/docs/requirements.txt b/docs/requirements.txt index b6daddb777..6d3249e4cf 100644 --- a/docs/requirements.txt +++ b/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 diff --git a/docs/theme/css/extra.css b/docs/theme/css/extra.css index 9c0b82c1e2..3dc82a2fe1 100644 --- a/docs/theme/css/extra.css +++ b/docs/theme/css/extra.css @@ -97,4 +97,4 @@ li.md-tabs__item:hover{ margin-right: 4px; background-position: center; background-repeat: no-repeat; -} \ No newline at end of file +} diff --git a/mkdocs.yml b/mkdocs.yml index e819fbb8d3..9c5b9053d3 100644 --- a/mkdocs.yml +++ b/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