How to LDAP authentication

Contents

This page reviews Integrating with Active Directory, OpenLDAP, and LDAPs.

Introduction
Active Directory and LDAP Configuration
Integration with Microsoft Active Directory
Integration with OpenLDAP

Introduction

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 JBoss 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. This process is best illustrated with an example. The following sections first 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.

Active Directory and LDAP Configuration

Important Points Before You Start

LDAP users cannot be assigned to roles using the portal administrator application unless you do not use the SynchronizeRoles option.
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 portal database.
A default webservices user wsuser account is required, and needs to be member of the AUTHENTICATED group and any other LDAP group (recommended to create WSUser group).
Any active user account should belong to a group called Authenticated in LDAP.
GroundWork Monitor must be configured with the LDAP server name, a user name and password to bind to LDAP with, 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 JBoss Portal must be restarted for the configuration to take effect.

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:
```
cn=ldapauth,ou=GWUsers,dc=demo,dc=com
```
[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

Web Service Security

As mentioned above, web services are secured using a webservices proxy user wsuser by default. This user is managed in the portal user management.

The user name and password used are stored in: /usr/local/groundwork/config/ws_client.properties
This user name should also exist in LDAP for GWMEE 6.4 or newer.
The default user name is wsuser and needs to be member of the AUTHENTICATED group and any other LDAP group (recommended to create WSUser group).
Keep in mind that changing the Web Services user name or changing the password for the default wsuser requires an update of the ws_client.properties file. You should restart gwservices if you modify this file.

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 the Authenticated role (group) in LDAP. 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.

\##############################################
\#portal proxy user name and password
portal.proxy.user=user
portal.proxy.password=password
\##############################################

GDMA Auto Register User

The gdma auto register user is used to access the Foundation API. 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 a member of the Authenticated role (group) and gdma group in LDAP. The login ID and password in LDAP must always match the entries for the Auto_Register_User setting in the gdma client's gdma_auto.conf file.

Portal Admin User

Some operations in the portal can only be executed by the admin user, such as defining the default preferences for dashboard pages. By default the admin user is a member of the GWAdmin role defined in GroundWork Monitor. If you use LDAP for GroundWork Monitor authentication/authorization, the admin user name might be already in use in LDAP, thus creating a conflict, or you may not want to use this user name for reasons of user name standardization.

In this case, you can define a new user in LDAP (gwadmin for example) and make them a member of the GWAdmin and Authenticated Roles (groups in LDAP). You can then adjust the default admin user name to match in GroundWork Monitor. For example, let's say you want the GroundWork Monitor Admin user to be called gwadmin instead of admin. You should restart gwservices if you modify this file.

Edit the web.xml file:

/usr/local/groundwork/foundation/container/webapps/jboss/jboss-web.deployer/conf/web.xml

change admin:

<context-param>
    <param-name>defaultDashboardAdminUser</param-name>
    <param-value>admin</param-value>
    <description>The admin user is  used to define the preferences that are inherited by dashboard portlets</description>
</context-param>

to gwadmin:

<context-param>
    <param-name>defaultDashboardAdminUser</param-name>
    <param-value>gwadmin</param-value>
    <description>The admin user is  used to define the preferences that are inherited by dashboard portlets</description>
</context-param>

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. So, 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 by synchronized with Roles in the portal.

GWgdma
GWAdmin
GWOperator
GWUser
Authenticated
GWwsuser (it is recommended to have this Group in LDAP to separate portal and webservices users. The user wsuser should belong to this group).

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 cn=Users,dc=groundworkers,dc=com.

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

rolesCtxDN="CN=GWRoles,dc=demo,dc=com"

While for an Organizational Unit the prefix is OU

rolesCtxDN="OU=GWRoles,dc=demo,dc=com"

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).

In previous versions of GroundWork Monitor, the default role names were 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.

This example assumes that you have created the organizational unit GWUsers, and that you have added your users to groups in this OU.

Configuration Steps

The steps below are for single JVM systems. For dual JVM systems please see; [PARTNER:Installing Dual JVM Configuration on Large Systems for 6.7.0]

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:
```
service groundwork stop gwservices
```
To enable Active Directory authentication, log in to the command line as root or equivalent, and modify:
```
/usr/local/groundwork/foundation/container/webapps/jboss/jboss-portal.sar/conf/login-config.xml
```

Uncomment the section in JOSSOLoginModule like this:

# <application-policy name="josso">
  <authentication>
        <login-module code="org.jboss.portal.identity.sso.josso.JOSSOLoginModule"
            flag="required">
            <module-option name="debug">true</module-option>
            <!--
                 Uncomment this section for LDAP/AD configuration. For more info refer documentation.
            -->
                 <module-option name="synchronizeIdentity">true</module-option>
                 <module-option name="synchronizeRoles">true</module-option>
                 <module-option name="preserveRoles">true</module-option>
                 <module-option name="additionalRole">Authenticated</module-option>
                 <module-option name="defaultAssignedRole">GWUser</module-option>
                 <module-option name="userModuleJNDIName">java:/portal/UserModule</module-option>
                 <module-option name="roleModuleJNDIName">java:/portal/RoleModule</module-option>
                 <module-option name="membershipModuleJNDIName">java:/portal/MembershipModule</module-option>
                 <module-option name="userProfileModuleJNDIName">java:/portal/UserProfileModule</module-option>
        </login-module>
  </authentication>

Save the file.
Edit the file /usr/local/groundwork/config/resources/josso-gateway-ldap-stores.xml with your appropriate LDAP/AD properties. You will be replacing server 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 that OU, and added the groups GWAdmin, GWOperator, GWUser, and Authenticated there, as recommended.
  The rolesCtxDN="OU=GWRoles,dc=demo,dc=com" is an OU, not a CN in Active Directory.
```
<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"
/>
```
Save the file.

Edit: /usr/local/groundwork/config/resources/josso-gateway-config.xml
Replace the following line:

<s:import resource="josso-gateway-db-stores.xml" />

with

<s:import resource="josso-gateway-ldap-stores.xml" />

Like this:

<!-- Identity, Session and Assertion Stores configuration -->
       <!--    <s:import resource="josso-gateway-db-stores.xml" />  -->
               <s:import resource="josso-gateway-ldap-stores.xml" />

Search for josso-basic-authentication and replace it with josso-bind-authentication:
Like this:

<def-auth:authenticator id="josso-authenticator">
     <def-auth:schemes>
       <!--    <s:ref bean="josso-basic-authentication"/> -->
               <s:ref bean="josso-bind-authentication"/>
     </def-auth:schemes>
 </def-auth:authenticator>

Save the file.
Edit: /usr/local/groundwork/config/resources/josso-gateway-auth.xml

Uncomment BIND Authentication Scheme (normally LDAP) section.
Like this:

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
      <!-- BIND Authentication Scheme (normally LDAP) -->
      <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
      <!-- Requires a be a bindalble credential store ! -->
      <!-- name attribute is important and must not be changed -->
      <bind-authscheme:bind-auth-scheme
              id="josso-bind-authentication"
              name="basic-authentication"
              hashAlgorithm="MD5"
              hashEncoding="HEX"
              ignorePasswordCase="false"
              ignoreUserCase="false">

          <bind-authscheme:credentialStore>
              <s:ref bean="josso-identity-store"/>
          </bind-authscheme:credentialStore>

          <bind-authscheme:credentialStoreKeyAdapter>
              <s:ref bean="josso-simple-key-adapter"/>
          </bind-authscheme:credentialStoreKeyAdapter>

      </bind-authscheme:bind-auth-scheme>

Save the file.
Now, start the GroundWork portal.
Run as root
```
service groundwork start gwservices
```

At this point, all the users in the Authenticated group 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 portal. Note that only the Portal Admin user will be able to set up shared dashboards with portlet preferences that are inherited by other users.

Integration with OpenLDAP

Important Points Before you Start

OpenLDAP is hard to configure
OpenLDAP allows anonymous browsing by default. This can be a bad thing. always configure GroundWork Monitor to use a user to access containers
The user must have access to browse the tree in the User and Role context containers

Requirements and Options

[Required] An OpenLDAP server
[Required] Administrative access to OpenLDAP (for setting up Users and Roles)
[Required] A user account with rights to scan the containers for Users and Roles
[Useful] LDAP browser

OpenLDAP Example

Background

OpenLDAP configuration is similar to Active Directory configuration. The requirements are similar as well. The main difference is in the configuration of LDAP itself, and the creation of a container for roles objects, whereas in Active Directory access to portal roles is controlled by group membership. OpenLDAP can be configured (as can Active Directory) to allow anonymous access for queries. This is not recommended, but it is supported. This example assumes that you have set up your openLDAP server with a role container called GWRoles.

Configuration Steps

To get started login to the OpenLDAP server and set up the Users container (default is ou=People), then set up the Roles container, add users to the Users container, Roles to the roles container, and add users to roles. It is a good idea to test your LDAP user login for browsing.
root user is cn=manager by default, and while the uid=root object is in the People container the default context may be different, for example: cn=manager,dc=groundworkers,dc=com
Be sure to read the Active Directory section above.
To enable OpenLDAP authentication, log in to the GroundWork command line as root or equivalent, and modify the files as you would for the Active Directory example above.

When you edit /usr/local/groundwork/config/resources/josso-gateway-ldap-stores.xml, be sure to use your appropriate LDAP properties:
For example:

<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="ou=GWUsers,dc=mycompany"
principalUidAttributeID="uid"
uidAttributeID="memberUid"
rolesCtxDN="ou=GWRoles,dc=cmycompany"
roleAttributeID="cn"
credentialQueryString="uid=cn"
userPropertiesQueryString="mail=mail,cn=description
/>

Follow steps 7 thru 10 from the Active Directory section. You will need to save the file, and restart the portal. All users will be logged out, so be sure to do this in a downtime window.
Run as root: service groundwork restart gwservices
All other steps are the essentially the same as for Active Directory.

How to LDAP authentication

Introduction

Active Directory and LDAP Configuration

Important Points Before You Start

Requirements and Options

Web Service Security

Portal Proxy User

GDMA Auto Register User

Portal Admin User

Recommended LDAP Setup

Integration with Microsoft Active Directory

Configuration Steps

Integration with OpenLDAP

Important Points Before you Start

Requirements and Options

OpenLDAP Example

Labels