Using LDAP/Active

Directory
Learn how to set up the ldap-
config.xml file in the CMS

Hannon Hill Corporation

3340 Peachtree Rd NE
Suite 820, 8th Floor
Atlanta, GA 30326
Tel: 800.407.3540
Tel: 678.904.6900
© 2001-2005 Hannon Hill. All rights reserved. Cascade Server, Hannon
Fax: 678.904.6901 Hill, and the logos are registered trademarks of Hannon Hill Corporation.
www.hannonhill.com All other trademarks are owned by their respective owners.
 LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

Table of Contents
Introduction...................................................................................................................3
File Details....................................................................................................................3
File Structure ................................................................................................................3
<options> ..................................................................................................................3
<schedule>................................................................................................................5
<policies> ..................................................................................................................5
user-policy................................................................................................................... 5
Additional User Policy Option.................................................................................... 7
ad-security-group-policy............................................................................................. 9
Running the LDAP Migrator ........................................................................................11
Automatic Migration.................................................................................................11
Manual Migration.....................................................................................................11
Updating the Configuration File ...............................................................................11

2
 LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

INTRODUCTION

The CMS enables the LDAP-enabled enterprise to effectively integrate already-

established user-group relationships into the system user-group information architecture.

This integration is two-fold. The LDAP migration tool allows the integrator to set up and
automate:

1. Migration of users and groups from LDAP installation into the CMS
2. Real-time authentication of users brought in from the LDAP installation.

FILE DETAILS

A sample LDAP configuration file is provided with the default install. This sample file
can be found in

%INSTALL_DIR%/server/default/deploy/program.ear/ldap/ldap-config.xml

and to be recognized by the CMS, it must be placed in the base directory. This is the
same directory into which the License.dat file must also be placed.

FILE STRUCTURE

The file itself must be valid XML. The root element is <ldap-synchronization-
configuration> which itself has three sub-elements:

• <options>
• <schedule>
• <policies>

<options>

<user-requirements>
<email-required>true</email-required>
<full-name-required>true</full-name-required>
</user-requirements>

user-requirements is an optional sub-element that directs what

constitutes a valid user from the LDAP installation. Based on

3
LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

the policies (below) described, the migration tool will pull out
individual users from the LDAP installation. Each user will have
the ability to have 1) username, 2) email address, and 3) full
name pulled from the LDAP installation. The user-requirements
element allows the integrator to specify that the email and full
name fields are not required to be drawn. The defaults for these
items are true.

<automatic-synchronization>no</automatic-synchronization>

this element specifies whether or not the LDAP tool should start
automatically on a schedule, specified below.

<orphaned-ldap-users>remove</orphaned-ldap-users>

for any users in the content management system that are not part
of the LDAP install, the system may take one of the following
actions:
• ignore – does nothing
• remove – deletes user from the system
• deactivate – leaves user intact, but that user cannot log
in.

<server>
<ldap-version>3</ldap-version>
<hostname>server</hostname>
<port>389</port>
<security>
<username>CN=Administrator, DC=hannonhill,DC=com</username>
<password>12345</password>
</security>
<auth-type>simple</auth-type>
</server>

The server element specifies connection-related information of

the machine that is hosting the LDAP installation. It contains
several subelements:
• ldap-version
This may be either 2 or 3. Will usually be 3.

• hostname
The TCP/IP hostname of the server on which the LDAP
installation is running.

• port
The TCP/IP port of the server on which the LDAP
installation is running. Will typically be 389.

• security
Contains username and password elements that are necessary
to bind to the server so that the migration tool is able to
query the directory.

Note that the username element must be a fully qualified

Distinguished Name (DN).

4
 LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

• auth-type
For users that are specified in a policy (below) to
actively authenticate against an LDAP installation, the
auth-type element specified what kind of authentication
should be performed.

This should either be ‘simple’ or ‘Digest-MD5’.

<report>
<generate-report>yes</generate-report>
<send-to-email>info@site.com</send-to-email>
</report>

The report element allows the integrator to have an email

summarizing each migration sent to an email account.

<schedule>
<repeat-every>1</repeat-every>
<repeat-time-unit>hours</repeat-time-unit>

The repeat-every element specifies, if automatic-synchronization

is enabled, the number of time units that will pass in between
automatic synchronizations.

The repeat-time-unit specifies the length of each time repeat-

every time unit. This may be minutes or hours or days.

<policies>

The policies element contains individual policy elements that are one of the following:

• user-policy
• ad-security-group-policy

user-policy

This is the most common type of policy. It is not implementation specific, and
only requires a LDAP-compliant directory. It queries a container, iterating over
that container’s child objects, determining which objects are user objects to be
imported into the CMS.

<user-policy summary="Main Employees">

<container-identifier>
OU=Employees,DC=hannonhill,DC=com
</container-identifier>

5
LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

container-identifier is the DN of the container which

contains the users to be queried as a part of this policy.
Note that typically this will be an Organizational Unit
(OU).

<object-attribute-filter>
<name>objectCategory</name>
<value>
CN=Person,CN=Schema,CN=Configuration,DC=hannonhill,D
C=com</value>
</object-attribute-filter>

The object-attribute-filter allows the integrator to

specify which objects inside of the container for the
policy are actual user objects. For each object-attribute-
filter specified, each child of the container must have the
attribute and value match for that child to be considered a
user.

<username-attribute>sAMAccountName</username-attribute>
<email-attribute>mail</email-attribute>
<full-name-attribute>displayName</full-name-attribute>

These are the names of the attributes for each user that
contain the username, email, and full name of the user,
respectively.

<authenticate-against-ldap-server>
yes</authenticate-against-ldap-server>

If the user, once brought into ContentXML, should as a part

of the log in process authenticate against the LDAP server.

<enable-new-users>yes</enable-new-users>

Should each user migrated from the LDAP installation be

enabled by default? If one is not authenticating against
the LDAP server, this should be no to allow for the manual
setting of that user’s password from the web based
administration tool.

<system-groups remove-from-other-groups="yes">
<group>
<name>analysts</name>
</group>
<group>
<name>development</name>
<create-if-does-not-exist>
<role>Administrator</role>
<role>Publisher</role>

6
LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

</create-if-does-not-exist>
</group>
</system-groups>

The system-groups element specifies for each user migrated

in to what groups that user should belong. Note that the
attribute remove-from-other-groups=”yes” will instruct the
migration tool to remove the user from any groups not
included as children of this element.

Each group element should have a name element that

specifies the name of the group. If one wishes to auto-
create groups that do not already belong in the system,
then the create-if-does-not-exist should be specified for
that group. The create-if-does-not-exist should contain at
least one or more role elements, which will be used to
assign role(s) to the newly created group.

<system-roles remove-from-other-roles="yes">
<role>Administrator</role>
<role>Publisher</role>
</system-roles>

The system-roles element specifies for each user migrated

in to what roles that user should belong. Note that the
attribute remove-from-other-roles=”yes” will instruct the
migration tool to remove the user from any roles not
included as children of this element. At least one role
should be specified.

</user-policy>

Additional User Policy Option

Each LDAP-created user, at migration time, needs some key pieces of

information:

1. email address
2. full name
3. username
4. fully qualified distinguished name (FQDN)

The FQDN will usually look something like:

CN=FirstName LastName,OU=Employees,DN=company,DN=com

The user-policy configuration element supports the following sub-element

in the event distinguishedName is not present or does not represent the
FQDN for that user:

7
LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

<user-dn>
<!-- required -->
<attribute-name>fullName</attribute-name>

<!-- optional, defaults to false -->

<use-name-value-pair>true</use-name-value-pair>

<!-- optional, defaults to false -->

<prepend-to-container-identifier>true</prepend-to-container-
identifier>
</user-dn>

If the user-dn element is not specified, the user-policy will default to the
standard method of using the distinguishedName attribute to gather the
FQDN for that particular user. If it is specified, then it will attempt to read
the value of attribute-name when migrating the user. The value of the
attribute is basis of the new FQDN for this user.

If the use-name-value-pair is true, then the FQDN will look something

like:

fullName=FirstName LastName

If the prepend-to-container-identifier element is true, then the FQDN will

look something like:

fullName=FirstName
LastName,OU=Employees,DN=company,DN=com

For most cases, use-name-value-pair and prepend-to-container-identifier

should both be set to "true" if the custom user-dn rules are specified.

Wildcard filtering capability for LDAP User Policies

To enable a user policy to select user objects located inside a base container on an
LDAP installation:

Typically this is done by specifying multiple <object-attribute-filter>

elements:

<object-attribute-filter>
<name>objectclass</name>
<value>person</value>
</object-attribute-filter>
<object-attribute-filter>
<name>department</name>
<value>Marketing</value>
</object-attribute-filter>

8
LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

For the base container for this user-policy, these two object attribute filters have this
effect:

"Select all objects under the base container that have the
attribute value pairs:

objectclass=person
and
department=Marketing

"

This method is meant for less complex LDAP installations. For those requiring more
complex queries and wildcard filtering, in place of object-attribute-filter elements, one
may specify a single <freeform-filter> element:

<freeform-filter>
(&amp;(objectclass=person)(department=Mark*))
</freeform-filter>

This would match all objects under the base container that have the attribute
objectclass=person and any department that starts with Mark (Marketing, Marker
Production, etc).

***You may not have both a freeform-filter and any object-attribute-filter element

***The '&' symbol that is used to denote a logical “AND” should be escaped as
“&amp”; because of the XML nature of the configuration file.

ad-security-group-policy

This is only applicable for Active Directory installs. It queries a Security Group
object in the system, and from that Security Group’s attributes determines the
DNs of the members of that Security Group. Each of those users, then, are
queried and brought into the CMS.

<ad-security-group-policy summary="Security Group">

<security-group-id>
CN=TestSecurityGroup,OU=Employees,DC=hannonhill,DC=com
</security-group-id>

The security-group-id is the DN of the Security Group

object within the Active Directory install.

<group-member-attribute-id>member</group-member-attribute-id>

The security group identified by the security-group-id will

be queried to get a list of its members. This is done by
getting a list of all of the attributes of that Security

9
LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

Group that have a specific name. This name is specified by

the group-member-attribute-id.

Getting this set of values from the Security Group results

in a collection of user DNs. These DNs are then queried in
a similar fashion to that of the user-policy. To that
effect, the options below are handled in a similar manner
to that of the user-policy.

<username-attribute>sAMAccountName</username-attribute>
<email-attribute>mail</email-attribute>
<full-name-attribute>displayName</full-name-attribute>

<authenticate-against-ldap-server>
yes
</authenticate-against-ldap-server>

<enable-new-users>yes</enable-new-users>

<system-groups remove-from-other-groups="yes">
<group>
<name>groupA</name>
<create-if-does-not-exist>
<role>Administrator</role>
<role>Publisher</role>
</create-if-does-not-exist>
</group>
<group>
<name>groupB</name>
<create-if-does-not-exist>
<role>Administrator</role>
<role>Publisher</role>
</create-if-does-not-exist>
</group>
<group>
<name>groupC</name>
<create-if-does-not-exist>
<role>Administrator</role>
<role>Publisher</role>
</create-if-does-not-exist>
</group>
</system-groups>

<system-roles remove-from-other-roles="yes">
<role>Administrator</role>
<role>Publisher</role>
</system-roles>
</ad-security-group-policy>

10
 LDAP Configuration – Understanding and implementing LDAP/AD for CMS managers

RUNNING THE LDAP MIGRATOR

The LDAP Migrator tool may be invoked manually, automatically, or both.

Automatic Migration

Automatic migration must be set up through the LDAP configuration file and be followed
by a server restart to invoke the LDAP scheduler. In this configuration it is highly
recommended that the configuration specify a report to be generated and emailed to the
integrator.

Manual Migration

Once logged into the CMS as a user with an Administrator role, the LDAP migrator may
be invoked simply by navigating in the menu:

Tools -> Other -> Sync LDAP

This is the recommended way to migrate users when initially setting up the tool, as errors
in the configuration file are reported directly back to the user interface.

Updating the Configuration File

There is no need to restart the CMS for minor changes to the configuration file.
Generally, when changing the automatic-synchronization flag it is highly recommended
to restart the CMS, but otherwise the configuration file will be re-read upon the next
invocation of the LDAP migration tool.

11