GWME-7.1.1-6 - LDAP Global Catalog

compared with
Current by NotSupportContact-Mark Carey
on Aug 03, 2017 14:33.

This line was removed.
This word was removed. This word was added.
This line was added.

Changes (2)

View Page History

h1. Problem

LDAP as deployed using JOSSO-1.8.4 and JBoss 6 has some deficits under certain customer use cases, namely
* GWMON-12972 Add the following
** The issue of speed of access addressed in the 7.1.1-1 patch which added caching
** The need for multiple LDAP endpoints where users are not in a single catalog (so called Global Catalog issue)
** The need to authenticate users whose accounts are located in multiple containers in the same catalog
** The need to authenticate users whose accounts are located in nested containers
* GWMON-12172, GWMON-13016 License page blank issue
* GWMON-13075, GWMON-12995 LDAPAggregator SSL keystore configuration, (useful for self-signed certificates), and enable TLSv1.2 for JDK 1.7.

Further we are rolling up the changes incorporated in other patches which alter war and jar files touched in this patch, making the application of such patches incompatible in sequence
* [LDAP Caching|]
* [Status View auto refresh|]
* GWMON-12883 (svn commits 27490, 27501) Virtualization dashboard does not show virtual hosts if they were previously monitored by Nagios.
* GWMON-12950 (svn commit 27645) Allow for passthrough queries in Rest API. Passthrough queries are prefixed by 'pass:'. These queries will not have any query helper functions applied but just be executed as is.
* GWMON-12156 (svn commit 27754) Plugin cannot be uploaded to foundation manage plugin section
* GWMON-12856 (svn commit 27744) Required custom group name in LDAP longer than allowed string length
* GWMON-12912 (svn commit 27702, 27766) Enable caching for improved logperf performance and scalability
* GWMON-12970 (svn commit 27770, 27773) Embed svn revision and branch name into java deployables (wars/ears)

h1. Solution

This patch is built in a maintenance branch including the solutions already coded for the points above and specifically, for LDAP, an aggregator function to permit specification and use of multiple LDAP AD and OpenLDAP endpoints so that users in any of the stores may be authenticated and given authorization to use GroundWork Portal applications according to their group membership.

Application of this upgrade on a system using native JBoss Gatein A and A has no effect. Application on a system previously configured with Josso Ldap store will result in continued operation using the legacy credentials in the joss-gateway-ldap-stores.xml file.

Once installed, making adjustments to the endpoint specifications in the modified file "" will result in the deprecation of the legacy directions in josso-gateway-ldap-stores.xml (they are simply ignored). The file is read whenever the ldap aggregator code is executed, so it is not necessary to restart gwservices. Note that the initial setting in the "josso-gateway-config.xml" file must reference the "josso-gateway-ldap-store.xml" file and not the "josso-gateway-gatein-store.xml" file.

h2. Installation

# Download the patch file tar archive to, for example the /tmp directory
# Decompress the install script and files and run the install script. They will appear in subdirectory TB7.1.1-6.multiple_ldap_providers. Go there and make sure to set ownership and permission.
tar xvf TB7.1.1-6.multiple_ldap_providers.tgz
cd TB7.1.1-6.multiple_ldap_providers

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.

h2. Configuration

h3. Legacy Respect

On first installation of the patch, in a system already configured for LDAP, no further changes than installing the patch are necessary. The values stored in josso-gateway-ldap-stores.xml will be read and used and access will be exactly as previously designed. The new code will be running, more efficiently and with the benefits of caching of user tokens, etc.

Should this not be the case, or in the event you wish immediately to set up the multiple endpoints, these are additional steps.

h3. Control Switches

The use of the LDAP aggregator is controlled by the same switch in the file josso-gateway-config.xml which at installation of GroundWork is set 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 file */usr/local/groundwork/foundation/container/josso-1.8.4/lib/josso-gateway-config.xml* by replacing
<s:import resource="josso-gateway-gatein-stores.xml" />
<s:import resource="josso-gateway-ldap-stores.xml" />

The requirement of using a domain in the user name is controlled by a parameter in whose default is false, no domain required.
{noformat} = false
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".

h3. 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).
* If any domains are configured here, the JOSSO endpoint configuration in josso-gateway-ldap-stores.xml is ignored.
* If NO domains are configured in, the JOSSO configuration is loaded into the LDAP Aggregator as the default domain.

Note that domain names 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.

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":


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

# a named domain, (no '.' allowed in domain name):
##<domain name>.<property name> = ...
# the default domain:
##<property name> = ...

The following property names can be configured per domain:
* credential_query_string
* enable_start_tls
* initial_context_factory
* ldap_search_scope
* principal_uid_attribute_id
* principle_lookup_attribute_id
* provider_url
* role_attribute_id
* role_matching_mode
* roles_ctx_dn
* security_authentication
* security_credential
* security_principal
* security_protocol
* server_type
* trust_store
* trust_store_password
* uid_attribute_id
* updatable_credential_attribute_id
* user_certificate_attribute_id
* user_properties_query_string
* users_ctx_dn

Normally, only these need to be specified for each domain endpoint:
* server_type
* provider_url
* security_principal
* security_credential
* users_ctx_dn
* roles_ctx_dn

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
source /usr/local/groundwork/scripts/
/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.0.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

h3. Notes and Variations

Each specified endpoint is searched separately; the credentials and OU/CN directory in one endpoint have no bearing on the others. This fact permits some flexibility in use cases that a less comprehensive approach might fail to satisfy.

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 the customer has organized users.

Changes made to are immediately effective. No restart of gwservices is required.

h3. Examples

Here are two examples elucidating working configurations. Note the use of the port 389. If one had to connect to LDAPS the port would change, along with the specification of security protocol.

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 "jsmith\windows2012"

# '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

h2. Uninstallation

*{_}Step 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.
{info}This patch was moved to a rollup patch and released as [GWME-7.1.1-11 - Foundation update with Advanced LDAP].{info}