... h1. AD and LDAP Configuration
This page reviews AD and LDAP configuration and integration for GroundWork Monitor 7.1.
{toc:minLevel=4|maxLevel=4|printable=false}
h4. 1.0 Introduction to Authentication
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. GroundWork Monitor 6.4 introduced Single Sign-on (JOSSO), which entails additional security for applications managed by the portal, and thus requires a few additional steps for configuration when using LDAP.
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 Microsoft Active Directory authentication. LDAP configuration is similar and is described in a subsequent example.
h4. 2.0 Active Directory and LDAP Configuration
h5. 2.1 Important Points Before You Start
* LDAP users cannot be assigned to roles using the portal administrator application.
* LDAP users do not need to be defined in the portal (this is different from GroundWork Monitor 5.x).
* Configuration of LDAP parameters is done outside of the UI and requires a restart of *gwservices*.
* User passwords are never synchronized from LDAP to the GroundWork Monitor portal database.
* Any LDAP user who needs to access the GroundWork Monitor portal needs to be part of Authenticated group in LDAP/AD in addition to the regular GroundWork Monitor groups such as GWAdmin, GWOperator and GWUser. If not, the user may get an unauthorized HTTP 403 error when they try to login to GroundWork Monitor.
* GroundWork Monitor must be configured with the LDAP server name, a user name and password to bind to LDAP, and the specific container or organizational unit containing the users to be allowed access.
* The bind user will need browse and search permissions for the locations in LDAP where the users and groups are stored.
* These values must be input into an XML configuration file in a specific location, and the GroundWork Monitor portal must be restarted for the configuration to take effect.
* If your LDAP server is down for some reason, you can revert the GroundWork authentication mechanism back to the GroundWork database. In this case, stock user accounts can be used to login to the portal. Also the passwords for stock user accounts will be the last changed password before switching to LDAP. You would edit the file:
{noformat}
/usr/local/groundwork/josso-1.8.4/lib/josso-gateway-config.xml
{noformat}
and replace:
{noformat}
<s:import resource="josso-gateway-ldap-stores.xml" />
{noformat}
with:
{noformat}
<s:import resource="josso-gateway-gatein-stores.xml" />
{noformat}
h5. 2.2 Requirements and Options
* (Required) Active Directory domain controller to which you have administrative access
* (Required) Account with rights to browse the container in which you store the users. Example *ldapauth*, context:
{noformat}
|
cn=ldapauth,ou=GWUsers,dc=demo,dc=com
{noformat}
|
{Note}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 GroundWork fail but with a command line tests succeed.{Note}
|
* (Optional) Roles in the portal for desired access levels
* (Optional) A container and groups set up to match roles in the portal
|
... * (Useful) adsiedit.msc utility
h6. 2.2.1 Portal Proxy User
The portal proxy user is used to access API's of applications secured by the portal. You can either use an existing user or create a new one. If you do change from the default, you must add this user to the LDAP system you are using to synchronize from. Make sure that the user is member of *GWUser*. The login ID and password in LDAP always has to match the entries for the proxy user settings in the */usr/local/groundwork/config/foundation.properties* file. You should restart *gwservices* if you modify this file.
{noformat}
portal.proxy.user=user
portal.proxy.password=password
{noformat}
h6. 2.2.2 GDMA Auto Register User
The GDMA Auto Register user is used to access the Foundation API. It is recommended the default credentials be changed on the GroundWork server before an client agent installation. The login ID and password must match the entries for the *Auto_Register_User* setting in the GDMA client's *gdma_auto.conf* file. See the [Quick Start Auto Registration] document for adding/changing GDMA credentials.
h6. 2.2.3 Recommended LDAP Setup
Portal access authentication is controlled by *Role* permissions. Users gain access to different sections of the portal through role membership. In LDAP, group membership is used to map Role membership in GroundWork Monitor. In order to manage roles in GroundWork Monitor you should setup a new context (an Organizational Unit in AD by default) for the GroundWork Monitor roles.
Example: GWRoles (OU=GWRoles)
To this monitoring specific context add the following *Groups*. With this setup only GroundWork monitoring specific roles will be synchronized even if the user is member of other groups in different contexts (containers). This avoids crowding the GroundWork Monitor administration pages with roles unrelated to monitoring. You can then add company specific groups to the *GWRoles* context, which you can use to define specific access rights in GroundWork Monitor. When a user logs in, *Groups* in the *GWRoles* context of which the user is member of will be synchronized with *Roles* in the portal.
* GWRoot
* GWAdmin
* GWOperator
* GWUser
* Authenticated
h4. 3.0 Integration with OpenLDAP Directory
h5. 3.1 Configuration Steps
# Before changing the authentication method the portal should be stopped using the following command. All users will be logged out, so be sure to do this in a downtime window:
{noformat}
service groundwork stop gwservices
{noformat}
# Run this script to encrypt the LDAP password:
For 7.1.1 :
{noformat}
/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.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 org.groundwork.foundation.ws.impl.JasyptUtils --encrypt PASSWORD
{noformat}
For 7.1.0 :
{noformat}
/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 org.groundwork.foundation.ws.impl.JasyptUtils --encrypt PASSWORD
{noformat}
# Edit */usr/local/groundwork/config/josso-gateway-ldap-stores.xml* and add the bind credential details and the encrypted password. If upgrading from previous version of GroundWork, do not copy the existing *joss-gateway-ldap-stores.xml* file - please just edit the new file with the appropriate information.
#* If upgrading, you may want to restore the backed up copy of */usr/local/groundwork/foundation/container/josso-1.8.4/lib/josso-gateway-ldap-stores.xml* to a space outside of */usr/local/groundwork* for comparison of the LDAP settings.
{note}DO NOT RESTORE THE OLD FILE\! This is just a sanity check to make sure the values entered for LDAP match those used prior to the upgrade.{note}
# Edit */usr/local/groundwork/config/josso-gateway-config.xml*
Replacing:
{noformat}
<s:import resource="josso-gateway-gatein-stores.xml" />
{noformat}
with the following and saving the file:
{noformat}
<s:import resource="josso-gateway-ldap-stores.xml" />
{noformat}
# Edit */usr/local/groundwork/config/ldap-mapping-directives.properties* file to define the additional groups (if any) in LDAP and map them to *gw-portal-user*.
# Change the superuser in */usr/local/groundwork/config/gatein.properties* to <Insert new root user here> by adding these lines to the end of that file:
{noformat}
# portal-configuration.xml setting for org.exoplatform.portal.config.UserACL
# super.user init parameter value. This setting and portal-configuration.xml
# synchronization is done on startup and when this file is modified. Once
# set, portal must be restarted for value to take effect.
super.user=<Insert new root user here>
{noformat}
# Run this command to update the superuser userid to <Insert new root user here>
{noformat}
source /usr/local/groundwork/scripts/setenv.sh
java -cp /usr/local/groundwork/jpp/modules/com/groundwork/security/main/groundwork-jboss-security-7.1.0.jar com.groundwork.core.security.GateinConfigurationUtils -superuser <Insert new root user here>
{noformat}
# Edit */usr/local/groundwork/apache2/conf/groundwork/foundation-ui.conf* to allow for GWAdmin role to control access to Foundation.
{noformat}
vi /usr/local/groundwork/apache2/conf/groundwork/foundation-ui.conf
#uncomment the Require role GWAdmin line
#comment the Require user admin
{noformat}
# Restart groundwork
{noformat}
service groundwork restart
{noformat}
# Test logins by <Insert new root user here>, test login by users in GWAdmin group and non-GWAdmin groups.
h4. 4.0 Integration with Microsoft Active Directory
By default, the Active Directory system places all users into a container defined by the system as *cn=Users,dc=<myorganization>,dc=<com>*. Where *<myorganization>* is specific to the domain name of your implementation and *<com>* is the typical default suffix. For instance, if the Active Directory domain is *groundworkers.com*, the users would be stored in;
{noformat}
cn=Users,dc=groundworkers,dc=com
{noformat}
Through the Active Directory administration tool an administrator can add Organizational Units (OU), which are functionally the same as Containers (CN) to organize Roles. The distinction between Container and Organizational Unit is important when configuring the portal for LDAP, since if you specify a *CN* in the file in GroundWork Monitor, but create an *OU* in Active Directory, it will not find the Container and login will fail to assign roles correctly. It's easy to see the difference;
* The configuration entry for a Container uses the CN prefix:
{noformat}
rolesCtxDN="CN=GWRoles,dc=demo,dc=com"
{noformat}
* While for an Organizational Unit the prefix is OU:
{noformat}
rolesCtxDN="OU=GWRoles,dc=demo,dc=com"
{noformat}
When you use the Active Directory Users and Computers tool and create new objects, the only container you can create is an *OU*, so the latter of the above formats is the one to use.
Setting the *SynchronizeRoles* option to *true* will set up this role in GroundWork Monitor automatically when the first Active Directory user logs in. This is the recommended configuration, as it will make management transparent. If you decide not to use SynchronizeRoles, you will need to create any roles you wish to have the users be members of in GroundWork Monitor, and manually match the names of these roles to the group names in Active Directory.
The default role all users are assigned to is *GWUser*, so you can create a group called *GWUser* in Active Directory, and place users to whom you wish to grant default access to GroundWork Monitor into this group.
|
Similarly, if you wish to designate operators or administrators from among the Active Directory users, you should create groups named *GWOperator* and *GWAdmin*, and add your users to these groups. It is recommended that you place these groups in an alternate organizational unit (see above for Recommended LDAP Setup section).
|
{Note}In previous versions of GroundWork Monitor, the default role names were _Admin{_}, _Operator{_}, _Admin_, _Operator_, and _User_. These generic names often conflicted with default group names in Active Directory, and so they were changed as of GroundWork Monitor 6.2. If you are using a system upgraded from before 6.2 to 6.2 or later, you must change the group names in Active Directory, and add new roles to the GroundWork Monitor portal to match the Group names. The *GWAdmin* role (formerly _Admin_) is special, and you can't grant the same rights to another role. Please use the *GWAdmin* role for your administrative users. If you need to have this role name changed, please contact GroundWork Support.{Note}
|
This example assumes that you have created the organizational unit *GWUsers*, and that you have added your users to groups in this *OU*.
|
...
h5. 4.1 Configuration Steps
# Before changing the authentication method the portal should be stopped by issuing the following command. All users will be logged out, so be sure to do this in a downtime window:
{noformat}
service groundwork stop gwservices
{noformat}
# Run this script to encrypt the LDAP password:
{noformat}
/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 org.groundwork.foundation.ws.impl.JasyptUtils --encrypt PASSWORD
{noformat}
# To enable Active Directory or LDAP authentication, log in to the command line as *root*, and modify:
{noformat}
/usr/local/groundwork/josso-1.8.4/lib/josso-gateway-config.xml
{noformat}
Replace the following section:
{noformat}
<s:import resource="josso-gateway-gatein-stores.xml" />
{noformat}
with:
{noformat}
<s:import resource="josso-gateway-ldap-stores.xml" />
{noformat}
# Save the file.
# Edit the following file with your appropriate LDAP/AD properties:
{noformat}
/usr/local/groundwork/josso-1.8.4/lib/josso-gateway-ldap-stores.xml
{noformat}
You will be replacing the ldapservername with the resolvable hostname or IP address of your LDAP server, Administrator with the user name of your LDAP user (authorized to browse the containers where your users are), password with that users password, and the cn=XXX names with those appropriate for your AD system. For example, if your domain is demo.com, following the recommendations above you might:
#* Set securityPrincipal="cn=ldapauth,cn=Users,dc=demo,dc=com" to use the ldapauth user in the Users container to be able to browse the AD tree
#* Set usersCtxDN="CN=Users,dc=demo,dc=com" to be able to see all the users in the default location
#* Set rolesCtxDN="OU=GWRoles,dc=demo,dc=com" if you set up the OU, and added the groups GWAdmin, GWOperator, GWUser, and GWRoot, as recommended
{note}The rolesCtxDN="OU=GWRoles,dc=demo,dc=com" is an OU, not a CN in Active Directory.{note}
{noformat}
<ldap-istore:ldap-bind-store
id="josso-identity-store"
initialContextFactory="com.sun.jndi.ldap.LdapCtxFactory"
providerUrl="ldap://server:389"
securityPrincipal="cn=Administrator,cn=Users,dc=demo,dc=com"
securityCredential="password"
securityAuthentication="simple"
ldapSearchScope="SUBTREE"
usersCtxDN="CN=Users,dc=demo,dc=com"
principalUidAttributeID="sAMAccountName"
uidAttributeID="member"
rolesCtxDN="OU=GWRoles,dc=demo,dc=com"
roleAttributeID="sAMAccountName"
credentialQueryString="uid=sAMAccountName"
userPropertiesQueryString="mail=mail,cn=description"
/>
{noformat}
# Save the file.
# Run as *root*:
{noformat}
service groundwork start gwservices
{noformat}
At this point, all the users in the *GWRoles OU* should be able to log in. If they are not members of a group named the same as a role in the portal, they will be mapped to the default *GWUser* role. This allows them essentially view-only access to the portal screens, including the status viewer. The groups they are members of in the *GWRoles OU* will be created as roles in the portal if they do not already exist, and you may proceed to grant access to pages for these roles in the usual way.
#* If they are members of the *GWOperator* group, they will have access to *Event Console* and *Nagios* screens, as well as the *Actions* menus in the *Status* screen.
#* If they are members of the *GWAdmin* group, they will have administrative access to the *GroundWork Monitor* portal.
\\
{note}Only the *root* user within the *GWRoot* membership can create shared dashboards with portlet preferences that are inherited by other users.{note}
|
E-mail