update keycloak documentation (#8575)

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

@@ -81,12 +81,10 @@ Here implementation details about [keycloak login workflow](keycloak-sso-impl.md
 
 By default MapStore can integrate openID login with Keycloak and also supports integration with Keycloak SSO.
 
-By default users that login with Keycloak are created on the database.
+By default users that login with Keycloak are created on the database and their Keycloak roles inserted as MapStore UserGroup.
 Anyway MapStore can interact with Keycloak REST API to provide a direct integration without persisting anything on the MapStore's database.
 This provides a stricter integration between the applications, allowing the assignment of roles and groups directly from keycloak, and avoiding any synchronization issue.
 
-This is actually the only way to map keycloak roles to MapStore groups.
-
 In this scenario the integration MapStore replaces the user and user-group database tables with the keycloak REST API.
 
 !!! note
@@ -121,7 +119,14 @@ And click on Save.
 
 #### 2. Configure `mapstore-ovr.properties`
 
-moreover in `mapstore-ovr.properties` you have to add the following information (replacing `<keycloak-base-url>` with your base keycloak base url):
+
+The `autoCreateUser` option must be set to false in `mapstore-ovr.properties`.
+
+```properties
+keycloakOAuth2Config.autoCreateUser=false
+```
+
+Moreover in `mapstore-ovr.properties` you have to add the following information (replacing `<keycloak-base-url>` with your base keycloak base url):
 
 ```properties
 ## Keycloak as User and UserGroup repository
@@ -140,11 +145,12 @@ Where:
 
 !!! note
     <sup>1</sup> In order to query the keycloak REST API, you need to have in your realm at least one user with
-    `view-users` role permission. Usually the administrator of the realm has these permission. To associate these
-    permissions to a new user dedicated to this purpose you have to open "Role Mappings" tab of keycloak and in "Client
-    Roles" select `realm-management` (or in master realm select `master-realm`), add to selected at least `view-users`.
+    `realm-admin` role permission. Usually the administrator of the realm has these permission. To associate these
+    permissions to a new user dedicated to this purpose, you have to open "Role Mappings" tab of keycloak and in "Client
+    Roles" select `realm-management` (or in master realm select `master-realm`) and add to selected `realm-admin`.
     <img src="../img/kc-role-view-user.jpg" class="ms-docimage" style="max-width: 500px" />
 
+
 #### 3. Activate the functionality via system property
 
 In order to activate the integration in your instance, you will need to set the [Java System Property](https://www.ibm.com/docs/en/sdk-java-technology/7?topic=customization-how-specify-javalangsystem-property) `security.integration`  with the value `keycloak-direct`.

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

@@ -143,17 +143,22 @@ keycloakOAuth2Config.autoCreateUser=true
 # Comma separated list of <keycloak-role>:<geostore-role>
 keycloakOAuth2Config.roleMappings=admin:ADMIN,user:USER
 
+# Comma separated list of <keycloak-role>:<geostore-group>
+keycloakOAuth2Config.roleMappings=MY_KEYCLOAK_ROLE:MY_MAPSTORE_GROUP,MY_KEYCLOAK_ROLE2:MY_MAPSTORE_GROUP2
+
 # Default role, when no mapping has matched
 keycloakOAuth2Config.authenticatedDefaultRole=USER
 ```
 
 - `keycloakOAuth2Config.jsonConfig`: insert the JSON copied, removing all the spaces
 - `keycloakOAuth2Config.redirectUri`: need to be configured to point to your application at the path `<base-app-url>/rest/geostore/openid/keycloak/callback`, e.g. `https://my.mapstore.site.com/mapstore/rest/geostore/openid/keycloak/callback`
 - `keycloakOAuth2Config.internalRedirectUri` can be set to your application root, e.g. `https://my.mapstore.site.com/mapstore/`
-- `keycloakOAuth2Config.autoCreateUser`: true if you want to create user on DB on login (if you are not using any other user integration e.g. `ldap`, `keycloak`)
+- `keycloakOAuth2Config.autoCreateUser`: true if you want MapStore to insert a Keycloak authenticated user on the DB. UserGroups will be inserted as well and kept in synch with the roles defined for the user in Keycloak. The option **must be set to false if MapStore is using a read-only external service for users and groups** (i.e. Keycloak or LDAP).
 - `keycloakOAuth2Config.forceConfiguredRedirectURI`: optional, if `true`, forces the redirect URI for callback to be equal to teh redirect URI. This is useful if you have problems logging in behind a proxy, or in dev mode.
-- `keycloakOAuth2Config.roleMappings`: comma separated list of mappings, to map keycloak roles to mapstore roles. Allowed values `USER` or `ADMIN`
+- `keycloakOAuth2Config.roleMappings`: comma separated list of mappings with the following format ``keycloak_admin_role:ADMIN,keycloak_user_role:USER``. These mappings will be used to map Keycloak roles to MapStore roles. Allowed values `USER` or `ADMIN`.
 - `keycloakOAuth2Config.authenticatedDefaultRole`: where the role has not been assigned by the mappings above, the role here will be used. Allowed values `USER` or `ADMIN`.
+- `keycloakOAuth2Config.groupMappings`: comma separated list of mappings with the following format ``keycloak_role_name:mapstore_group_name,keycloak_role_name2:mapstore_group_name2``. These mappings will be used to map Keycloak roles to MapStore groups.
+- `keycloakOAuth2Config.dropUnmapped`: when set to false, MapStore will drop Keycloak roles that are not matched by any mapping role and group mapping. When set to true all the unmatched Keycloak roles will be added as MapStore UserGroups.