WAS THIS PAGE HELPFUL? Leave Feedback
This page reviews AD and LDAP configuration and integration for GroundWork Monitor.
GroundWork Monitor supports single sign-on authentication through an external authentication source. Authentication services can be provided by Microsoft Active Directory or through a standards-compliant LDAP server. Most user accounts need not be defined in GroundWork Monitor a priori. User accounts must still be assigned system-specific roles and privileges, and the use of LDAP for authentication changes the way this is done. Configuring the GroundWork JBoss Portal for LDAP allows user passwords and other details such as role membership to be managed by the external directory service. User accounts and roles are synchronized with the GroundWork JBoss Portal when the user logs in, and users are assigned a default role as well as any roles they are members of in LDAP.
It is also possible to enable LDAPS, or LDAP over SSL, as well as many other alternate configurations. Please see the reference materials for JBoss LDAP configuration available here if you would like to study the various options and customize your LDAP setup with GroundWork Monitor.
This how-to goes through an example of setup, configuration, and assignment of users to roles in the context of users and groups that are managed by LDAP. The following sections outline some important points before you start, requirements and options, and then describes an example of configuring GroundWork Monitor for LDAP authentication.
Important Points Before You Start
|Avoid spaces or slashes in the distinguished name of the bind account, and $ or # in the bind account password. These characters can result in situations difficult to troubleshoot where bind attempts from GroundWork fail but with a command line tests succeed.|
|In at least some scenarios a space in a name of an account or role can be replaced with the string "\u0020". Example follows|
|New in the 7.2.1 Rollup patch is the capability to map arbitrarily named LDAP Groups to the standard GW Groups and Roles|
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 "foundation.properties". 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.
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 replace:
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).
Each specified endpoint is searched separately; the credentials and OU/CN directory in one endpoint have no bearing on the others.
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".
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":
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 (core.security.ldap.config.) in the properties file
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:
The security credential is required to be encrypted. Bare passwords will fail to authenticate. Use the following command lines to generate the string, substituting the actual password for the example PASSWORD
The result will look like this:
This value will be used for the security_credential property for the corresponding domain configuration. This procedure is also documented here: How to generate encrypted credentials
The default super user account for configuring defaults and shared dashboards has a username of "root". It is required that the super user account exists in LDAP so it can be logged into the portal, however this username is usually restricted in most organizations. To change the username for the account follow the procedure documented here: How to change the portal super user
Where users are in a single master Users OU, the search has only a single level. But suppose 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 by which the customer has organized users.
When connecting to an LDAP provider that is protected by SSL or TLS two changes are needed:
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.
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.
We recommend that you apply the patch the following patch located here:
Once this is done you have access to more complex LDAP configuration combinations.
Our recommendation is to use local AD conventions for naming the role context container/ou and the Groups therein.
GroundWork LDAP Aggregator maps these arbitrarily named Groups to the standard Groups and Roles already present in our portal. If you add your own Roles those are similarly mapped.
Let's imagine that in your LDAP directory you created:
Let's say you already have groups directly in the Users tree with users in them that would get the Admin and Operator privileges and these are in your directory as follows:
So you make:
Now on the GW Monitor server add this directive to the file /usr/local/groundwork/config/foundation.properties:
Since you have multiple role context locations in LDAP, you can specify to search each one with separate definitions on the same line separated by a "|" (pipe) symbol. An example follows, directing the LDAP Aggregator to search for groups in each of them and for the User as a member of at least one of them:
If you have Users in multiple places in the directory the same notation can be used for the users context. In the example we imagine there are two sets of users who will be given access, in the NOC and IT groups:
Add the mapping to the file /usr/local/groundwork/config/ldap-mapping-directives.properties. This is where the arbitrary LDAP names get associated with the portal:
Notice there is no mention of the "chained" groups aga and ago. The ldap search conducted by the LDAP Aggregator will match up the combinations and identify the ultimate group and role to be assigned to the user.
Once these changes are made and saved, restart GroundWork services:
This covers the 4 standard out of the box groups and roles. Should you want to customize with new roles you must first create the Role (membership) in the portal and assign the host group and resource privileges it may attain. You should also make the adjustments to the pages, containers and application permissions so that the new Role is permitted to access them.
Next you must add the key/value pairs to the ldap-mapping-directives.properties file to map the LDAP group to the portal role. Let's say you named the Role "Management":
Restart gwservices to make the change effective.
On the LDAP side, create the group "SomeLDAPGroup" under one of the named role context locations (from our example, NotGWRoles) and make the Users who will have this privilege members of SomeLDAPGroup. If they are not already members of the corresponding LDAP group for the gw-portal-user role, make that change as well (so they are able to land on the default landing page; if you don't do this their log in will net a 403 not authorized error)
If you need more detailed messages in the /usr/local/groundwork/jpp/standalone/log/framework.log log file you can increase the logging level. Consult with GroundWork Support to obtain this direction.