Configuring JAAS Modules for transient users

While enabling transient users in HCL Digital Experience (DX) Compose allows external OpenID Connect (OIDC) users to log in, custom Java Authentication and Authorization Service (JAAS) login modules can provide further integration. This topic provides the steps to enable your own JAAS modules for transient users using HCL-provided samples. For the sample modules deployment instructions, an Auth0 account using the Default App values is configured.

Sample code disclaimer

The JAAS login modules described (HCLDummyJAASSimpleAuth0 and HCLDummyJAASGroupsAuth0) are provided as samples for proof-of-concept and testing purposes only. They have not been fully evaluated for security vulnerabilities. Any implementation based on this sample code should undergo thorough security analysis and testing prior to use in a production environment. You will need to customize them to fit your selected OIDC provider and specific security and attribute or group mapping requirements.

Prerequisites

Ensure that OIDC authentication is already enabled and configured in your HCL DX Compose deployment. For more details, refer to Configuring DX Compose to use an OIDC identity provider.
Ensure that transient users are already enabled and configured in your HCL DX Compose deployment. For more details, refer to Configuring transient users in DX Compose with OpenID Connect.
Ensure you have built a custom WebEngine image with the HCL provided sample JAAS modules. For more details, refer to Customizing the HCL DX Compose WebEngine image.

For the sample deployment, the following Dockerfile contents were used to build the custom image:

    # Dockerfile contents:

FROM oci://hclcr.io/dx-compose/hcl-dx-deployment/webengine:CF228_20250516-1642_34573

# Copy the custom modules into the customized image
COPY --chown=dx_user:dx_users ./HCLDummyJAASSimpleAuth0LoginModule.jar /opt/openliberty/wlp/usr/servers/defaultServer/customPlugins/HCLDummyJAASSimpleAuth0LoginModule.jar

COPY --chown=dx_user:dx_users ./HCLDummyJAASGroupsAuth0LoginModule.jar /opt/openliberty/wlp/usr/servers/defaultServer/customPlugins/HCLDummyJAASGroupsAuth0LoginModule.jar

# Copy any necessary additional files that are required by the custom jars into the customized image
COPY --chown=dx_user:dx_users ./auth0_opInfo.json /opt/openliberty/wlp/usr/servers/defaultServer/customPlugins/opInfo.json

The Docker build command for this sample deployment is as follows:

```
docker -D build --no-cache=true --progress=plain -t <my_custom_repository>/webengine:<my_custom_tag> .
```

Enabling HCL sample JAAS modules in DX Compose

This section describes how to deploy and configure two sample JAAS login modules:

HCLDummyJAASSimpleAuth0: This module provides mapping of common attributes for a transient user.
HCLDummyJAASGroupsAuth0: In addition to attribute mapping, this module has the ability to assign a transient user to pre-configured DX groups.

Follow these steps to enable the HCL sample JAAS modules in your DX Compose deployment:

Fetch the current configuration values from the running Helm release to ensure you preserve existing settings while adding the JAAS module configuration. Run the following command:
```
helm get values dx-deployment -n dxns -o yaml -a > custom-values-all.yaml
```
Replace dx-deployment with your Helm release name and dxns with your namespace if they differ. This command saves the current values to a file named custom-values-all.yaml.

In the custom-values-all.yaml file, add or modify the following section to enable and configure the HCL sample JAAS Modules in your HCL DX Compose deployment. For more information, see Configuration changes using overrides and Updating DX properties using Helm values.

The HCLDummyJAASSimpleAuth0 module focuses on mapping essential user attributes from the OIDC token (ID token or UserInfo endpoint) to the JAAS Subject. This module makes these attributes available within the DX session. Typically mapped attributes include unique ID, username, email, and full name.

images:
  tags:
    webEngine: my_custom_tag
configuration:
  webEngine:
    configOverrideFiles:
      jaas-simple-overrides.xml: |
        <server description="HCL Dummy JAAS Simple Overrides">
          <jaasLoginModule id="HCLDummyJAASSimpleAuth0LoginModule" className="com.hcl.HCLDummyJAASSimpleAuth0" controlFlag="REQUIRED" libraryRef="customPluginsLib">
            <!-- options debug="true" / -->
          </jaasLoginModule>
          <jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" loginModuleRef="HCLDummyJAASSimpleAuth0LoginModule, hashtable" />
        </server>

This configuration enables the HCL DX Compose deployment to utilize enhanced functionality for your transient users by mapping additional user attributes from the OIDC provider to the DX user session.

The HCLDummyJAASGroupsAuth0 module extends the functionality of HCLDummyJAASSimpleAuth0. Besides attribute mapping, it allows you to assign transient users to one or more DX groups based on information present in the OIDC claims (for example, a groups or roles claim). This is useful for controlling access to DX resources (pages, portlets, content) based on group memberships derived from the external OIDC provider without needing to manage these memberships directly in DX for transient users.

images:
  tags:
    webEngine: my_custom_tag
configuration:
  webEngine:
    configOverrideFiles:
      jaas-group-overrides.xml: |
        <server description="HCL Dummy JAAS Group Overrides">
          <jaasLoginModule id="HCLDummyJAASGroupsAuth0LoginModule" className="com.hcl.HCLDummyJAASGroupsAuth0" controlFlag="REQUIRED" libraryRef="customPluginsLib">
            <!-- options debug="true" / -->
            <options opInfoPath="/opt/openliberty/wlp/usr/servers/defaultServer/customPlugins/opInfo.json"/>
          </jaasLoginModule>
          <jaasLoginContextEntry id="system.WEB_INBOUND" name="system.WEB_INBOUND" loginModuleRef="HCLDummyJAASGroupsAuth0LoginModule, hashtable" />
        </server>
      user-overrides.xml: |
        <server descriptions="HCL JAAS User Overrides">
          <basicRegistry id="basic" realm="defaultWIMFileBasedRealm">
            <group id="cn=testRole01,o=defaultWIMFileBasedRealm" name="testRole01" />
          </basicRegistry>
        </server>
    propertiesFilesOverrides:
      PACGroupManagementService.properties:
        accessControlGroupManagement.useWSSubject: "true"

This configuration enables the HCL DX Compose deployment to utilize enhanced functionality for your transient users. This includes mapping additional user attributes from the OIDC provider to the DX user session, or assigning transient users to specific DX groups based on OIDC claims.

Use the following helm upgrade command to apply the updated configuration. Include both the base values file and the modified custom-values-all.yaml file.
```
helm -n dxns upgrade dx-deployment ./install-hcl-dx-deployment/ -f install-deploy-values.yaml -f custom-values-all.yaml
```
- Replace dxns with your namespace, and adjust the paths to install-hcl-dx-deployment and the values files (install-deploy-values.yaml and custom-values-all.yaml) according to your environment.
- The -f flags specify the base configuration (install-deploy-values.yaml) and the updated configuration (custom-values-all.yaml).
For more information, see Upgrading the Helm deployment.