LDAP Integration

RHQ uses passwords to authenticate users. Authentication information, comprised of user names and passwords, can be stored in an internal database (the default) or in an external LDAP repository. This document provides a summary of LDAP-based authentication and authorization in RHQ.

Configuring RHQ to Use LDAP for Authentication

In order to configure RHQ to use LDAP for authentication, navigate to the Server Configuration page (Dashboard->Administration->Server Configuration). The following configuration parameters can be specified:

• URL: This is the URL to the LDAP server. This defaults to ldap://localhost/ on port 389 (or port 636 if the SSL option is selected).
• SSL: Provides the option to use SSL while communicating with the LDAP server.
• Username/Password: The username and password to connect to the LDAP server. The username is typically the full LDAP distinguished name (DN) of a manager user, e.g. cn=Manager,dc=jboss,dc=com.
• Search Base: Base of the directory tree to search for usernames and passwords while authenticating users, e.g., "o=JBoss,c=US" or "ou=People,dc=jboss,dc=com"
• Search Filter: Any additional filters to apply when doing the LDAP search. This is useful if the population to authenticate can be identified via a given LDAP property, e.g. "RHQUser=true"
• Login Property: The LDAP property that contains the user name. Defaults to "cn". If multiple matches are found, the first entry found is used.

The configuration settings are captured by the class{{org.rhq.enterprise.gui.admin.config.EditConfigAction}}. It appears that the class simply stores the information entered by the user without making any attempt to validate it, i.e., checking, for example, that the LDAP server can be accessed via the URL and username/password specified by the user. The interface org.rhq.enterprise.server.legacy.common.shared.HQConstants defines the LDAP-related attributes such as the names of the above configuration parameters and the name of the class representing the LDAP JAAS Login Module org.rhq.enterprise.server.core.jaas.LdapLoginModule.

Authenticating Users via LDAP

Once the RHQ server has been configured to use LDAP for authentication, subsequent attempts to login to the RHQ console result in requests to the LDAP server to validate users' credentials. RHQ login requests are dispatched to the Struts Action class org.rhq.enterprise.gui.authentication.AuthenticateUserAction.

Communication with the LDAP server is handled by the class org.rhq.enterprise.server.core.jaas.LdapLoginModule, which implements a JAAS Login Module for LDAP. This class relies on Sun's LDAP initial context implementation (javax.naming.ldap.InitialLdapContext) to perform LDAP operations via JNDI. The login module first searches the set of base directories for a matching username applying any search filters. If a matching name is found, a bind request specifying both the username and password is sent to LDAP to validate the credentials. Authentication is deemed successful if the bind request returns normally.

Irrespective of whether LDAP is selected for authentication, the credentials of the root user rhqadmin (and those of the built-in super-user, Overlord) are stored in the internal database. This does not require special-casing the authentication logic as the JAAS login modules are stacked: when LDAP authentication is selected, the LDAP login module appears above the JDBC login module on the stack.

Impact of User Administration on the LDAP Repository

RHQ uses the LDAP repository in read-only mode.

One of the interesting features of the LDAP integration is the support for self-registration in RHQ available to those who are identified as potential RHQ users in the LDAP repository. One way of identifying RHQ users in the LDAP repository is to define attributes that can be specified in a search filter in the RHQ configuration, e.g., RHQUser=true. When such a user accesses the RHQ console for the first time, he/she is first authenticated in the LDAP repository, and then redirected to the registration page to capture auxiliary information such as first/last name and email address (the logic can be found in the class AuthenticateUserAction). This alleviates the task of user registration for RHQ administrators, and reduces the likelihood of errors as information is entered directly by the registrants.

LDAP Authorization

LDAP authorization begins with the existing LDAP authentication mechanism and adds the ability for RHQ administrators to leverage the pre-existing LDAP user and groups associations (defined external to RHQ) and appropriately map them to RHQ resource access model. The authorization mechanism dynamically updates the RHQ role < - > user definitions with the runtime user - >ldap group associations maintained on the LDAP server.

RHQ Roles, Groups and Users...

As a quick reminder, all entities(platforms,servers,services) within RHQ are considered resources. Groups allow the administrator to consistently bundle arbitrary amounts and/or hierarchies of resources. Roles encapsulate the permissions that entitled users will have if that role is assigned to a user. For this discussion it is helpful to remember that:

• a user account is how one gets authenticated to the RHQ server
• role describes how one gets authorized to view resources on the RHQ server
• and groups define which resources a said user has access to.
  

Each role can be seen as the mechanism of uniting authentication, authorization and visibility for a said user account. With overlapping roles, the greatest permissions attached dictate overall user ability.

The LDAP Parallel

LDAP is a lightweight directory server that many organizations have adopted to house user account information and to subsequently group those user accounts into larger units relevant to the business of the organization. Mark, Susey and Janet all have person accounts on the LDAP server. Mark is a part of the Accounting and Janitorial groups, Susey belongs to the Vice Presidents group, while Janet does not belong to any LDAP group. Many organizations already have groups of System Administrators and Operators that naturally lend themselves to matching roles and groups within the RHQ system.

How LDAP Group Authorization Works

There are variations on the exact order but the following outlines steps for successfully integrating existing LDAP user and groupings in with the RHQ model.

1. With a group of existing LDAP users in mind, define a new group "All LDAP Resources" bundling all resources that these users will need to have access to. Add all of the required resources to that group and browse to verify contents.
2. Create a new Role "LDAP Users" to organize users, RHQ groups and LDAP groups for integration.
3. While editing the "LDAP Users" role, hit the 'Add To List' button in the 'Assign Resource Groups' region to add the "All LDAP Resources" group to this role.
4. The final step, assuming 'Correct Configuration' defined further below, is to use the 'Add To List' button to select and assign LDAP groups available from your remote LDAP server to this role.

That's it. With correct setup, the first time that one of the LDAP authenticated and authorized users logs into the RHQ system, the authorization UI will request that they define a little bit of sign-up information and RHQ user accounts will be created and appropriately assigned/unassigned to the 'LDAP Users' role accordingly. In other words, from an LDAP standpoint you should not be using the 'ADD TO LIST' button from the 'Assigned Users' region to maintain or synchronize authorization information. The LDAP-RHQ group synchronization is handled automatically for you.

Correct Configuration

The RHQ server is only designed to support integration with one LDAP server. As such the configuration information defined in the Administration -> System Config -> Settings area is used for both LDAP authentication and LDAP Authorization. Authentication has already been covered above but we'll call out a few of the specific regions that are important for authorization specifically.

• Group Search Filter: field is an ldap search value that needs to return all LDAP groups available for authorization. This field is crucial for group authorization.
  • Ex. (objectclass=group) for Active Directory OR
  • Ex. (objectclass=groupOfUniqueNames).
• Group Member Filter: field is combined with the group search filter field and with the LDAP user domain component to make up the group membership check.
  • Ex. for Active Directory an ldap search filter like (&(objectclass=group)(member=cn=<userName being authorized>,ou=People,dc=test,dc=com))
  • Ex. ldap search filter like (&(objectclass=groupOfUniqueNames)(uniqueMember=uid=<userName being authorized>,ou=People,dc=test,dc=com))

    Getting the ldap filters right When setting the LDAP configuration up, it is helpful to verify generated LDAP filters are correct and return results using a separate ldap client first.

All the Pieces

Using RHQ and LDAP Authorizaton models together

For greater details on how the RHQ and LDAP Administration models work together see this link, but a simple rule of thumb is that once you're using an RHQ role for LDAP authorization purposes that the RHQ Administrator should not edit the "Assigned Users" list for that role because role -> user mappings are automatically handled by the server.

Other LDAP Design Information

Look here for more technical/design discussions of the Database and source implementation elements of LDAP 'Group Authorization Mappings'.

For more information on testing the LDAP RHQ integration

For Setup, Tips, Tools go here.