Since 2022.01 it is possible to configure the integrate the FEWS Web Service with OIDC (Open ID Connect). It is also possible to integrate the Delft-FEWS Groups and Permissions configurations with OIDC.
Introduction
OIDC is used by many cloud providers to authenticate application. Examples are:
MS Entry ID: https://docs.microsoft.com/nl-nl/azure/active-directory/develop/v2-oauth2-auth-code-flow
AWS Cognito: https://aws.amazon.com/cognito/
The Web Services can authenticate against these OIDC provider, but only MS Entry ID has been fully tested. Other providers may work as well, but have not been tested yet.
General Configuration
To configure the Web Services to use OAuth2/OIDC authentication, the following ENV variables need to be set when starting the Delft-FEWS Web Services.
| Environment Variable | Description | Value |
|---|---|---|
| FEWS_WS_AUTHENTICATION_TYPE | To enable Oauth2 with OIDC, this ENV variable is required. | AuthenticationOpenIdConnect |
| FEWS_WS_AUTHENTICATION_OAUTH2_KEYS_URI | Provider specific URI that is used to get public certificates to validate JWT tokens. ENV is required if FEWS_WS_AUTHENTICATION_TYPE is configured with value AuthenticationOpenIdConnect. | MS Entry ID: https://login.microsoftonline.com/<tenantid>/discovery/v2.0/keys |
| FEWS_WS_AUTHENTICATION_EDITOR_GROUPS | Optional ENV variable. List of groups that have edit permissions to the Web Services. If the provided JWT token containes a roles claim with one of the configured groups, access to all HTTP endpoints is allowed. Recommended name is: WS_EDITOR | One or more application roles, comma seprated. In Azure AD theres are typically configured in an App Registration. |
| FEWS_WS_AUTHENTICATION_VIEWER_GROUPS | Optional ENV variable. List of groups that have view permissions to the Web Services. If the proveded JWT token containes a roles claim with one of the configured groups, only access to GET HTTP endpoints is allowed. Recommended name is: WS_VIEWER | One or more application roles, comma seprated. In Azure AD theres are typically configured in an App Registration. |
| FEWS_WS_AUTHENTICATION_OAUTH2_USER_INFO_URI | Userinfo URL that can be used to determine email address of user. Only to be used if access token doesn't contain email address. For Microsoft Entra ID this ENV variable is obsolete and shouldn't be set, since the email adres is set in the access token. | https://my-identity-provider/oidc/userinfo |
If either FEWS_WS_AUTHENTICATION_ADMIN_GROUPS or FEWS_WS_AUTHENTICATION_VIEWER_GROUPS has been configured it is required to have roles in the JWT token to be able to access the Web Services. These groups are intended to have a high level role based access control if only authentication isn't sufficient. For fine grained access control, integration with UserGroups and Permissions can be used.
Seamless Integration with OIDC protected Archive Server (since 2024.01)
In case the Web Services is configured to use an Archive for seamless integration and the Archive Server is protected with Open ID Connect as well, some extra configuration is required. The Web Service will use a Oauth2 client credentials flow (https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow) to acquire a JWT token that can be passed to the Archive Server backend. This client needs at lease the ARCHIVE_USER and ARCHIVE_EDITOR roles.
For more information on integrating with the Archive, please see: Deltares Open Archive Open ID Connect integration. For general information of integrating different Delft-FEWS system with Open ID Connect in Azure, please see: Open ID Connect Security with Microsoft Entra ID.
| Environment Variable | Description | Value |
|---|---|---|
| FEWS_WS_AUTHENTICATION_OAUTH2_CLIENT_ID | To client id of the app registration that can perform a client credentials flow | bacfc428-xxxx-xxxx-xxxx-7b1bc7b4ce06; |
| FEWS_WS_AUTHENTICATION_OAUTH2_CLIENT_SECRET | Secret of the client that can perform a client credentials flow. | iTDcHXXXXXXXXXXXXXXXXXqKp3o= |
| FEWS_WS_AUTHENTICATION_OAUTH2_SCOPE | Scope that is allowed to access the Archive API. Typically the Backend APIs of Delft-FEWS are provided in a seperate app registration and exposes the API with a scope. | api://api-client-id/.default |
| FEWS_WS_AUTHENTICATION_OAUTH2_TOKEN_URI | URI of the open id connect endpoint that can be used to request a JWT token that can be passed to the Archive Server | MS Entra ID: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token |
Tomcat header size
When using OAuth2 with OIDC, it is recommended to increase the max header size accepted by Tomcat. In case a proxy server is used in front of Tomcat the proxy server might need some adjustments as well. Authentication tokens are sent as http headers and can become quite large. To configure this in Tomcat, adjust the HTTP connector of tomcat in the server.xml. In the following example the maxHeader size is set to 10MB.
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" maxHttpHeaderSize="10000000"/>
UserGroups and Permissions
It is possible to integrate with the UserGroups and Permissions. First of all the following property has to be set in the FEWS WebServices Configuration File file in the general section:
<enablePermissions>true</enablePermissions>
Once enabled, it is possible to use roles that are part of the JWT claim, and add them as part of a userGroup.
For example in the following userGroups configuration, the FEWS_FORECASTER systemUserGoups is added as part of the userGroup FewsWebServicesPrivateGroup. If the FEWS_FORECASTER is availble in the JWT token as a roles claim, the Delft-FEWS Web Services will be given the permissions that are assigned to the FewsWebServicesPrivateGroup.
<?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 http://fews.wldelft.nl/schemas/version1.0/userGroups.xsd"> <userGroup id="FewsWebServicesPrivateGroup"> <systemUserGroup id="FEWS_FORECASTER"/> </userGroup> </userGroups>
In the permissions file, a permission can be configured and used in the Delft-FEWS configurations. In the following example a permission with id FewsWebServicesPrivatePermissions is configured and assigend to the FewsWebServicesPrivateGroup.
<?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 http://fews.wldelft.nl/schemas/version1.0/permissions.xsd"> <permission id="FewsWebServicesPrivatePermissions"> <userGroup id="FewsWebServicesPrivateGroup"/> </permission> </permissions>
Usage
Typical usage is when using a single page web application that needs to authenticate a user against the Delft-FEWS Web Services.
Once the web application has logged in, a JWT access token has been provided to the web application. The access token has to be sent to the Delft-FEWS Web Services with every HTTP request as a Bearer token in the Authorization header, similar to the follow example:
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1yNS ..... nztNqRzWw
A decoded access token might look as follows (using a tool like https://jwt.io/:
In this example a FEWS_FORECASTER role was assigned in as a claim.
Groups mapped in Admin Interface
it is also possible to map users to groups using the admin interface. The email address that is used in the access token that is sent to the Delft-FEWS Web Services, is used to lookup users in the database. If no user with this emails address was found a new user will be created in the database. If no email address is available (like in the client credential flow), no user registration is done.
If a user was found, the assigned groups will be used to determine the assigned permissions as described in the "UserGroups and Permissions" section.
