GWME-7.1.1-11 - Foundation update with Advanced LDAP


Several performance and behavior issues have reported by customers in 7.1.1. These include

Further we are rolling up the changes incorporated in other patches which alter war and jar files touched in this patch, these patches are no longer required and should not be applied once this patch has been deployed:


Apply the attached update to received the performance fixes. For the Advanced LDAP support you will need to make further adjustments to the configuration.

If you already have LDAP configured from before applying this patch but do not need to use multiple endpoints your existing configuration will be loaded correctly without additional configuration.


  1. Download the patch file tar archive to, for example the /tmp directory
    Name Size Creator Creation Date Comment  
    ZIP Archive TB7.1.1-11.foundation_update_with_a... 60.42 MB Hans Kriel Sep 01, 2017 15:00 MD5: 4105ce058f236da3ab8e31143e9f02e0  
  2. Decompress the install script and files and run the install script. They will appear in subdirectory TB7.1.1-11.foundation_update_with_advanced_ldap_support. Go there and make sure to set ownership and permission.
    tar xvf TB7.1.1-11.foundation_update_with_advanced_ldap_support.tgz
    cd TB7.1.1-11.foundation_update_with_advanced_ldap_support

The patch directory will be noted (in the production version of the updater) with the facts of this update, along with backup files to be used in the uninstall phase if necessary.

Jar file names are correctly identified with -11 suffix. Note that the -11 suffix is important to you when executing the command line hash generator.

In the event that you had previously installed TB7.1.1-1 and/or TB7.1.1-8 this patch will detect the condition. It will handle both making a backup to restore the files involved as well as replacing the -1 and -8 patch files with the rolled up patches.


Application of this upgrade on a system using the default authentication requires no further configuration.

For LDAP support, "josso-gateway-config.xml" must reference "josso-gateway-ldap-stores.xml" and not "josso-gateway-gatein-stores.xml".

Application on a system previously configured with Josso Ldap store will result in continued operation using the legacy credentials in the "josso-gateway-ldap-stores.xml" file.

To take advantage of the new facilities you can make changes to "". If ldap configurations are found in this file, configuration settings in "josso-gateway-ldap-stores.xml" are ignored.

Details for updating these files are below.

Enabling LDAP Authentication

The use of the LDAP authentication is controlled by the same setting in "josso-gateway-config.xml" which is defaulted to use the local gatein store. To facilitate use of LDAP AD or OpenLDAP you will first change the following line. If LDAP was previously enabled the change will already be present.

Edit "josso-gateway-config.xml" and replacing:

/usr/local/groundwork/foundation/container/josso-1.8.4/lib/josso-gateway-config.xml - line 109
<s:import resource="josso-gateway-gatein-stores.xml" />


/usr/local/groundwork/foundation/container/josso-1.8.4/lib/josso-gateway-config.xml - line 109
<s:import resource="josso-gateway-ldap-stores.xml" />

Endpoint Definitions

The endpoints are added to the file. Each endpoint has a section in the file.

Multiple domains are configured by replicating sets of properties for AD or OpenLDAP below. Only properties that need to be overridden need to be copied, (the rest will default as below based on the type of domain).

Each specified endpoint is searched separately; the credentials and OU/CN directory in one endpoint have no bearing on the others.

Enabling domain prefixes in usernames

The requirement of using a domain in the user name is controlled by a parameter in whose default is false, no domain required.

/usr/local/groundwork/config/ - line 294 = true

If multiple endpoint domains are specified and a user name is in more than one, the possibility exists that the authentication will be on the wrong domain and role access will not be granted properly. Therefore we recommend that this be set to true and that users be required to enter the domain string "domain\user".

These are valid login principals (notice the slash can go either way in the login process). The domain name that the user enters is in the example, "demo" or "windows2012":

Domain property naming considerations

Note that domain names in the endpoint definitions have no relationship to the actual DN domain. In fact, the domain names these endpoints are known by cannot contain the '.' character. Valid names might be 'Demo' or 'Windows2012'. These generally look like Windows NetBios domain names and are used as prefixes on the principle name during login. So if the actual DN domain name is a simple string you might use it, but observe the rule.

UPN forms are not currently supported. The default domain can also be configured with no domain specified in the properties below. The default domain, if defined, will be used to look up users that are not authenticated with a domain prefix.

Otherwise, when a login prefix is not entered for authentication, the named domains are searched in the order they are defined in this file and on the first authentication success the search terminates.

Configuring each of the properties for a specific name or default domain must utilize the following forms ( in the properties file

  1. a named domain, (no '.' allowed in domain name):
    1.<domain name>.<property name> = ...
      domain namespaced example =  ldap://
  2. the default domain:
    1.<property name> = ...
      default namespaced example =  ldap://

Available LDAP configuration properties

Normally, only these property names need to be specified for each domain endpoint:

This is the full list of property names that can be configured per domain:

Security credential encryption

The security credential is still required as an encrypted string. Use the following command lines to generate the string, substituting the actual password for the example PASSWORD

/usr/local/groundwork/java/bin/java -cp /usr/local/groundwork/jpp/modules/org/jasypt/main/jasypt-1.9.2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/codec/main/commons-codec-1.4-redhat-2.jar:/usr/local/groundwork/jpp/modules/com/groundwork/collage/main/collage-api-7.1.1-11.jar:/usr/local/groundwork/josso-1.8.4/lib/commons-logging-1.1.1.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/configuration/main/commons-configuration-1.6-redhat-2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/lang/main/commons-lang-2.6-redhat-2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/collections/main/commons-collections-3.2.1-redhat-2.jar:/usr/local/groundwork/jpp/modules/org/apache/commons/lang3/main/commons-lang3-3.2.jar:/usr/local/groundwork/jpp/modules/com/chrylis/base58-codec/main/base58-codec-1.2.0.jar --encrypt PASSWORD 2>/dev/null

The result will look like this:

***ENCRYPTED VALUE=2eH7t2u82Cc4nfeNqhQfxK3mboEMkMBmY

This value will be used for the security_credential property for the corresponding domain configuration.

LDAP search scope

For example, where users are in a single master Users OU the search has only a single level. Suppose that the customer has users in a nested form, buried in subdirectories. The Aggregator allows us to define an endpoint at the top of the directory tree, and the search will descend the tree until it has either exhausted the possibilities (no match) or discovered the user (first match) and attempted authentication. The attribute in the endpoint spec that controls this is

ldap_search_scope = SUBTREE

Alternatively, you may define two or more endpoints for the same LDAP, naming scope as the "BASE" (just the indicated container or OU) or "ONE LEVEL" (objects subordinate to the named base but not the base) instead of "SUBTREE" (the base name and all nested objects to the maximum depth). In this way you can limit the searches according to the manner by which the customer has organized users.

LDAPS connections

When connecting to an LDAP provider that is protected by SSL or TLS two changes are needed:

  1. Install the certificates from the CA into the certificate store:
    /usr/local/groundwork/java/bin/keytool keytool -import -noprompt -storepass changeit -keystore /usr/local/groundwork/java/jre/lib/security/cacerts -alias MY-CERTIFICATE-NAME -file MY-CERTIFICATE-NAME.pem
    Certificate Encoding
    The certificates being imported MUST be PEM encoded certificates or the import will fail. If exporting from Microsoft you should select a Base64 encoded CER certificate type. Do not include the private key when you export.
  2. change the protocol used in the provider_url from ldap:// to ldaps://: = ldaps://


Here are three examples of working configurations.

Take special note of the "domain" portion of the configuration in each example. Both "windows2012" and "demo" are arbitrary. The actual domain names are "corp" and "demo". We suggest avoiding using the actual domain name so that it does not become the unconscious rule, later causing an error where the actual domain had a character like "." embedded.

Whatever you decide, the string you choose will be the one that users must enter, so for example "demo/jdoe" or "windows2012\jsmith". The slash can go either way, the form is always domain followed by slash followed by user.

Note that the port is not specified if the server you are pointing to is using default settings (389 for cert-less, 636 for LDAPs). In the third example you can see the form used for specified port.

# 'windows2012' AD endpoint:
# = AD = ldap:// = cn=ldapauth,cn=Users,dc=corp,dc=localdomain = XcuJVdPmzFo9egZ4a24XFsoTzoeZafKM = cn=Users,dc=corp,dc=localdomain = ou=GWRoles,dc=corp,dc=localdomain
# 'demo' AD endpoint:
# = AD = ldaps:// = cn=ldapauth,cn=Users,dc=demo,dc=com = 2eH7t2u82Cc4nfeNqhQfxK3mboEMkMBmY = cn=Users,dc=demo,dc=com = ou=GWRoles,dc=demo,dc=com
# 'default' AD endpoint:
# = AD = ldaps:// = cn=ldapauth,cn=Users,dc=demo,dc=com = 3eH7t2u82Cc4nfeNqW7fxK3mboEMkMBmY = cn=Users,dc=demo,dc=com = ou=GWRoles,dc=demo,dc=com


  1. Run the uninstall script, and respond to the prompts.

The patch directory will be processed to reflect the restoration of the files and uninstall steps.