Hannon Hill Corporation
950 East Paces Ferry Rd
Suite 2440, 24
thFloor
Atlanta, GA 30326
Tel: 800.407.3540
Tel: 678.904.6900
Fax: 678.904.6901
www.hannonhill.com
2001-2006 Hannon Hill. All rights reserved. Cascade Server, Hannon Hill, and the logos are registered trademarks of Hannon Hill Corporation. All other trademarks are owned by their respective owners.
Using LDAP/Active
Directory
Learn how to set up the
ldap-config.xml file in the CMS
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
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
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).
• 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 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>
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>
</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:
<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>
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>
(&(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
“&”; 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
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.
