LDAP/Active Directory

• Configuration File Details
• Running the LDAP Migrator
• Using LDAP with SSL
• User Auth Plug-in
• Custom LDAP Binding Modules

• Cascade Server 5.5.2 Release Notes
• Cascade Server 5.5.1 Release Notes
• Cascade Server 5.5 Release Notes
• New Asset Factory and Workflow Trigger Plugins
• Cascade Server 5.2.4 Release Notes
• Cascade Server 5.2.3 Release Notes
• Cascade Server Firefox Extension
• Cascade Server 5.2.2 Release Notes
• Cascade Server 5.2.1 Release Notes

Configuration File Details

A configuration file is required for LDAP / Active Directory authentication. The configuration file is stored in the database and is accessible via Tools -> System -> Configuration -> LDAP Configuration.

 

Configuration File Details

The configuration 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 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.

<is-enabled>yes</is-enabled>

This element specifies whether the LDAP system should function in its present state as defined by the configuration file. If it is desired to turn off the LDAP functionality, one may leave the configuration file present and simply set is-enabled to 'no', or 'false'. 

<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 <repeat-time-unit> specifies the length of each time repeat-every time unit. This may be minutes or hours or days.

For versions 4.1 and above, the following <binding> element may be added under the <server> element:

<binding> <classname>com.hannonhill.cascade.model.security.ldap.bind.LDAPSSLBind</classname> <parameter> <name>javax.net.ssl.keyStore</name> <value>C:/Java/jdk/jdk1.5.0_06/jre/lib/security/keystore</value> </parameter> <parameter> <name>javax.net.ssl.keyStorePassword</name> <value>hannon</value> </parameter> <parameter> <name>trust-server-certificate</name> <value>yes</value> </parameter> </binding>

This is the default binding that Cascade Server uses and performs normal LDAP binding without encryption for purposes of authentication and user migration. Cascade Server also provides an SSL binding functionality.

<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> </user-policy>

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,DC=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 Cascade Server, should as a part of the log in process authenticate against the LDAP server.

<authentication-mode>ldap</authentication-mode>

Beginning with Cascade Server 4.2, Administrators may specify within a new <authentication-mode> element whether to use "normal", "custom", or "ldap" authentication. This element overrides the <authenticate-against-ldap-server> policy level configuration element, which allowed only "yes", "no", without allowing for custom authentication modes.

<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 still 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>

However, user-dn element is deprecated and it should not be used in the future. 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>(&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).

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

Note: 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> </ad-security-group-policy>

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.

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

LDAP Configuration File