From 0e6a3cedd696f1926555792dd9daf2ae34c17e10 Mon Sep 17 00:00:00 2001 From: ekkelenkamp Date: Thu, 24 Oct 2024 14:11:11 +0200 Subject: [PATCH] Documented configuring groups in keycloak and use them in the Web Services. --- docs/public/oidc/keycloak/README.md | 80 ++++++++++++++++++++++++----- 1 file changed, 68 insertions(+), 12 deletions(-) diff --git a/docs/public/oidc/keycloak/README.md b/docs/public/oidc/keycloak/README.md index 21a39daf..835ef6c1 100644 --- a/docs/public/oidc/keycloak/README.md +++ b/docs/public/oidc/keycloak/README.md @@ -1,8 +1,8 @@ ## 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 to show how to configure. -Se also the [Keycloak documentation](https://www.keycloak.org/getting-started/getting-started-docker) for more information. +The keycloak docker image will be used. +See also the [Keycloak documentation](https://www.keycloak.org/getting-started/getting-started-docker) 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. @@ -32,7 +32,7 @@ For the login settings, the following need to be set: - Root URL (homepage of the web oc): http://localhost:8080 - Home URL (homepage of the web oc): http://localhost:8080 - Valid Redirect URIs: http://localhost:8080/auth/callback -- Valid Post Logout Redirect URIs: http://localhost:8080 +- Valid Post Logout Redirect URIs: http://localhost:8080/auth/logout - Web origins: + ![login-settings](./login-settings.png) @@ -47,7 +47,7 @@ Set the password for the user weboc. ![set-password](./create-password.png) 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 missing is the configuration of the app-config.json file of the Delft-FEWS Web OC. +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: @@ -57,12 +57,12 @@ In the app-config.json file of the Delft-FEWS Web OC, the following OIDC propert "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 offline_access", + "VITE_AUTH_SCOPE": "openid profile email", "VITE_REQUEST_HEADER_AUTHORIZATION": "Bearer" } ``` -If you now open the Delft-FEWS Web OC in the browser, a login screen will appear. +If you now open the Delft-FEWS Web OC in the browser (http://localhost:8080), a login screen will appear. ![login](./weboc-login.png) @@ -71,11 +71,10 @@ After clicking the login button, you will be redirected to the Keycloak login pa ![keycloak-login](./keycloak-login.png) 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. +On the top left you can see you are logged in. Here it is also possible to logout. ![weboc-profile](./weboc-profile.png) -Here it is also possible to logout. # Groups @@ -99,12 +98,12 @@ Chose: Configure a new mapper and select Group Membership. Create a claim called groups and make sure it is added to the access token and id token. -Disable Full group path is selected. +Disable Full group path. It should be Off. ![custom-mapper-groups](./custom-mapper-groups.png) This will make sure that the groups are passed in the access token. -In a decoded acccess token the groups will be available: +The access token will contain the groups claim with all groups a user is member off. ![access_token](./access_token.png) @@ -112,9 +111,10 @@ In a decoded acccess token the groups will be available: # 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: - FEWS_WS_AUTHENTICATION_TYPE: AuthenticationOpenIdConnect @@ -122,5 +122,61 @@ For this example, the following configuration environment variables are required - FEWS_WS_AUTHENTICATION_EDITOR_GROUPS: WS_EDITOR - FEWS_WS_AUTHENTICATION_VIEWER_GROUPS: WS_VIEWER -Take note that the weboc in the URL is the name of the realm that was created in Keycloak. +# Delft Fews Configuration + +To use permissions, they need to be enabled in the PiServiceConfigFiles/WebServices.xml configuration of Delft-FEWS +For example: + +```xml + + + + false + + true + + + +``` + +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 + + + + + + +``` + +In the SystemConfigFiles/Permissions.xml the following configuration can be added, where the WebOC permission is defined. + +```xml + + + + + + + +``` +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 + + + + ..... + + WebOC + + ...... + +``` + +If setup correctly only the topoloyg nodes that a Web OC user has permissions for are displayed to the logged in user. \ No newline at end of file