Using LDAP/Active Directory

Transcription

1 Using LDAP/Active Directory Learn how to set up the ldapconfig.xml file in the CMS Hannon Hill Corporation 950 East Paces Ferry Rd Suite 2440, 24 th Floor Atlanta, GA Tel: Tel: Fax: 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.

2 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

3 INTRODUCTION The CMS enables the LDAP-enabled enterprise to effectively integrate alreadyestablished 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-synchronizationconfiguration> which itself has three sub-elements: <options> <schedule> <policies> <options> <user-requirements> < -required>true</ -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

4 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) address, and 3) full name pulled from the LDAP installation. The user-requirements element allows the integrator to specify that the 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

5 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- >info@site.com</send-to- > </report> The report element allows the integrator to have an summarizing each migration sent to an 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 repeatevery 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

6 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-attributefilter 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> < -attribute>mail</ -attribute> <full-name-attribute>displayname</full-name-attribute> These are the names of the attributes for each user that contain the username, , 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> 6

7 </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 autocreate 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"> </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. 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

8 <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-containeridentifier> </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

9 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 &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

10 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> < -attribute>mail</ -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> </create-if-does-not-exist> </group> <group> <name>groupb</name> <create-if-does-not-exist> </create-if-does-not-exist> </group> <group> <name>groupc</name> <create-if-does-not-exist> </create-if-does-not-exist> </group> </system-groups> <system-roles remove-from-other-roles="yes"> </system-roles> </ad-security-group-policy> 10

11 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 ed 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