In this post we will show 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.

The instructions and examples below all were written with ReportServer 2.1 in mind, as there were some improvements in this version, that make things easier. But although some modifications are necessary the principal approach is also valid for older versions.

Synchronizing Users

The complete example is available here: ldapimport.groovy

As for the length of the script we will not go through it line by line, but rather outline the general process and highlight some important spots that are likely starting-points for customization.

So let’s start with a general overview of the synchronization process. Besides the account data, used to log-in (bind) to the Active Directory Server the script requires two additional configuration values. The first is the ldapBase value, which specifies the common root node of all the directory entries that should be imported. This could simply be you organisation’s User-root, as in the example or just a subtree, if you don’t want to import all directory users into ReportServer. You can further tweak which user object get imported by modifying the ldapFilter property. Keeping the default value will import all users, groups and organizational unit as present in your directory. If you decide to modify this, keep in mind, that importing a user does not grant him any privileges. On the other hand a user not present in ReportServer will not even be available as a recipient for scheduled reports, or reports send by email. So generally there is no reason not just to import all your users.

The second configuration is the target node in ReportServer’s user tree. This is the node below which all imported objects will be placed. The script as published above will create an organizational unit “external” to which it will add all ldap objects. We suggest to keep imported objects separate from native ReportServer user tree objects, as this makes the synchronization much easier. The script also write protects all imported objects, to ensure that no objects are accidentally added to the automatically synchronized subtree.

After all configuration data is prepared the script starts by creating a map of all objects currently present below the targetNode. This map will later be used to make sure that objects that already existed are not recreated. This is important as creating the objects anew (and deleting the old one) will assign a new ID to the objects and we would have to update the id, wherever it was referenced. It’s much more reliable to just reuse the existing object.

Afterwards the script connects to the directory and issues a search for all objects below the ldapBase node that match the ldapFilter. The search results are sorted by their path, so we don’t have to take care of creating objects in the right order (parents before their children). If you change the filter expression you will have to add some code here that will find/create a suitable container for the node we are about to import.

In the next step the script iterates over the search results and creates the appropriate ReportServer object for each result. Execution is handed over to a create method for the specific object type. These methods all follow the same structure: they first either retrieve the node from the map created in the first step, or create a new node. Then the node is placed at the correct position in the target tree. Finally the search result’s properties are copied over to the ReportServer object.

When the object was created its writer-protection flag is set and the guid and origin properties are modified to indicate that the object was retrieved from the directory. The guid set here was used in the first step to uniquely identify and match existing nodes to the ones retrieved from the directory. The guid and origin properties are also the only part that is really specific to ReportServer 2.1, as these were not present in earlier versions. To use the script with older versions of ReportServer you would need to store this information elsewhere.

After all objects got created in the target structure a postprocessing is performed that correctly sets the members of all groups. The process is to iterate over all objects found in the directory and for each group first clear the list of members and then retrieve the members from a map created in the previous step.

As a final step all users no longer present in the directory are removed from the target subtree.

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. 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 is available here: hookldappam.groovy

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

Let’s first look at the LdapPAM class. PAM is short for plugable 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 probably enable SSL/TLS when using this module.
The second method authenticate performs the actual authentication. It’s called with a set of tokens as collected by the specified client module and return an 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 whith 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

Possible improvements / TODO