LDAP Integration

RHQ uses passwords to authenticate users. Authentication information, comprising 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 in RHQ.

It is important to note that support for LDAP currently does not include storing attributes other than user names and passwords. In particular, authorization information such as roles used to control access to RHQ resources is persisted in the internal database.

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

As stated earlier, RHQ uses LDAP only to perform credential validation. Auxiliary information about a user such as first/last name, phone number, email address, and RHQ roles is stored in the RHQ internal database. Furthermore, user administration actions performed in RHQ do not impact the LDAP repository. For instance, the LDAP repository is not populated with the username and password when a user is registered in RHQ. The user must be defined in the LDAP repository independently of RHQ administration, and is assumed to have credentials populated in the LDAP repository when he/she is ready to access the RHQ console. In other words, 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.