fews-web-oc

Keycloak

The following example explains how the Delft-FEWS Web OC and Delft-FEWS WebServices can be configured to support OIDC. The keycloak docker image will be used. See also the Keycloak documentation for more information.

In this example we assume that the Delft-FEWS Web OC and Delft-FEWS WebServices are running on the same server: http://localhost:8080 for the Web OC and http://localhost:8080/FewsWebServices/ for the Delft-FEWS Web Services.

Keycloak will be running on http://localhost:8888.

docker run -p 8888:8080 -d -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.0.1 start-dev

After starting the Keycloak docker image, the Keycloak admin console can be accessed at http://localhost:8888/auth/admin.

Create a new realm, for example: weboc.

realm

Create a new client, for example: weboc-client-id.

client

Select the default client capabilities:

capabilities

For the login settings, the following need to be set:

login-settings

Create a new user, for example: weboc.

create-user

Set the password for the user weboc.

set-password

If keycloak has been set up as described, it is now possible to login to the Delft-FEWS Web OC with the user weboc. The only thing that is required is to update the Web OC configuration file: app-config.json.

In the app-config.json file of the Delft-FEWS Web OC, the following OIDC properties have to be set:

{
  "VITE_FEWS_WEBSERVICES_URL": "http://localhost:8080/FewsWebServices/",
  "VITE_AUTH_AUTHORITY": "http://localhost:8888/auth/realms/weboc",
  "VITE_AUTH_METADATA_URL": "http://localhost:8888/realms/weboc/.well-known/openid-configuration",
  "VITE_AUTH_ID": "weboc-client-id",
  "VITE_AUTH_SCOPE": "openid profile email",
  "VITE_REQUEST_HEADER_AUTHORIZATION": "Bearer"
}

If you now open the Delft-FEWS Web OC in the browser (http://localhost:8080), a login screen will appear.

login

After clicking the login button, you will be redirected to the Keycloak login page.

keycloak-login

After logging in, you will be redirected back to the Delft-FEWS Web OC. On the top left you can see you are logged in. Here it is also possible to logout.

weboc-profile

Groups

For integration with the WebServices UserGroups and Permissions, group memberships have to be passed in an access token to the Delft-FEWS WebServices.

In keycloak groups can be configured in the Groups section:

This can be done by adding the following mapper to the client in Keycloak:

In the weboc-client-id client, select Client Scopes and selected the weboc-client-id-dedicated client scope.

dedicated-scope

Here a mapper can be configured. Chose: Configure a new mapper and select Group Membership.

group-membership-mapper

Create a claim called groups and make sure it is added to the access token and id token. Disable Full group path. It should be Off.

custom-mapper-groups

This will make sure that the groups are passed in the access token. The access token will contain the groups claim with all groups a user is member off.

access_token

Web Services OIDC Configuration

For the Delft-FEWS WebServices to accept the access token, please refer to the following documentation: https://publicwiki.deltares.nl/display/FEWSDOC/FEWS+Web+Services+Security+with+Open+ID+Connect

N.B.: OIDC integration is NOT supported when using embedded tomcat. The Delft-FEWS WebServices should be deployed on a separate tomcat server.

For this example, the following configuration environment variables are required:

Delft Fews Configuration

To use permissions, they need to be enabled in the PiServiceConfigFiles/WebServices.xml configuration of Delft-FEWS For example:

<?xml version="1.0" encoding="utf-8"?>
<webServices xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			 xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/webServices.xsd">
	<general>
        <readonlyMode>false</readonlyMode>
		<permissions>
			<enablePermissions>true</enablePermissions>
		</permissions>
	</general>
</webServices>

Suppose we want to have a WebOC permission that applies to the WebOC user group. In the SystemConfigFiles/UserGroups.xml the following configuration can be added, where the systemUserGroup should match the group name in Keycloak. In this example we assume there is a keycloak group called: WEBOC_USER

<?xml version="1.0" encoding="UTF-8"?>
<userGroups xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/userGroups.xsd">
    <userGroup id="WebOC">
        <systemUserGroup id="WEBOC_USER"></systemUserGroup>
    </userGroup>
</userGroups>

In the SystemConfigFiles/Permissions.xml the following configuration can be added, where the WebOC permission is defined.

<?xml version="1.0" encoding="UTF-8"?>
<permissions xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/permissions.xsd">
	<permission id="WebOC">
		<userGroup id="WebOC"></userGroup>
	</permission>
</permissions>

Finally, the permissions can be applied to the relevant parts in the Delft-FEWS configuration. For example in the Topolgy.xml file certain nodes can be made available using the webOC permission. If no permissions are applied to a node, they will be available to the Web OC as well.

<?xml version="1.0" encoding="UTF-8"?>
<topology xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/topology.xsd">
	<nodes id="Information_Sources" name="Information Sources">
        .....    
		<nodes id="Delft-FEWS">
			<viewPermission>WebOC</viewPermission>
		</nodes>
        ......
</topology>

If setup correctly only the topoloyg nodes that a Web OC user has permissions for are displayed to the logged in user.

This site is open source. Improve this page.