LDAP as deployed using JOSSO-1.8.4 and JBoss 6 has some deficits under certain customer use cases, namely
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
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 "foundation.properties" will result in the deprecation of the legacy directions in josso-gateway-ldap-stores.xml (they are simply ignored). The file foundation.properties 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.
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.
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.
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
The requirement of using a domain in the user name is controlled by a parameter in foundation.properties whose default is false, no domain required.
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".
The endpoints are added to the foundation.properties 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).
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 (core.security.ldap.config.) in the properties file
The following property names can be configured per domain:
Normally, only these need to be specified for each domain endpoint:
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
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
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 foundation.properties are immediately effective. No restart of gwservices is required.
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"
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.