Skip to content

DX WebEngine Configuration Changes Using Overrides

Overview

This document provides detailed steps for updating the server.xml properties or for configuration using configOverrideFiles.

The snippets are merged into the Open Liberty server.xml file. After making changes to the respective values.yaml file, apply them by using the helm upgrade ... command. Open Liberty picks up and applies changes at runtime; this does not require a restart.

User / User Group through Configuration Overrides

Below is an example snippet of configuring DX WebEngine server to configure or override user or user group.

configOverrideFiles:
  user-overrides.xml: |
    <server description="DX WebEngine server"> 
      <basicRegistry id="basic" realm="defaultWIMFileBasedRealm"> 
        <user name="wpsadmin" password="newPass" />
        <user name="newuser1" password="password" />
        <group name="wpsadmins" id="cn=wpsadmins,o=defaultWIMFileBasedRealm">
          <member name="wpsadmin" />
        </group>
        <group name="nonadmins" id="cn=nonadmins,o=defaultWIMFileBasedRealm">
          <member name="newuser1" />
        </group>
      </basicRegistry> 
    </server>
Note: The name of the customization (user-overrides.xml in the example above) can be any string. However, it's beneficial for it to be descriptive of the changes it introduces. Note: To update the default admin username and password, refer to Updating the Default Admin Password.

SMTP Configuration through Configuration Overrides

Below is an example snippet of configuring DX WebEngine server to use a mail server. The smtphost will need to be replaced with the proper hostname of the mail server. If authentication is required to communicate with the mail server then replace smtpUser and smtpPassword with the correct values, otherwise remove those lines from the snippet.

configOverrideFiles:
  smtpOverride.xml: | 
    <server description="DX WebEngine server">
      <mailSession
        id="dxWebEngineMail"
        host="smtphost.com"
        from="no-reply@smtphost.com"
        jndiName="mail/BuilderMailSession"
        description="DX WebEngine MailSession"
        mailSessionID="dxWebEngineMail"
        user="smtpUser"
        password="smtpPassword">
          <property name="mail.smtp.auth" value="false" />
          <property name="mail.smtp.port" value="25" />
      </mailSession>
    </server>
Note: The name of the customization (smtpOverride in the example above) can be any string. However, it's beneficial for it to be descriptive of the changes it introduces.

SSL Configuration through Configuration Overrides

The Open Liberty may not trust default certificates. By providing this config setting, the default certificates will be trusted enabling communication with third-party services.

configOverrideFiles:
   sslOverride.xml: |
      <server description="DX WebEngine server">  
        <ssl id="defaultSSLConfig" trustDefaultCerts="true" />
      </server>
Note: The name of the customization (sslOverride in the example above) can be any string. However, it's beneficial for it to be descriptive of the changes it introduces.

LDAP Configuration through Configuration Overrides

Below is an example snippet for configuring the DX WebEngine server to use an OpenLDAP server. The baseDN, bindDN, bindPassword, and host will need to be replaced with the proper values.

For custom LDAP types, use customFilters to define your own search filters for users and groups. For predefined LDAP types supported by Open Liberty, use idsFilters. If your LDAP directory uses nested groups or hierarchical structures, consider enabling recursiveSearch to ensure all relevant entries are retrieved. For more information, refer to the Open Liberty LDAP Registry documentation.

The attributeConfiguration element in the LDAP registry configuration allows you to map LDAP attributes to user registry attributes. This is useful when the attribute names in your LDAP directory do not match the expected attribute names. Each attribute element specifies a mapping. name - The name of the attribute in the LDAP directory. propertyName - The name of the attribute to be mapped to. In the example below, LDAP mail attribute is mapped to ibm-primaryEmail, which is the attribute used to display email address of a user and LDAP title attribute is mapped to ibm-jobTitle, which is the attribute used to display job title of a user. 

configOverrideFiles:
  ldapOverride.xml: | 
    <server description="DX WebEngine server"> 
      <ldapRegistry id="ldap" realm="SampleLdapIDSRealm"
        host="127.0.0.1" port="1389" ignoreCase="true"
        baseDN="dc=dx,dc=com"
        ldapType="Custom"
        sslEnabled="false"
        bindDN="cn=dx_user,dc=dx,dc=com"
        bindPassword="p0rtal4u">
          <customFilters
            userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))"
            groupFilter="(&amp;(cn=%v)(objectclass=groupOfUniqueNames))"
            userIdMap="*:uid"
            groupIdMap="*:cn"
            groupMemberIdMap="groupOfUniqueNames:uniqueMember">
          </customFilters>
          <attributeConfiguration>
            <attribute name="mail" propertyName="ibm-primaryEmail" entityType="PersonAccount"/>
            <attribute name="title" propertyName="ibm-jobTitle" entityType="PersonAccount"/>
          </attributeConfiguration>
      </ldapRegistry>
      <federatedRepository>
        <primaryRealm name="FederatedRealm" allowOpIfRepoDown="true">
          <participatingBaseEntry name="o=defaultWIMFileBasedRealm"/>
          <participatingBaseEntry name="dc=dx,dc=com"/>
        </primaryRealm>
      </federatedRepository>
    </server>
Follow this document to set up a custom LDAP server in Liberty: Configuring LDAP with Liberty.

Security Hardening

Out of the Box cCnfiguration

Several out of the box security hardenings have been applied based on Security hardening for production: 

configOverrideFiles:
  securityOverride.xml: | 
    <server description="DX WebEngine server"> 
      <webAppSecurity httpOnlyCookies="true" trackLoggedOutSSOCookies="false"/>
      <httpDispatcher enableWelcomePage="false" />
      <httpOptions removeServerHeader="true" />
      <httpSession invalidateOnUnauthorizedSessionRequestException="true" cookieHttpOnly="true"/>
    </server>
Note: The trackLoggedOutSSOCookies setting, when enabled, ensures that if a user logs out from one browser, the same user will be required to log in again if they try to access the resource from another browser. This setting helps prevent session replay attacks by marking the LTPA cookie as invalid upon logout. However, it can impact your SSO scenarios. For example, if a user logs in from multiple browsers to the same server and logs out from one browser, they will need to log in again if they try to access the resource from another browser. As a result, it is set to false by default but can be enabled for production environments.

To allow http access for developer setups with the docker image, SSL only has not been enforced. For a production setup one might apply the following as server.xml override: 

  configOverrideFiles:
    securityOverride.xml: | 
      <server description="DX WebEngine server"> 
        <webAppSecurity httpOnlyCookies="true" removeServerHeader="true" disableXPoweredBy="true" trackLoggedOutSSOCookies="true" ssoRequiresSSL="true" sameSiteCookie="none"/>
        <httpSession invalidateOnUnauthorizedSessionRequestException="true" cookieHttpOnly="true" cookieSameSite="None"/>
      </server>

Also by default we have configured to trust any default certificates, which are typically included in all mainstream browsers. By providing this config setting, the default certificates will be not trusted disabling communication with third-party services. 

  configOverrideFiles:
    securityOverride.xml: | 
    <server description="DX WebEngine server"> 
      <ssl id="defaultSSLConfig" trustDefaultCerts="false" />
    </server>

Additional Configuration

See Security hardening for production for more information.

Virtual Hosts can be used to limit the domains the server responds to - in the sample below the virtual host is configured to not respond to other hosts than localhost and sample.hcl.com:

<virtualHost id="default_host" allowFromEndpointRef="localHostOnly">
    <hostAlias>*:9080</hostAlias>
    <hostAlias>*:9443</hostAlias>
    <hostAlias>sample.hcl.com:80</hostAlias>
    <hostAlias>sample.hcl.com:443</hostAlias>
</virtualHost>

Note: Refer to this Update custom values.yaml with configOverrideFiles using HELM upgrade.