Configuring LDAP in 10 Easy Steps

  1. Obtain a username and password for your LDAP server that has read access to the users you want to import into Cascade
  2. Download a tool like LDAPExplorerTool that will let you browse for fully-qualified paths to your users
  3. Download the example LDAP configuration file from the Knowledge Base. The following steps will discuss modifying particular sections of that file.
  4. Put your LDAP server's connection details and credentials into the <server> element of the config file:

     <server>
         <ldap-version>3</ldap-version>
         <hostname>ldap.internal.myorg.com</hostname>
         <port>389</port>
         <security>
             <username>CN=John Smith,OU=Employees,DC=myorg,DC=org</username>
             <password>secretpassword</password>
         </security>
         <auth-type>simple</auth-type>
         <binding>
             <classname>com.hannonhill.cascade.model.security.ldap.bind.LDAPCleartextBind</classname>            
             <!-- SSL information goes here, if needed (see step 4) -->
         </binding>
     </server>
    
  5. Determine whether your LDAP server uses SSL. If it does, you're want to use the com.hannonhill.cascade.model.security.ldap.bind.LDAPSSLBind bind parameter within the <bind> section of your XML. The SSL binding class makes use of the following parameters:

javax.net.ssl.keyStore – the location of the SSL keystore on the Cascade server
javax.net.ssl.keyStorePassword – the password of the SSL keystore on the Cascade server
trust-server-certificate – whether or not you wish to trust the server certificate automatically. If you do not install the client certificate into the SSL keystore on the server running Cascade, this parameter should be set to "yes" or "true" to ensure that the SSL handshake succeeds. If omitted, this setting defaults to false.

Your XML should resemble the following:

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

If your LDAP server does not use SSL, remove the <parameter> elements inside <binding> if you're not using SSL.

  1. Modify the <report> section of the config file if you want to be emailed regular LDAP sync reports.
  2. Now look to the <policies> section of the example file. There are two kinds of policies: <user-policy>, which works on all LDAP servers, and <ad-security-group-policy>, which works only on Microsoft's Active Directory. For a <user-policy> you can use most of what is already in the example file if you are working with Active Directory and wish to synchronize ALL users in a particular OU (part of the AD folder tree). If you wish to use a security group to control who has a user account in Cascade, you'll need to use <ad-security-group-policy>. The two policies are identical but for the way that they find which users to synchronize:

    <user-policy> has:

    1. <container-identifier> that points to an OU in your LDAP, which must contain all of the user accounts you want to sync
    2. <object-attribute-filter> or <freeform-filter> which can narrow down which users in the container you want to sync. <freeform-filter> is very powerful, but you must understand LDAP Filter Syntax

    <ad-security-group-policy> has only:

    1. <security-group-id> that points to the Security Group object in Active Directory listing the users to be synchronized.

    BOTH have all the remaining elements you see in the example config file:

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

    … specify which LDAP attributes represent username, e-mail, and full name in Cascade. Above are Active Directory's defaults.

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

    … Are accounts seen for the first time in LDAP automatically enabled in LDAP or will a Cascade admin have to enable them manually?

     <convert-usernames-to-lowercase>yes</convert-usernames-to-lowercase>
    

    … Self-explanatory.

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

    … Controls whether Cascade maintains the user's password or whether it is checked against the LDAP server. I recommend leaving these as they are, because most people's intent is to have the LDAP server manage passwords. If you want to do something different, inquire and we can point you in the right direction.

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

    … Determines the imported users' group membership. The remove-from-other-groups attribute, if set to yes, will mean that at EVERY LDAP SYNC the user will be removed from groups other than those listed. Not recommended. Set this to no. The <create-if-does-not-exist> element will automatically create the group if it does not exist and assign the listed roles to it. Usually not needed, so I would omit this section from your policy.

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

    … Determines which global roles are assigned to the imported users.

  3. Install the configuration file using System Menu > Configuration > LDAP. You will need Administrator privileges.

  4. Test your LDAP sync using System Menu > Utilities > Sync LDAP. You can check your Cascade dashboard Messages for a report, or, depending on how you set up the <report> section above, a report may be e-mailed to you.

That's it, in less than 10 steps. Once you're satisfied everything is working as desired, you can edit the config file again and make synchronization automatic using the <automatic-synchronization> and <schedule> elements. You'll also want to pay attention to the <orphaned-ldap-users> element. As users leave your organization and are removed or disabled in LDAP you can choose to delete them, deactivate them, or just leave them in Cascade. Deletion is usually a reasonable choice, as their username will still appear in places where appropriate (like Last Modified By). The only side effect of deleting a user is that their individual account information will disappear (like Messages and Preferences) and their account can't be Audited directly. You'll still be able to see them in the Audit trail for the various Assets they've worked with.