LDAP Authentication For OpenNMS

While the default behaviour of the OpenNMS service is to authenticate users against it's own PostgreSQL database, it can be configured to authenticate users against an LDAP DSA and load role information from the LDAP Dit. While users must still be defined within the service's database this facilitates more centralized administration and eases password management for users.

Note: This text is based heavily on the OpenNMS with LDAP Authentication document from the OpenNMS Wiki. The primary difference it we have implemented this without using the RFC2307 (POSIX/NIS) schema.

To Enable LDAP Authentication To Your OpenNMS Instance

1. Create a bind context for OpenNMS to use when performing searches of the DSA. A simple account object is sufficient.
   
dn: uid=opennms,ou=System,ou=Entities,ou=SAM,o=Morrison Industries,c=US
objectClass: top
objectClass: account
objectClass: simpleSecurityObject
uid: opennms
userPassword: *********

   If you intend to use XMPP notifications and your XMPP server uses the DSA for authentication make sure that this account is visible to the bind context of your XMPP service.
2. Load the groupOfUids schema into your DSA. This schema provides an objectclass called "groupOfUids" for storing a list of user ids. The alternative is to use posixGroup but that also requires you to allocate a gidNumber, but there is no need for NSS to be aware of these groups.
   
objectclass ( 1.3.6.1.4.1.6921.3.5
NAME 'groupOfUids'
DESC 'Morrison Industries account object'
SUP ( top )
STRUCTURAL
MUST ( cn )
MAY (
memberuid $ description $ businessCategory $
owner $ seeAlso $ o $ ou
)
)

   A file containing this schema is available here from the LDAP Schema Collection.
3. Create a bind context for the authentication of the Realtime Console ("rtc"). This object must be located beneath the root used for searching for accounts and the password must be "rtc".
   
dn: uid=rtc,ou=System,ou=Entities,ou=SAM,o=Morrison Industries,c=US
objectClass: top
objectClass: account
objectClass: simpleSecurityObject
uid: rtc
userPassword: {CLEAR}rtc

4. Create a container object for storing OpenNMS roles. For instance, I placed this object at "ou=Roles,ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US" beneath another container object "ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US" just in case it later becomes possible to store more OpenNMS configuration information within the Dit.
   
dn: ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US
objectClass: top
objectClass: organizationalUnit
ou: OpenNMS

dn: ou=Roles,ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US
objectClass: top
objectClass: organizationalUnit
ou: Roles

5. Within the roles container object create three role objects: "OpenNMS User" which contains all users, "OpenNMS Administrator" which contains all users who should have administrative capacity over the OpenNMS instance, and "OpenNMS RTC Deamon" which should only contain the user "rtc".
   
dn: cn=OpenNMS User,ou=Roles,ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US
objectClass: top
objectClass: groupOfUids
cn: OpenNMS User
memberUid: adam
memberUid: steve
memberUid: rhopkins

dn: cn=OpenNMS Administrator,ou=Roles,ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US
objectClass: top
objectClass: groupOfUids
cn: OpenNMS Administrator
memberUid: adam

dn: cn=OpenNMS RTC Daemon,ou=Roles,ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US
objectClass: top
objectClass: groupOfUids
cn: OpenNMS RTC Daemon
memberUid: rtc

6. In the $OPENNMS_HOME/webapp directory there is a file named "opennms.xml". Within this file is a "Realm" stanza which must be replaced to use LDAP authentication. Do not disturb other stanzas, such as "Logger. The "Realm" (and possibly other) stanzas are withing the "Context" stanza. It is important to place the new "Realm" stanza within the "Context" stanza as well, and not accidently delete the context stanza's closing tag. The new "Realm" stanza will look like:
   
<Realm className="org.apache.catalina.realm.JNDIRealm"
debug="0"
connectionURL="ldap://littleboy.morrison.iserv.net:389"
connectionName="uid=opennms,ou=System,ou=Entities,ou=SAM,o=Morrison Industries,c=US"
connectionPassword="********"
userBase="ou=Entities,ou=SAM,o=Morrison Industries,c=US"
userSubtree="true"
userSearch="(&(uid={0})(objectclass=account))"
roleBase="ou=Roles,ou=OpenNMS,ou=SubSystems,o=Morrison Industries,c=US"
roleName="cn"
roleSearch="(&(memberUid={1})(objectclass=groupOfUids))"/>

   Within this stanza the attributes are as follows:
   • className This selects the Java class used for identity and authentication. JNDI indicates the Java interface to directory services (aka LDAP).
   • debug I am not aware of any documentation for this directive.
   • connectionURL This is the URL used to connect to the DSA.
   • connectionName This is the DN which OpenNMS will use to bind to the DSA.
   • connectionPassword This is the password OpenNMS will use to bind to the DSA.
   • userBase This is the base of the search that will be used when looking up identities (users, the "rtc" account).
   • userSubtree If this is true than the search will have a subtree scope, otherwise the search will have a one-level scope. Set this to false if all your accounts are within the container object specified by userBase otherwise if your accounts are divided into multiple containers beneath userbase set it to "true"
   • userSearch This is the filter that will be used when searching for an account, the string {0} will be replaced by the username. Since this value is within an XML block special characters like the & (ampersand) must be escaped to their proper XML names.
   • roleBase This is the base of searches for role objects.
   • roleName The LDAP attribute containing the name of the role.
   • roleSearch This is the filter that will be used to lookup role membership. The string {1} will be replaced with the user's login (uid). Since this value is within an XML block special characters like the & (ampersand) must be escaped to their proper XML names.
7. Restart the Tomcat service, it should not be neccessary to restart the OpenNMS service
8. You should now be able to login with your LDAP username and password, and users listed in the "OpenNMS Administrator" role object should be presented with the "Admin" link in the web interface.

Note: Users of the OpenNMS service MUST still be setup in the user administration section of the web ui's administrative interface. The LDAP service is only used for authentication and roles. If a user authenticates to the OpenNMS service but is not setup in the backend database the system will not behave properly.