LDAP configuration

To configure Noojee Administrators LDAP interface you need root access to a CLI. If you don't know what a CLI is then find someone who does before proceeding :D

LDAP configuration requires changes to two configuration files:

web.xml
ldap.<ldaptype>.xml

web.xml

Web.xml is used to control what type of authentication is used by Noojee Administrator and in the case of LDAP authentication which ldap configuration file is to be used.

Note: when enabling LDAP you MUST disable the 'Change Password' menu in Noojee Administrator as the user cannot change their password via Noojee Administrator when using LDAP.

Web.xml contains two 'context-params' which need to be modified to enable LDAP.

<context-param>
        <param-name>AUTHENTICATION_TYPE</param-name>
        <param-value>AUTH_TYPE_LDAP</param-value>
    </context-param>
    <context-param>
        <param-name>LDAP_CONFIG</param-name>
        <param-value>/WEB-INF/conf/ldap.slapd.xml</param-value>
    </context-param>

The above example show that the AUTHENTICATION_TYPE has been set to AUTH_TYPE_LDAP and the location of the LDAP_CONFIG has been set to /WEB/INF/conf/ldap.slapd.xml.

This would enable LDAP authentication using the slapd service. For Active Directory just change the name of the LDA_CONFIG to /WEB/INF/conf/ldap.AD.xml.

Any changes to the web.xml file require a restart of the tomcat service:

sudo service tomcat6 restart

ldap.<ldaptype>.xml

Noojee Administrator ships with support for Microsoft Active Directory and OpenLDAP (slapd). Using the following guide and with a sound knowledge of LDAP you can also add in support for any other LDAP based service.

The standard configuration file are:

Active Directory: ldap.AD.xml

OpenLDAP(slapd): ldap.slapd.xml

Each configuration file need to be modifed to match your systems setup.

At the top of each ldap xml configuration file is a number of entity definitions. For the AD and Slapd servers you should only need to modify these entity settings and the group mappings (more later).

You should find the following entity settings at the top of the file:

<!ENTITY Server    "localhost">
<!ENTITY Domain    "DC=noojee,DC=com,DC=au">
<!ENTITY Port    "389">
<!ENTITY AdminUserCN    "admin">
<!ENTITY AdminUserPassword    "secret">
<!ENTITY UserOrganisationalUnit "people">
<!ENTITY GroupOrganisationalUnit "groups">

Entity	Meaning
Server	The IP address or hostname of your LDAP server.
Domain	The domain served by our server. This will normally be your organisations main domain name. e.g. noojee.com.au which becomes DC=noojee,DC=com,DC=au
Port	The port to connect to the LDAP server on. The default port of 389 can normally be used unless you are using an SSL certificate.
AdminUserCN	The admin user cn (common name) is used by Noojee Administrator to connect to your AD server for the purpose of searching for users and groups. The provided admin user name must be an account with search priviliges and the ability to read a user's or group's attributes.
AdminUserPassword	The AdminUserCN's password.
UserOrganisationalUnit	This is used to define the base scope from where to search for users in your directory tree. If you are using one of the supported LDAP servers you should not need to change this value.
GroupOrganisationalUnit	This is used to define the base scope from where to search for groups in your directory tree. If you are using one of the supported LDAP servers you should not need to change this value.

Any changes to the ldap xml configuration file require a restart of the tomcat service for the to take affect.

sudo service tomcat6 restart

Advanced Configuration

The ldap xml configuration file also allows you to do more advanced configuration.

This section describes each of the ldap configuration options:

The xml file is defined as a hierarchy of xml tags. e.g.

<ldap>
    <server>xxxx</server>
    <port>nnn</port>
    <enabled true="true">enable</enabled>
</ldap>

To simplify the following description the tag '<server>' will be referred to as 'ldap.server' which provides its precise location in the xml hierarchy. An tag attribute such as the 'true' attribute of the '<enabled>' tag is described as 'ldap.enabled@true'

Tag	Description	Domain
ldap.server	See Server above.	Valid fqdn or ip address
ldap.port	See Port above.	Integer
ldap.use-ssl	If true, then communications is done via SSL. If false, then all communication is done using clear text. If you use SSL you will need to change the port to 636. The LDAP server must be set up with an X.509 SSL server certificate and have SSL enabled. Typically, you must first obtain a signed certificate for the server from a certificate authority (CA).	true\|false
binddn	The Distingushed Name of the Admin account used to search the directory tree. The provided admin user name must be an account with search priviliges and the ability to read a user's or group's attributes.	Distinguished Name
bindpw	Password of the binddn.
user.baseDN	The location in your directory tree from which to start searching for a user when that user attempts to login.	Distinguished Name
user.scope	Controls how the user.baseDN is searched. Subtree should normally be used as it allows the process to search the entire subtree under the user.baseDN.	object\|onelevel\|subtree
user.filter	The user filter is used to search for the authenticating user's LDAP entry. The filter MUST contain a single occurance of the parameter '%1'. The user's simple username e.g. 'bsutton' is substituted for %1 at run time. The filter needs to be formulated to return the users LDAP entry as an exact match. The exact filter is dependant on which LDAP server you are using.	Any valid LDAP search expression.
user.attributes.authDN	The name of the 'user attribute' that contains the user's Distingished Named (DN). The DN is retrive from the authenticating user's entry when the user.filter finds a match. The DN is subsequently used to authenticate the user against the LDAP service.	Valid LDAP attribute name.
user.attributes.groupMembershipID	The user attribute that contains the user's ID used to identify their membership of a group. This is often the full DN of the user but in some cases may be a simple uid for the user. The groupMembershipID is passed to the group.filter (see below)	Valid LDAP attribute name.
user.attributes.email	The user attribute which holds the user's email address. The user's email address is stored in the Noojee Administrators Account entry for the user.	Valid LDAP attribute name.
user.attributes.enabled	The user attribute which holds the users 'enabled' status. Only 'enabled' users will be allowed to log into Noojee Admin. The xml tag takes a number of attributes which control its exact behaviour (see belwo).
user.attributes.enabled@true	Allows the value of 'true' to be defined. For instance an LDAP server may use 'true', 'on' or '1' to describe the value as true. For each of these separate cases you would need an entry of true="true", true="on" or true="1". In some cases your LDAP server may NOTt have an enabled attribute but rather a disabled attribute. In these cases you can use the true attribute and reverse its meaning. e.g. true="false" which means if the 'disable' LDAP attribute has a value of 'false' then then account should be considred enabled. Confused?	Any valid string
user.attributes.enabled@false	See @true. This value defines the allowed value for false. e.g. false="false" false="off" false="0"
user.attributes.enabled@default	Provides a default value for the enabled attribute if it is not present. We recommend that you set this to leave the user disabled if the attribute is not present. Note the default value is compared against the @true and @false values to interpret its meaning.
groups.baseDN	The location in your directory tree from which to start searching for a user's set of groups when that user attempts to login.	Distinguished Name
groups.scope	Controls how the groups.baseDN is searched. Subtree should normally be used as it allows the process to search the entire subtree under the groups.baseDN.	object\|onelevel\|subtree
groups.nameAttribute	This is the group's attribute which contains the groups common name. The groups common name is used when mapping an ldapGroup to a njadminGroup.	Any valid LDAP attribute name.
groups.filter	The group filter is used to search for the authenticating user's membership of LDAP groups. The filter MUST contain a single occurance of the parameter '%1'. The user's id as controlled by the user.attributes.groupMembershipID is used in the search filter. e.g. 'cn=Brett Sutton,OU=Noojee Telephony,DC=Noojee,DC=com,DC=AU' or just bsutton. Which user attribute is suitable for use in the group membership search will depend on your LDAP server. The the value of groupMembershipID is substituted for %1 at run time. The filter needs to be formulated to return the set of LDAP groups the user belongs to.	Any valid LDAP search expression.
groups.mappings	Contains the set of mappings between LDAP groups and Noojee Administrator groups. The set of user groups that Noojee Administrator uses will not be the same as the set of groups used by your LDAP service. The group mappings allows an LDAP group to be mapped to one or more Noojee Admin groups. For each ldap group you need to create a groups.mappings.ldapGroup tag which contains one or more Noojee Administrator groups that you want the group to be mapped to. When a user authenticates, the set of LDAP groups the user belongs to is pulled from the LDAP server. For each group for which a mapping is exists, the associated set of Noojee Administrator groups are created against the Noojee Administrator user account. Any Noojee Administrator groups which aren't mapped will be deleted from the authenticating user's Noojee Administrator user account.	one or more groups.mappings.ldapGroup
groups.mappings.ldapGroups	Maps an LDAP group to one or more Noojee Administrator user group.	one or more nested njadminGroup
groups.mappings.ldapGroups@name	The name of the LDAP Group.	Any valid LDAP group name.
groups.mappings .ldapGroups.njadminGroup	The Noojee Administrator group which the parent LDAP group is to be mapped to.
groups.mappings .ldapGroups.njadminGroup@name	The name of the Noojee Administrator group.	Any valid Noojee Administrator user group.