How to AD and LDAP configuration




This page reviews AD and LDAP configuration and integration for GroundWork Monitor 7.2.0.

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.

LDAP and Active Directory Configuration

Important Points Before You Start

Requirements and Options

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

/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 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

/usr/local/groundwork/foundation/scripts/ encrypt --value=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

Portal super user

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

LDAP search scope

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

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