Use ApacheDS with IBM Cognos BI as LDAP Directory Server
The Apache Directory Server is part of the Apache Directory project and can be used as an LDAP server or authentication provider with IBM Cognos BI. This can be useful if you don't have a Directory Server in your organization or you just want to install a demo platform. In previous IBM Cognos BI versions you could use the Microsoft Windows NTLM namespace on Windows, but this is not longer supported since Cognos 10.2. Neither is the Series 7 Cognos Access Manager and Sun ONE Directory Server supplied as with pre 8.4 IBM Cognos BI versions.
The Apache Directory project consists of 2 parts, a Directory Server: ApacheDS, and an interface; Apache Directory Studio. The below describes how to use the ApacheDS in combination with IBM Cognos BI 10.2.1. So it assumes you have ApacheDS, Apache Directory Studio V2 and BI 10.2.1 (or other version) installed and in working order. The purpose here was a demo platform, so don't deduct any best practices from this. Don't forget to read the notes at the bottom.
Connect to ApacheDS from Apache Directory Studio
When you open Apache Directory Studio after a fresh install it is an empty canvas.
The first step is to connect to an LDAP server, ApacheDS in this case.
Steps:
Click the "New Connection ..." button to start the New LDAP Connection wizard.
Enter a Connection name, this can be anything, "ApacheDS" in this example.
Enter the Hostname server, "localhost" in this example.
Enter the Port number of Apache DS, by default this is "10389".
Manipulate other options as you please and click "Next"
Enter the authentication parameters, by default the Bind DN is "ui=admin,ou=system" and the Bind password is "secret". Obviously change this for non demo use. Click "Next".
The remaining screens, I left standard. Click "Finish".
Click the picture below to see larger screenshots of the New LDAP Connection wizard steps.
You should end up with something like the below with the default DIT (Directory Information Tree) on the left.
Create group objects
The next step is to set up a group en folder structure that you want to use in Cognos. It is always a good idea to think and design the structure before you start configuring. For this demo platform there is only a single group object of the type "organizationalUnit" within the default domain, this will map and work well in Cognos.
Steps:
Right click on the default domain "dc=example,dc=com" and select "New" and "New Entry..." to open the New Entry wizard.
Select "Create entry from scratch", later on you can use existing entries as template, and click "Next".
Select the object class "organizationalUnit" in the Object Classes selection screen and click "Next".
For the RDN (Relative Distinguished Name) select "ou" (the name) and type a name, in this case "CognosUsers", but you can pick anything. Below the RDN, you can than see the DN (Distinguished Name) that you can use to reference later on for this part of the DIT. Click "Next"
In the last screen you can enter additional attributes like e.g. a description. Not in the picture. Click "Finish".
Click the picture below to see larger screenshots of the New Entry wizard steps.
You will then end up with a new organizationalUnit with the name CognosUsers in the DIT.
Create users
Now we can add some users to "CognosUsers". The steps are similar to the above:
Right click on "CognosUsers" and select "New" and "New Entry..." to open the New Entry wizard.
Select "Create entry from scratch", later on you can use existing entries as template, and click "Next".
Select the object class "inetOrgPerson" in the Object Classes selection screen and click "Next".
For the RDN select "uid" (the user name) and type a name, in this case "Leonard", but you can pick anything. Keep in mind that by default this will be the log on name in IBM Cognos BI. This can be changed in Cognos Configuration. Do not add any more items here as they will then become part of the DN. This can be useful in some cases but not many. Click "Next".
In the last screen you can again add additional fields. Note that "cn" (name) and "sn" (surname) have to have values. You can include others as well. You can stick to the default mappings from Cognos Configuration or add your own and add them as Custom properties in Cognos Configuration. Please refer to the pictures below for sample values. Click "Finish".
Click the picture below to have larger screenshots of the different steps:
Don't forget to add an attribute to the users of the type "userPassword" as I did:
You will then end up with the user added to the tree. In the pic below a couple of more users have been added. The process is the same for all.
That's it for now in Apache Directory Studio.
Configure a namespace in IBM Cognos Configuration
By now there is a working LDAP and some testusers available. The next task is to add ApacheDS as an Authentication provider that can be used in IBM Cognos BI. These are the steps:
Open IBM Cognos Configuration.
Right click on "Authentication" in the tree to add a new namespace.
In the New Resource" windows, enter a name, this can be anything, and an LDAP type, select "LDAP - General default values".
If you click the new namespace, you will see a number of variables on the right, some are prefilled and some are not.
Enter or change the following parameters:
Namespace ID: Can be anything you want, "ApacheDS" in this example.
Host and port: This is the server name and the LDAP port number, "localhost:10389" in this case. If you don't know what to enter, go back to Apache Directory Studio and check the LDAP connection properties.
Base Distinguished Name: This should be the complete DN path up to the class entry-level that you want to include. In this example this is "ou=CognosUsers,dc=example,dc=com". Again if you don't know what to enter, go to the entry properties in Apache Directory Studio.
User lookup: change this to "uid=${userID}". If you want to use something else for authentication then the uid, this wil be different.
Use external identity mapping?: Change to "True".
Bind user DN and password: This should be the complete DN path of a user that will be used to search the namespace. In this case "uid=Admin,ou=CognosUsers,dc=example,dc=com" and the password, which is a user created previously. The exact DN can be found via the entry properties of that user in Apache Directory Server.
Use bind credentials for search: Change to "True".
Unique identifier: Change to "uid". Make sure each entry than has a uid.
Test the new namespace.
The result should then look something like this:
The last thing is to check all the mappings you want to use. It is important that the names are exactly the same in Cognos Configuration and ApacheDS. By default they map rather well, but check them. Also, if you have more parameters in ApacheDS than available here, you can add them via the custom properties. The mappings available in ApacheDS and mapped here in Cognos Configuration are the things that you can make available in Framework Manager. Can be highly useful when you want to apply data driven security.
Save and restart Cognos
Add users in Cognos
Finally the new namespace can be configured in IBM Cognos Administration.
Remember that you can only search a namespace when you log on with a user from that namespace. This means that if you want e.g. define an admin, you have to add the everyone group temporarily to the systems administrators group in Cognos Administration. Because you need to be an admin to be able to do so, but no user in your new namespace is an admin.
Log on with a new user.
Go to Cognos Administration and configure a new admin.
Test the new user and delete the everyone group again.
If this is a new install, don't forget to disable anonymous access in Cognos Configuration (and restart).
Notes
A useful dictionary with LDAP related terminology and abbreviations, here.
This post does not follow any best practices regarding the organization of groups, roles and users. The only purpose is to document how ApacheDS can work with IBM Cognos BI and what needs to be configured.