SSO Migration - MapStore doc and support

[offtherailz]

Related to geosolutions-it/geostore#525 (comment)

In geostore 2.6.x we introduced a refactor of OIDC support. This will need probably a migration due to the switch to next version of spring.

With this issue we take note that we have the folloiwing points to review:

• all points in SSO - Maintainance investigation geostore#525 (comment) expecially on removal or maintainance of certain functionalities
• provide proper migration guidelines
• provide proper documentation

Here reporting some information to support this future version.

New configurations

To document properly the new documentation, here I report some configurations valid for geostore 2.6.x that have to be reviewed when going to use it in mapstore and / or migrate in 1.7.x with spring

MapStore configuration

to configure ms to use oidc we need to change 2 files, localConfig.json and mapstore-ovr.properties

This is the configuration used for testing on MapStore

localConfig.json setup

here the sample configurations to use (one for each element). Old documentation for this part should still be valid. New attribute is showAccountInfo , to force to show the groups of the user for the given provider,. in user menu.

{
"authenticationProviders": [
      {
        "type": "openID",
        "provider": "azure",
        "showAccountInfo": true,
        "title": "azure"
      },{
        "type": "openID",
        "provider": "keycloak",
        "showAccountInfo": true,
        "title": "keycloak"
      },{
        "type": "openID",
        "provider": "oidc",
        "showAccountInfo": true,
        "title": "oidc"
      },
      {
        "type": "basic",
        "provider": "geostore"
      }
    ],
}

This configuration is taken from this PR review

Configurations for single and multiclient

### Azure test

template file for test

# -----------------------------------------------
# Azure AD / Entra ID — OpenID Connect Configuration
# -----------------------------------------------
oidcOAuth2Config.enabled=true
# Azure AD App Registration — Client credentials
oidcOAuth2Config.clientId=[...]
oidcOAuth2Config.clientSecret=[...]
# Discovery URL (multi-tenant endpoint)
oidcOAuth2Config.discoveryUrl=https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration
oidcOAuth2Config.sendClientSecret=true
# Scopes — openid is required for ID tokens; email and profile for user claims
oidcOAuth2Config.scopes=openid,email,profile,offline_access
# Auto-create users in GeoStore DB on first OIDC login  <---
oidcOAuth2Config.autoCreateUser=true
# OAuth2 redirect URI — must match the redirect URI registered in Azure AD
oidcOAuth2Config.redirectUri=http://localhost:8081/rest/geostore/openid/oidc/callback
# After successful login, redirect the browser to the MapStore frontend
oidcOAuth2Config.internalRedirectUri=http://localhost:8081/
# Username claim — preferred_username is more reliable than email on Azure AD
oidcOAuth2Config.principalKey=preferred_username
# Role mapping from Azure AD App Roles (flat "roles" claim)
oidcOAuth2Config.rolesClaim=roles

# Group mapping from Azure AD group claim
oidcOAuth2Config.groupsClaim=groups

# Enable OIDC RP-Initiated Logout
oidcOAuth2Config.globalLogoutEnabled=true

# DEBUG — enable sensitive logging to see token exchange details
oidcOAuth2Config.logSensitiveInfo=true

Multiprovider

test template

# Declare 3 providers
oidc.providers=keycloak,google,azure

# -----------------------------------------------
# Provider 1: Keycloak (corporate identity)
# -----------------------------------------------
keycloakOAuth2Config.enabled=true
keycloakOAuth2Config.clientId=[...]
keycloakOAuth2Config.clientSecret=[...]
keycloakOAuth2Config.discoveryUrl=[...]
keycloakOAuth2Config.redirectUri=http://localhost:8081/rest/geostore/openid/keycloak/callback
keycloakOAuth2Config.internalRedirectUri=../../mapstore/
keycloakOAuth2Config.autoCreateUser=true
keycloakOAuth2Config.principalKey=email
keycloakOAuth2Config.scopes=openid,email,profile
keycloakOAuth2Config.rolesClaim=realm_access.roles
keycloakOAuth2Config.roleMappings=realm_admin:ADMIN,realm_user:USER

# -----------------------------------------------
# Provider 2: Google (external users)
# -----------------------------------------------
googleOAuth2Config.enabled=true
googleOAuth2Config.clientId=[...]
googleOAuth2Config.clientSecret=[...]
googleOAuth2Config.discoveryUrl=[...]
googleOAuth2Config.redirectUri=hhttp://localhost:8081/rest/geostore/openid/google/callback
googleOAuth2Config.internalRedirectUri=../../mapstore/
googleOAuth2Config.autoCreateUser=true
googleOAuth2Config.principalKey=email
googleOAuth2Config.scopes=openid,email,profile
googleOAuth2Config.sendClientSecret=true
googleOAuth2Config.accessType=offline
googleOAuth2Config.authenticatedDefaultRole=USER

# -----------------------------------------------
### Provider 3: Azure (external users)
# -----------------------------------------------
# -----------------------------------------------
# Azure AD / Entra ID — OpenID Connect Configuration
# -----------------------------------------------
azureOAuth2Config.enabled=true

# Azure AD App Registration — Client credentials
azureOAuth2Config.clientId=[...]
azureOAuth2Config.clientSecret=[...]

# Discovery URL (multi-tenant endpoint)
azureOAuth2Config.discoveryUrl=[...]

# Send client_secret in the token request body (required for Azure AD confidential clients)
azureOAuth2Config.sendClientSecret=true

# Scopes — openid is required for ID tokens; email and profile for user claims
azureOAuth2Config.scopes=openid,email,profile,offline_access

# Auto-create users in GeoStore DB on first azure login
azureOAuth2Config.autoCreateUser=true
azureOAuth2Config.authenticatedDefaultRole=USER

# OAuth2 redirect URI — must match the redirect URI registered in Azure AD
azureOAuth2Config.redirectUri=http://localhost:8081/rest/geostore/openid/azure/callback

# After successful login, redirect the browser to the MapStore frontend
azureOAuth2Config.internalRedirectUri=http://localhost:8081/

# Username claim — preferred_username is more reliable than email on Azure AD
azureOAuth2Config.principalKey=preferred_username

# Microsoft Graph resolver for Azure AD App Groups and Roles
azureOAuth2Config.msGraphEnabled=true
azureOAuth2Config.msGraphRolesEnabled=true
azureOAuth2Config.msGraphGroupsEnabled=true
# Role mapping from Azure AD App Roles (flat "roles" claim)
azureOAuth2Config.rolesClaim=roles

# Group mapping from Azure AD group claim
azureOAuth2Config.groupsClaim=groups

# Enable azure RP-Initiated Logout
azureOAuth2Config.globalLogoutEnabled=true

Draft migration guidelines

we will need to provide some migration guidelines. Here a draft, that need to be reviewed and to be linked to the new documentation. Includes also a list, to review too, of things that has been discontinued

Migration guidelines section

Spring security refactor for OIDC

To improve and modernize the OIDC support for MapStore, geostore-spring-security.xml and the applicationContext.xml file of your project have to be updated. We suggest to align this file even if you don't use this feature, to be aligned also with future updates.

note: from this version, the following features will be discontinued:

• keycloak seamless SSO (automatic login) has been discontinued, because it can not be supported natively with standard security.
• keycloak user integration

Setup geostore-spring-security.xml

Basically you will have to :

• replace security:custom filters service dedicated, with the generic one
• replace old service dedicated beans with the new ones (3 beans, filter, register and configuration) that supports multiple providers.

In case you are using OIDC, to update your configuration, you will have to check the new configuration TODO.

@@ -22,8 +22,7 @@
         <security:csrf disabled="true"/>
         <security:custom-filter ref="authenticationTokenProcessingFilter" before="FORM_LOGIN_FILTER"/>
         <security:custom-filter ref="sessionTokenProcessingFilter" after="FORM_LOGIN_FILTER"/>
-        <security:custom-filter ref="keycloakFilter" before="BASIC_AUTH_FILTER"/>
-        <security:custom-filter ref="googleOpenIdFilter" after="BASIC_AUTH_FILTER"/>
+        <security:custom-filter ref="compositeOpenIdFilter" before="OPENID_FILTER"/>
         <security:anonymous />
     </security:http>

@@ -52,12 +51,10 @@
     <!-- OAuth2 beans -->
     <context:annotation-config/>

-    <bean id="googleSecurityConfiguration" class="it.geosolutions.geostore.services.rest.security.oauth2.google.OAuthGoogleSecurityConfiguration"/>
-
-    <!-- Keycloak -->
-
-    <bean id="keycloakConfig" class="it.geosolutions.geostore.services.rest.security.keycloak.KeyCloakSecurityConfiguration"/>
-
+    <!-- OAuth2 beans -->
+    <bean id="oidcSecurityConfiguration" class="it.geosolutions.geostore.services.rest.security.oauth2.openid_connect.OpenIdConnectSecurityConfiguration"/>
+    <bean id="oidcProviderRegistrar" class="it.geosolutions.geostore.services.rest.security.oauth2.openid_connect.OpenIdConnectProviderRegistrar"/>
+    <bean id="compositeOpenIdFilter" class="it.geosolutions.geostore.services.rest.security.oauth2.openid_connect.CompositeOpenIdConnectFilter"/>
     <!-- END OAuth2 beans-->

     <!--  security integration inclusions  -->

Setup applicationContext.xml

The applicationContext.xml (usually located in web/src/main/resources/) have to be updated adding a line to the bean for the property ignoreInvalidKeys.
This is needed to support multiple OIDC providers.

 <!-- Allows getting database configuration also from the data-dir -->
    <bean class="org.springframework.beans.factory.config.PropertyOverrideConfigurer">
        <property name="ignoreResourceNotFound" value="true"/>
+        <property name="ignoreInvalidKeys" value="true"/>
        <property name="order" value="10"/>
        <property name="locations">
            <list>
                <value>classpath:mapstore-ovr.properties</value>
                <value>file:${datadir.location:}/geostore-datasource-ovr.properties</value>
                <value>file:${datadir.location:}/mapstore-ovr.properties</value>
            </list>
        </property>
    </bean>

Update configurations

If you have a setup that integrates OIDC (keycloak, azure, google ...) you should update your configurations on client and server side to adapt to the new implementation. You can find a reference about how to configure OIDC in the relative OIDC section of this documentation.