How to integrate FileFly portal with Active Directory

FileFly 2.0 and higher have the capability to be integrated with Active Directory if required. Usually a single shared login is enough for most environments, but AD integration can be configred for larger teams or organizations that require it.

Tip

With FileFly 3.0 and higher, a new installation of the FileFly tools application prompts whether to configure AD authorization. The following instructions apply only if it is not initially configured or if FileFly 2 is running.

To configure AD authorization

Because configuring and testing AD integration requires stopping and restarting the Caringo FileFly Webapps service, plan for the FileFly scheduler to be suspended for the duration before you begin.

The main configuration for the LDAP connectivity can be found in the following directory on the server where the FileFly Admin Tools are installed.

C:\Program Files (x86)\Caringo FileFly\AdminTools\Tomcat\conf\server.xml

On opening the file to edit it you find the following entry near the end of the file.

<Engine name="Catalina" defaultHost="localhost">
<Realm className="org.apache.catalina.realm.LockOutRealm">

<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase">
<CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler"
algorithm="SHA-256" encoding="UTF-8" iterations="10" saltLength="32" />
</Realm>

<!-- To integrate with Active Directory, comment out the UserDatabaseRealm above and uncomment 
the JNDIRealm below. Supply appropriate LDAP servers and credentials (used only to access the
directory - no special rights are required). Be sure that LDAP/SSL is correctly configured on
AD servers before you start.
Configure userBase and roleBase contexts correctly for your domain. All admin users must reside
in the configured userBase (searched recursively). The 'fileflyadmin' group must
reside directly within roleBase (e.g., cn=fileflyadmin,ou=Groups,dc=example,dc=com).
In this configuration, users will login using their regular Windows login name (sAMAccountName).
-->
<!--
<Realm className="org.apache.catalina.realm.JNDIRealm"
connectionName="cn=ldapbinduser,cn=Users,dc=example,dc=com"
connectionPassword="PASSWORD"
connectionURL="ldaps://ad-server-1.example.com/"
alternateURL="ldaps://ad-server-2.example.com/"
referrals="follow"
userBase="cn=Users,dc=example,dc=com"
userSearch="(sAMAccountName={0})"
userSubtree="true"
roleBase="ou=Groups,dc=example,dc=com"
roleName="cn"
roleSubtree="false"
roleSearch="(member={0})" />
-->

</Realm>
<Host name="localhost" appBase="../webapps"
unpackWARs="true" autoDeploy="true" errorReportValveClass="servlet.QuietErrorReportValve">
</Host>
</Engine>

Note the guidance details in this file:

To integrate with Active Directory, comment out the UserDatabaseRealm above and uncomment the JNDIRealm below.
Supply appropriate LDAP servers and credentials (used only to access the directory; no special rights are required).
Verify LDAP/SSL is correctly configured on AD servers before starting.
Configure userBase and roleBase contexts correctly for your domain.
All admin users must reside in the configured userBase (searched recursively).
The 'fileflyadmin' group must reside directly within roleBase (e.g., cn=fileflyadmin,ou=Groups,dc=example,dc=com).
In this configuration, users log in using the regular Windows login name (sAMAccountName).

Enabling the JDNIrealm looks like:

<Engine name="Catalina" defaultHost="localhost">
<Realm className="org.apache.catalina.realm.LockOutRealm">
<!--
<Realm className="org.apache.catalina.realm.UserDatabaseRealm"
resourceName="UserDatabase">
<CredentialHandler className="org.apache.catalina.realm.MessageDigestCredentialHandler"
algorithm="SHA-256" encoding="UTF-8" iterations="10" saltLength="32" />
</Realm>
-->

<Realm className="org.apache.catalina.realm.JNDIRealm"
connectionName="cn=ldapbinduser,cn=Users,dc=example,dc=com"
connectionPassword="PASSWORD"
connectionURL="ldaps://ad-server-1.example.com/"
alternateURL="ldaps://ad-server-2.example.com/"
referrals="follow"
userBase="cn=Users,dc=example,dc=com"
userSearch="(sAMAccountName={0})"
userSubtree="true"
roleBase="ou=Groups,dc=example,dc=com"
roleName="cn"
roleSubtree="false"
roleSearch="(member={0})" />
</Realm>

The rest of the configuration must be specified as well to make a valid configuration, so take it line by line:

connectionName= "cn=ldapbinduser,cn=Users,dc=example,dc=dom" connectionPassword="PASSWORD"	The connection details for the directory. Specify a user that has list privileges on the directory. Example: `connectionName="cn=Administrator,cn=Users,dc=SalesLab01,dc=com"` This example uses the AD administrator account, but a service account can be used.
connectionURL="ldaps://ad-server-1.example.com/" alternateURL="ldaps://ad-server-2.example.com/"	These are the two primary AD servers. Given two servers: Lab01WinSVR01.SalesLab01.dom ADBackupServer.SalesLab01.dom the config lines are: `connectionURL="`ldaps://Lab01WinSVR01.SalesLab01.dom/`"` `alternateURL="`ldaps://ADBackupServer.SalesLab01.dom/`"`
referrals="follow"	Specifies if either of these two servers refers to another, follow the referral for the name/user lookup.
userBase="cn=Users,dc=example,dc=com"	Where the users live in active directory. Example: `userBase="cn=Users,dc=SalesLab01,dc=dom"`
userSearch="(sAMAccountName={0})"	Which property to use for matching the user attributes. More information: docs.microsoft.com/en-us/windows/desktop/adschema/a-samaccountname
userSubtree="true"	Per Tomcat documentation: Enable you want to search the entire subtree of the element specified by the `userBase` property for the user's entry. The default value of `false` (disabled) causes only the top level to be searched. Not used if you are using the `userPattern` expression.
roleBase="ou=Groups,dc=example,dc=com"	Where to start looking for groups. The ou for groups is where the FileFly admins group goes into.
roleName="cn"	Keep as is.
roleSubtree="false"	Similar to the userSubtree command, except nested groups are not desired.
roleSearch="(member={0})"	What attribute within LDAP to use for matching users to a group.

Configuration details can be found in the Tomcat 8 documentation: tomcat.apache.org/tomcat-8.5-doc/realm-howto.html

Example realm:

Important

Before testing your connection, complete the following:

Add the FileFly admin group into the roleBase location.
Use an XML validator (such as xmlvalidation.com) to check for parsing errors.
After any change, restart the Caringo FileFly Webapps Service and log in with a user that is part of the fileflyadmin group.

Troubleshooting

To troubleshoot the auth for Tomcat,

Navigate to the logs: C:\Program Files (x86)\Caringo FileFly\AdminTools\Tomcat\logs\
Locate and view the most recent catalina.<date>.log file.
Check the end of the log for errors.

Below the SSL handshake for AD is failing on both the primary and secondary locations.

This is fixed by switching back to LDAP by making this change:

Restart the Caringo FileFly Webapps Service and log in with any user that is part of the fileflyadmin group.