Configuration File Details
The LDAP configuration is stored as an XML file in the database. It is accessible via System Menu > Configuration > LDAP.
A sample LDAP configuration can be found here: LDAP Configuration XML.
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> 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.
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'.
This element specifies whether or not the LDAP tool should start automatically on a schedule, specified below.
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.
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’.
The <report> element allows the integrator to have an email summarizing each migration sent to an email account.
<schedule>
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 Cascade 4.1+, an optional <binding> element may be specified under the <server> element:
Clear-text and SSL binding are the two types methods available out of the box.
<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.
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).
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.
These are the names of the LDAP attributes for each user will map to the username, email, and full name of the Cascade user, respectively. All three elements are required.
If the user, once brought into Cascade Server, should as a part of the log in process authenticate against the LDAP server.
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.
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.
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.
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.
Custom DN Specification
Each LDAP user in Cascade, requires the following fields to be mapped from data in the LDAP system:
- email address
- full name
- username
- distinguished name (DN)
DN is used during authentication against the LDAP server. When LDAP users enter their usernames and passwords, Cascade locates the user's DN and attempts to bind to the LDAP server using the DN and the supplied password.
By default, Cascade will look for a distinguishedName attribute on the LDAP objects to map as the DN in Cascade. The distinguishedName attribute will usually look something like:
CN=FirstName LastName,OU=Employees,DN=company,DN=com
In the event a specific distinguishedName attribute is not present or does not represent the necessary DN for that user, the user-policy element supports the sub-element:
If it is specified, the system will attempt to read the value of the attribute with the name <attribute-name>. By default, only the attribute value is used to construct the DN. If <use-name-value-pair> is true, then the FQDN will include both the name and value of the attribute:
fullName=FirstName LastName
If <prepend-to-container-identifier> is true, then the DN will contain the attribute name and/or value (above) followed by a comma and the <container-identifier> user policy:
fullName=FirstName LastName,OU=Employees,DN=company,DN=com
In most cases, <use-name-value-pair> and <prepend-to-container-identifier> should both be set to "true" when using a custom <user-dn>.
The <user-dn> element is deprecated and it should not be avoided if it possible. It may be removed in future versions of the product. migrating the user. The value of the attribute is basis of the new FQDN for this user.
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:
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:
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 “&”; 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.
The security-group-id is the DN of the Security Group object within the Active Directory install.
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.