diff --git a/docs/developer-guide/integrations/users/img/azure-1.jpg b/docs/developer-guide/integrations/users/img/azure-1.jpg new file mode 100644 index 0000000000..e74c5a28d5 Binary files /dev/null and b/docs/developer-guide/integrations/users/img/azure-1.jpg differ diff --git a/docs/developer-guide/integrations/users/img/azure-2.jpg b/docs/developer-guide/integrations/users/img/azure-2.jpg new file mode 100644 index 0000000000..f013b4e340 Binary files /dev/null and b/docs/developer-guide/integrations/users/img/azure-2.jpg differ diff --git a/docs/developer-guide/integrations/users/img/azure-3.jpg b/docs/developer-guide/integrations/users/img/azure-3.jpg new file mode 100644 index 0000000000..1285bc2e0c Binary files /dev/null and b/docs/developer-guide/integrations/users/img/azure-3.jpg differ diff --git a/docs/developer-guide/integrations/users/img/azure-4.jpg b/docs/developer-guide/integrations/users/img/azure-4.jpg new file mode 100644 index 0000000000..d70ee63b7f Binary files /dev/null and b/docs/developer-guide/integrations/users/img/azure-4.jpg differ diff --git a/docs/developer-guide/integrations/users/img/azure-5.jpg b/docs/developer-guide/integrations/users/img/azure-5.jpg new file mode 100644 index 0000000000..773616859e Binary files /dev/null and b/docs/developer-guide/integrations/users/img/azure-5.jpg differ diff --git a/docs/developer-guide/integrations/users/openId.md b/docs/developer-guide/integrations/users/openId.md index 1e03edb67f..7775d1dba3 100644 --- a/docs/developer-guide/integrations/users/openId.md +++ b/docs/developer-guide/integrations/users/openId.md @@ -1,41 +1,190 @@ # Integration with OpenID connect -MapStore allows to integrate and login using some common [OpenID connect](https://openid.net/connect/) services. Having this support properly configured, you can make MapStore users able to login with the given OpenID service. +MapStore allows to integrate with [OpenID connect](https://openid.net/connect/) services. This allows to use external services to authenticate users in MapStore. This is useful when you have to integrate MapStore with an existing authentication system, or when you want to use a third-party service to authenticate users. ## Customizing logo an text in Login Form -For details about the configuration for a specific service, please refer to the specific section below. For details about `authenticationProviders` optional values (e.g. to customize icon and/or text to show), refer to the documentation of the [LoginPlugin](https://mapstore.geosolutionsgroup.com/mapstore/docs/api/plugins#plugins.Login). +For details about the configuration for a specific service, please refer to the corresponding section below. If you want to customize the icon and/or text displayed, you can refer to the documentation of the [LoginPlugin](https://mapstore.geosolutionsgroup.com/mapstore/docs/api/plugins#plugins.Login). -By default `authenticationProviders` is `{"type": "basic", "provider": "geostore"}`, that represents the standard login on **MapStore** with username and password. With the default configuration, when the user try to login, MapStore will show the classic login form. +By default, the `authenticationProviders` field contains only `{"type": "basic", "provider": "geostore"}`, which represents the standard login on **MapStore** using a username and password. With this default configuration, when a user tries to log in, MapStore will display the classic login form. -It is possible to add other providers to the list (e.g. `openid`) and they will be added as options to the login window. -You can remove the `geostore` entry from `authenticationProviders` list to remove the login form from the possible login systems. +You can add additional providers to the list (e.g., `openid`), and they will be included as options in the login window. If you want to remove the login form and only use the added providers, you can remove the `geostore` entry from the `authenticationProviders` list. -!!! note - If only one OpenID entry is present in `authenticationProviders` (and no `geostore` entry available), clicking on login in the login menu will not show any intermediate window and you will be redirected directly to the OpenID provider configured. If more than one entry is present in `authenticationProviders` list, the user will have to choose one of them to be authenticated. +!!! info + If only one OpenID entry is present in `authenticationProviders` (and no `geostore` entry available), clicking on the login entry in the login menu will redirect directly to the OpenID provider login page configured, without showing the login window. If more than one entry is present in the `authenticationProviders` list, the the login window will be provided in the MapStore UI to be able choose the desired one for the authentication. ## Supported OpenID services -MapStore allows to integrate with the following OpenID providers. +MapStore provides a generic OpenID connect provider (`oidc`) that can be used to configure any OpenID Connect service (Google, Microsoft, Keycloak, Facebook, Github, etc.). In addition, MapStore provides specific configurations for some services. This means that you can configure MapStore to use the following services out of the box: + +- OpenID connect +- Google (specific) +- Keycloak (specific) -- Google -- Keycloak +For each service you want to include, you have to: -For each service you want to add you have to: +- configure the service (e.g., create a new application on Google Console, create a new client on Keycloak, etc.) +- properly configure the backend (in `mapstore-ovr.properties`) +- modify the `localConfig.json` file by adding a proper entry to the `authenticationProviders` -- properly configure the backend -- modify `localConfig.json` adding a proper entry to the `authenticationProviders`. +Moreover the keycloak provider allows to configure advanced features like the **Single Sign On (SSO)** with other applications and **direct user database integration** as for [LDAP](ldap.md#ldap-integration-with-mapstore). !!! note - For the moment we can configure only one authentication per service type (only one for google, only one for keycloak ...). + For the moment the generic `oidc` provider does not support multiple instances. This means that you can configure only **one** generic `oidc` provider. You can configure the specific providers (e.g., `google`, `keycloak`) in addition to the generic `oidc` provider, but not multiple instances of the generic `oidc` provider. So for instance you can configure a generic `oidc` provider (e.g. connected to Github) plus a `google` and a `keycloak` provider, but not two generic `oidc` providers. + +### OpenID connect (generic) + +In order to configure the generic OpenID provider with a service of your choice you have to: + +- Configure the OpenID provider client +- Configure MapStore back-end +- Configure the MapStore front-end + +#### Configure OpenID provider client + +This step depends on the specific OpenID provider so, please, refer to the specific documentation of the OpenID provider you are using. You can find some examples about how to configure a generic OpenID provider with Microsoft Azure in the following sections. The same information are valid for other OpenID providers, like Google, Keycloak, etc. +You have to get the following information: + +- **Client ID**: the client id. This is the client id that must be present on the OpenID provider +- **Client Secret**: the client secret. This is the client secret for the client id on the OpenID provider +- **Discovery URL**: the discovery URL. This is the URL that contains all the information for the specific service. + +#### Configure the MapStore back-end + +In order to configure the generic OpenID provider you have to: + +- create/edit `mapstore-ovr.properties` file (in data-dir or class path) to configure the generic provider this way: + +```properties +# enables the keycloak OpenID Connect filter +oidcOAuth2Config.enabled=true + +# note: this is the client id have to be present on the OpenID provider +oidcOAuth2Config.clientId=mapstore-server +oidcOAuth2Config.clientSecret= +# the discovery URL +oidcOAuth2Config.discoveryUrl=http://keycloak:8080/auth/realms/mapstore/.well-known/openid-configuration +oidcOAuth2Config.sendClientSecret=true +# create the user if not present +oidcOAuth2Config.autoCreateUser=true +oidcOAuth2Config.redirectUri=http://localhost:8080/mapstore/rest/geostore/openid/oidc/callback +# Internal redirect URI (you can set it to relative path like this `../../..` to make this config work across domain) +oidcOAuth2Config.internalRedirectUri=http://localhost:8080/mapstore +# user name attribute (default is `email`) +# oidcOAuth2Config.principalKey=email +# Optional role claims, if a claim contains roles, you can map them to MapStore roles. (roles can be only ADMIN or USER) +# oidcOAuth2Config.rolesClaim=roles +# Optional group claims, if a claim contains groups, you can map them to MapStore groups. +# oidcOAuth2Config.groupsClaim=groups +# Enables global logout from SSO, if properly confugred. false by default +# oidcOAuth2Config.globalLogoutEnabled=true + +``` + +- `oidcOAuth2Config.clientId`: the client id. This is the client id that must be present on the OpenID provider +- `oidcOAuth2Config.clientSecret`: the client secret. This is the client secret for the client id on the OpenID provider +- `oidcOAuth2Config.discoveryUrl`: the discovery URL. This is the URL that contains all the information for the specific service. +- `oidcOAuth2Config.sendClientSecret`: if `true`, the client secret will be sent to the OpenID provider. If `false`, the client secret will not be sent. +- `oidcOAuth2Config.autoCreateUser`: if `true`, the user will be created, if not present, in the MapStore database. If `false`, the user will not be created (useful if the user is managed by an external service like Keycloak or LDAP). +- `oidcOAuth2Config.redirectUri`: the redirect URI. This is the URI that the OpenID provider, and it must be the effective URI of the MapStore application, with the path `/rest/geostore/openid/oidc/callback`. +- `oidcOAuth2Config.internalRedirectUri`: the internal redirect URI. This is the URI that the MapStore will redirect to after the login. It must be the effective URI of the MapStore application. +- `oidcOAuth2Config.principalKey`: (*optional*) the user name attribute. This is the attribute that will be used as user name. The default is `email`. +- `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 + +!!! note + The `rolesClaim` and `groupsClaim` 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. + +#### Configure the MapStore front-end + +- Add an entry for `oidc` in `authenticationProviders` inside `localConfig.json` file. + +```json +{ + "authenticationProviders": [ + { + "type": "openID", + "provider": "oidc", + "title": "My custom identity provider" + }, + { + "type": "basic", + "provider": "geostore" + } + ] +} +``` + +You can customize the `title` to be displayed in the login form, add an `imageURL` or use only one `authenticationProviders`, removing the `geostore` entry, if you want to use only the OpenID provider. In this case the user will be redirected directly to the OpenID provider without showing the login form. + +#### Example with Microsoft Azure + +Microsoft Azure provides OpenID Connect support. This is an example of how to configure MapStore to use Microsoft Azure as an OpenID provider. The same steps can be applied to other OpenID providers. Please refer to the specific documentation of the OpenID provider you are using. [Here](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) the one for Microsoft Azure. + +Here a quick summary of the steps to configure Microsoft Azure as an OpenID provider and get the information needed to configure MapStore: + +1. Create a new application ![Create azure application](img/azure-1.jpg) +2. Set the proper valid redirect URLs ![set redirect URL](img/azure-2.jpg) to: `https:///mapstore/rest/geostore/openid/oidc/callback` +3. Create and copy the client secret ![Create and copy client secret](img/azure-3.jpg) +4. Add optional claims if needed ![Add optional claims](img/azure-4.jpg) +5. Copy endpoints and data to configure MapStore ![Copy endpoints](img/azure-5.jpg) + +These steps are based on the [Microsoft Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app). +Please refer the official documentation for any detail or additional configuration. + +Here below are also some other sample configurations for MapStore: + +`mapstore-ovr.properties`: + +```properties +# enables the OpenID Connect filter +oidcOAuth2Config.enabled=true + +# note: this is the client id you have created in Keycloak +oidcOAuth2Config.clientId= +oidcOAuth2Config.clientSecret= + +# DISCOVERY_URL something like https://login.microsoftonline.com/abc-dfe-ghi-123-345-567-789/v2.0/.well-known/openid-configuration +oidcOAuth2Config.discoveryUrl= +oidcOAuth2Config.sendClientSecret=true +# create the user if not present +oidcOAuth2Config.autoCreateUser=true +# Here you have to set your redirect URI (here is configured for localhost) +oidcOAuth2Config.redirectUri=http://localhost:8080/mapstore/rest/geostore/openid/oidc/callback +# Internal redirect URI (you can set it to relative path like this `../../..` to make this config work across domain) +oidcOAuth2Config.internalRedirectUri=http://localhost:8080/mapstore +``` + +`localConfig.json.patch` ( *with a custom title and an image with the Microsoft logo* to show in the login form) + +```json + { + "authenticationProviders": [ + { + "type": "openID", + "provider": "oidc", + "title": "Microsoft", + "imageURL": "data:image/svg+xml;base64,PHN2ZyBhcmlhLWhpZGRlbj0idHJ1ZSIgdmlld0JveD0iMCAwIDI1IDI1IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGl0ZW1wcm9wPSJsb2dvIiBpdGVtc2NvcGU9Iml0ZW1zY29wZSI+CgkJCTxwYXRoIGQ9Ik0xMS41MjE2IDAuNUgwVjExLjkwNjdIMTEuNTIxNlYwLjVaIiBmaWxsPSIjZjI1MDIyIj48L3BhdGg+CgkJCTxwYXRoIGQ9Ik0yNC4yNDE4IDAuNUgxMi43MjAyVjExLjkwNjdIMjQuMjQxOFYwLjVaIiBmaWxsPSIjN2ZiYTAwIj48L3BhdGg+CgkJCTxwYXRoIGQ9Ik0xMS41MjE2IDEzLjA5MzNIMFYyNC41SDExLjUyMTZWMTMuMDkzM1oiIGZpbGw9IiMwMGE0ZWYiPjwvcGF0aD4KCQkJPHBhdGggZD0iTTI0LjI0MTggMTMuMDkzM0gxMi43MjAyVjI0LjVIMjQuMjQxOFYxMy4wOTMzWiIgZmlsbD0iI2ZmYjkwMCI+PC9wYXRoPgoJCTwvc3ZnPgo=" + }, + { + "type": "basic", + "provider": "geostore" + } + ] + + } +``` ### Google +The Google OpenID Connect provider allows to use Google as an authentication provider. This is useful when you want to use Google as an authentication provider for your application. + #### Create Oauth 2.0 credentials on Google Console -In order to setup the openID connection you have to setup a project in Google API Console to obtain Oauth 2.0 credentials and configure them. +In order to setup the openID connection you have to setup a project in Google API Console to obtain Oauth 2.0 credentials and configure them. Here a quick summary of the steps to configure Google as an OpenID provider. For more details, please refer to the [Google documentation](https://developers.google.com/identity/openid-connect/openid-connect). -- Open Google developer console and, from credentials section, create a new credential of type **Oauth client ID** +- Open the Google developer console and, from credentials section, create a new credential of type **Oauth client ID** @@ -51,7 +200,9 @@ Please follow the [Google documentation](https://developers.google.com/identity/ After the setup, you will have to: -- create/edit `mapstore-ovr.properties` file (in data-dir or class path) to configure the google provider this way: +- create/edit the `mapstore-ovr.properties` file (in data-dir or class path) to configure the Google OpenID integration by inserting in particular the `clientId` and the `clientSecret` obtained from Google Console. You have also to set the `autoCreateUser` to `true` to create the user if not present in the MapStore database: + +Here an example of the configuration, documented inline: ```properties @@ -65,7 +216,7 @@ googleOAuth2Config.clientSecret= # create the user if not present googleOAuth2Config.autoCreateUser=true -# Redirect URL +# Redirect URL (needs to be configured in the Google Console too) googleOAuth2Config.redirectUri=https:///mapstore/rest/geostore/openid/google/callback # Internal redirect URI (you can set it to relative path like this `../../..` to make this config work across domain) googleOAuth2Config.internalRedirectUri=https:///mapstore/ diff --git a/docs/developer-guide/mapstore-migration-guide.md b/docs/developer-guide/mapstore-migration-guide.md index 984100e0bb..2e9ce4d813 100644 --- a/docs/developer-guide/mapstore-migration-guide.md +++ b/docs/developer-guide/mapstore-migration-guide.md @@ -20,6 +20,35 @@ This is a list of things to check if you want to update from a previous version - Optionally check also accessory files like `.eslinrc`, if you want to keep aligned with lint standards. - Follow the instructions below, in order, from your version to the one you want to update to. +## Migration from 2024.01.00 to 2024.02.00 + +### Integration with openID Connect + +A generic OpenID Connect (OIDC) authentication support has been introduced in MapStore. This feature allows to authenticate users using an OIDC provider, like Keycloak, Okta, Google, Azure, etc. + +To provide this functionality, it is necessary to update the project's `geostore-spring-security.xml` file, if the default one is not used. +If you are using the default one, you can skip this step. + +Here the changes to apply if needed: + +```diff +@@ -24,6 +24,7 @@ + + + ++ + + + +@@ -52,6 +53,7 @@ + + + ++ + + +``` + ## Migration from 2023.02.02 to 2024.01.00 ### TOC plugin refactor @@ -33,7 +62,7 @@ The table of content (TOC) has been refactored with following changes: - `activateQueryTool` removed property, now the button will be directly added by `FilterLayer` plugin, when available - `activateDownloadTool` removed property, now the button will be added directly from `LayerDownload` when available - `activateMetedataTool` removed property, now the button will be added directly from `MetadataInfo` when availables - - `checkPlugins` remove property, now availability of tools rely on the related plugin so this check is not needed anymore + - `checkPlugins` remove property, now availability of tools rely on the related plugin so this check is not needed anymore - `showFullTitleOnExpand` removed property, the new style allows for seeing the full title inline without duplicating it - `metadataTemplate` this configuration has been moved to `MetadataInfo` plugin - `metadataOptions` this configuration has been moved to `MetadataInfo` plugin diff --git a/product/config/db/geostore-spring-security-db.xml b/product/config/db/geostore-spring-security-db.xml index 02e4cdd834..1b7a90bc60 100644 --- a/product/config/db/geostore-spring-security-db.xml +++ b/product/config/db/geostore-spring-security-db.xml @@ -24,6 +24,7 @@ + @@ -50,9 +51,13 @@ - + + + + +