Chapter 10. Integrating ReportServer with an Active Directory using LDAP

10. Integrating ReportServer with an Active Directory using LDAP

In the following we will outline the necessary steps to connect ReportServer to an Active Directory using LDAP. As there are many valid ways to organize a company's directory (may it be AD or another vendors product) ReportServer does not come with a predefined LDAP connector. This on one hand means, that the configuration might seem rather complex, but on the other hand it provides you with a maximum of flexibility.

To connect ReportServer to the Active Directory Service we will use ReportServer's integrated groovy script engine. The whole process can be divided into two, mostly separate parts. One part is the synchronization of the user objects: we will automatically copy Users, Organizational Units and Groups from the directory to ReportServer and keep them updated. The second part is a mechanism that authenticates the previously imported users when they log into ReportServer.

10.1. Synchronizing Users

The current ldapimport.groovy script is available here: https://github.com/infofabrik/reportserver-samples/blob/main/src/net/datenwerke/rs/samples/admin/ldap/ldapimport.groovy.

Note that as of ReportServer 4.0.0 you can use the ''ldapimport'' command together with the sso/ldap.cf configuration file for manually importing LDAP users.

Further, you can use the ''ldaptest'' command for checking your configuration. Details and example use can be found in the Administration Guide.

For scheduling this functionality periodically, you can use the ldapimport.groovy script linked above and schedule it via ''scheduleScript''.

Refer to the Configuration Guide for a detailed description of all configurable values.

10.2. Authenticating Users

There are many different ways to check a user's credentials, like using Client Certificates, authenticating with Kerberos or using some Single-Sign-On mechanism with e.g. spnego or CAS. We will present a very simple script that authenticates a user who provided a username/password-combination by trying to use this information to bind against the directory.

The complete script (hookldappam.groovy) is also in the appendix as well as available for download in the support portal.

The script consist of three separate parts: Two classes and a short script snippet, that registers an instance of these classes with ReportServer.

Let us first look at the LdapPAM class. PAM is short for pluggable authenticator module, authenticator modules in ReportServer are made up out of two parts: a client-side part, that handles the interaction with a user and a server-side part, that checks the credentials the client module retrieved from the user.

The implemented interface ReportServerPAM is shared by all of ReportServer authenticator mechanisms. It requires the implementation of two methods, the first is getClientModule, which provides the appropriate client component. Our LdapPAM reuses the UserPasswordClientPAM, that makes the user enter a combination of username and password and transfers the cleartext of both to the server. You should ensure SSL/TLS is enabled when using this module.

The second method authenticate performs the actual authentication. It is called with a set of tokens as collected by the specified client module and returns an object of type AuthenticationResult. The AuthenticationResult has three components, a boolean value indicating if authentication was successful, the resolved user, if any, and a second boolean value that indicates if the result is authoritative. This third value is only relevant with negative results - in this case it controls whether other modules (if any are activated) are queried or if the request is denied immediately.

The actual authentication is handed off to an instance of the LdapAuthenticator class. The code is basically the same as in the import script. A connection to the directory is established using the supplied password, and the information stored during import in the users origin field.

Depending on the outcome of this connection attempt an AuthenticationResult object is created and returned. In case of a negative authentication attempt the authoritative property is set based on the users origin property.

Lastly the script uses ReportServer's callback registry to hook into the authentication process.

Putting it all together

Now that you should have a basic understanding how the two scripts work, let's give it a try. Download the three files ldapimport.groovy, hookldappam.groovy and sso/ldap.cf to your computer.

Open the sso/ldap.cf with a text editor and change the configuration options to match your configuration. Details on these can be found in the Configuration Guide.

After you modified the file, open ReportServer in your browser and go to the fileserver section in the admin module.

Upload both .groovy files to a location below the bin directory. Open the terminal by pressing CTRL+ALT+T. Upload the sso/ldap.cf to the /etc directory. Change your current directory to the location where you put the script files using the cd command and execute the import script.

cd /fileserver/bin
exec -c ldapimport.groovy

The -c (commit) flag is important because otherwise changes to the data model made by the script would be reverted after execution.

If you now change over to the user manager section you can view the results of the import. Also some statistics were written to the server's logfile/console.

After you have verified that the import was successful, it's time to load the authenticator module. Again, open the terminal by pressing Ctrl+Alt+T, cd to the script's location and execute it.

cd /fileserver/bin
exec hookldappam.groovy

Now you are all set to give it a try: Log out, or better yet use a second browser in case something is wrong and try to log in again.

10.3. Possible Improvements
  • Autoload authenticator module on startup One important thing, to keep in mind is that hooks attached by a script will be lost when you restart ReportServer. To make sure the ldapPamHook gets automatically reattached place the script in the onstartup.d/ directory. Scripts in this directory automatically get executed on start-up, so your authenticator module is always available.
  • Using the scheduler to refresh users periodically To keep ReportServer's user database in sync with your company directory you would probably like to run the script automatically from time to time. To do this, you can use the scheduleScript terminal command.
  • Automatically fetch/refresh a user's corresponding user object on login Additionally to periodic updates you might want to refresh a user's object whenever s/he tries to log in. This can easily be achieved by modifying the hookldappam script and adding the required functionality.