Setting up IBM Cognos BI security using Java based Custom Authentication Provider

An authentication provider implements all the functionality required by Cognos to communicate with an authentication source. It includes

• User authentication using external authentication sources
• Namespace searches
• Trusted credentials management
• Authentication provider configuration

The following diagram shows the IBM Cognos security architecture when a full authentication provider is implemented.

You may ask why Custom Authentication Provider when you have LDAP and other standard solutions? There are cases –

1)      You want to integrate Cognos BI with your existing application and provide Single Sign On but you are using database to store users/groups credentials in existing application.

2)      Another case where you are using your own algorithm, protocol, business rules or programming logic to authenticate users.

 
Developing a Custom Authentication Provider

To implement a custom authentication provider, you must have knowledge of the Java programming language. Along with Java you should also be familiar with the following:

1)  XPath, the XML search language of the World-Wide Web Consortium (W3C)  
2) The IBM Cognos Software Development Kit, particularly the BiBusHeader class and user authentication methods.

When you create a trusted sign-on provider, the following tasks are involved:

1. Creating a trusted single sign-on provider
2. Configuring the namespace interface
3. Creating a manifest for the jar file
4. Registering an authentication listener

Before we start with these tasks step-by-step make sure you have Cognos BI Server and Cognos SDK is installed. Few Java samples are available in the install_location/sdk/java/AuthenticationProvider directory which we’ll use here. You would also require Java Development Kit to compile .java files. For this demo I am using Cognos BI 10.2.1 and IBM DB2 10.5 on Windows 7 Professional OS environment.

Now, let’s start with

Task – 1) Creating a trusted single sign-on provider

A trusted sign-on provider is used to determine the user's identity and communicate it to the appropriate authentication namespace configured using an authentication provider supported by Cognos BI. The user's identity must be available to Cognos BI before any secured object can be accessed. With the Trusted sign-on Provider API, you can do the following:

• Add or remove an environment variable
• Add or remove a trusted environment variable for single sign-on
• Set a cookie
• Add or remove a credential
• Prompt a user for information (user recoverable exception)
• Prompt the system for information (system recoverable exception)
• Set a different namespace by setting an environment variable

The trusted sign-on provider receives an authentication request from IBM Cognos BI and modifies it, as required, to communicate with the provider authentication namespace. For example, it reads a cookie, decrypts it, parses out the user name, and sets the trusted environment variable, such as REMOTE_USER, to the required user name. Then, it sends the authentication request back to IBM Cognos BI, specifying a full authentication namespace to process the request with the environment variable now set.

For a provider to successfully perform the trusted sign-on functionality, you must implement the INamespaceTrustedsignonProvider interface. For more details you can download “Custom Authentication Provider Developer Guide” or find it in C:/Program Files/IBM/cognos/c10_64/webcontent/documentation/en/dg_auth.pdf.

Depending on the Cognos configuration, different session information is available for single sign-on functionality. The session information available from the gateways that can be configured for IBM Cognos BI is described here:

CGI gateway

CGI environment variables, HTTP header variables, REMOTE_USER

ISAPI gateway

HTTP header variables, REMOTE_USER

Apache MOD gateway

HTTP header variables, REMOTE_USER

Servlet gateway, or servlet dispatcher

HTTP header variables, REMOTE_USER, USER_PRINCIPAL (USER_PRINCIPAL is how the gateway or dispatcher exposes the J2EE user principal name to providers)

Here we’ll go ahead with “JDBCSample” taken from <CognosInstall>\sdk\java\AuthenticationProvider\ folder. There are two versions of the JDBC provider sample. The classic version (JDBCSample.java) does not support the new session failover capabilities of IBM Cognos that were introudced in 10.2.1.

The restorable version (RestorableJDBCSample.java) can handle restoring a session after failover, and demonstrates the changes necessary to implement failover in your own custom provider so we’ll go with this version.

You may want to have a look at “RestorableJDBCSample.java”. You can also change few things here and there to customize it for your requirements. Open “dbInit_db2.sql” file to see the table structure for your authentication provider. You would find two tables “USERS” & “GROUPS” and one view. You can change DDL as you like and run this script against DB2 database. Alternatively “dbInit_sqlserver.sql” can be used for MS SQL Server.

I have created 6 users (admin, user1,  user2, user3, user4, user5) and two groups (administrators, users) for demo purpose. Next, we need to set properties in “JDBC_Config_Restorable.properties” file available in configuration folder and change properties as per your settings.

Note: Currently passwords are stored in table as text but you can use encryption functions before store them to make it more secure.

Now, follow the steps mentioned in readme.txt file, doing the same here.

Change the directory
cd C:\Program Files\IBM\cognos\c10_64\sdk\java\AuthenticationProvider\MultiTenancyTenantProviderSample

Add the Java SDK to your path.
set PATH=C:\Program Files\Java\jdk1.6.0_26\bin;%PATH%

Build the sample using the command build.bat

Now you would see “CAM_AAA_JDBCSample.jar” file in the directory. Copy this jar file along DB2 JDBC 32-bit drivers to <Cognos install>/webapps/p2pd/WEB-INF/lib.

Also copy Configuration\JDBC_Config_Restorable.properties file in <Cognos install>/configuration folder. We need to rename this file with “JDBC_Config_”+ NameSpaceID(case sensitive) +”.properties”. For example – if NameSpaceID is MyJavaAuthProvider then filename would be “JDBC_Config_ MyJavaAuthProvider.properties”.

Task-2) Configuring the namespace interface

Add a “New resource -> Namespace” under Security -> Authentication in Cognos Configuration tool as shown below.

Keep “Custome Java Provider” as Type, you can choose Name of your choice. Select Ok.

Add the following entries to the properties of your authentication namespace:
Namespace ID = MyJavaAuthProvider (Remember we renamed property file using this name)
Java class name = JDBCSample

If you want to stop anonymous access then you can disable it by setting a property in ‘Cognos’ name space as shown in the picture below.

Save configuration and restart Cognos services. Select your Authentication provider and test the connection. If it works the go ahead or troubleshoot the problems unless it works.

Task – 3) Creating a Manifest for the jar File

When you write a custom authentication provider, you must produce a jar file that contains the following information in its Manifest:

• Specification-Title: IBM® Cognos® Custom Provider SDK
• Specification-Version: 1.1
• Specification-Vendor: IBM Corp.

This part we are already covering. MANIFEST file with above content is part of JDBCSample folder but we need to remember it when we create jar separately.

Task – 4) Registering an authentication listener

The Custom Java authentication provider API includes the following authentication events:

·         Logon

This event is called after a successful logon. If a user logs on to multiple namespaces, there is a logon event for each namespace and the passportID remains the same.

·         Logoff

This event is called after a logoff request is issued from a user and before the passport is destroyed. A logoff cannot fail. There is one logoff event for each namespace to which a user is authenticated.

·         LogonExpired

This event is called when a passport expires and before the passport is destroyed. A logonExpired cannot fail. There is one logonExpired event for each namespace to which a user is authenticated.
The interface used to implement a Cognos authentication listener is named IAuthenticationListener. For more information about this interface, see the documentation in the install_location/sdk/java/AuthenticationProvider/javadoc directory.

You can register an authentication listener for all namespaces or for specific namespaces. Lets register our authentication listener by following below steps -

1.      Go to the install_location/configuration directory.

2.      Open the file AAA.properties.sample using a text editor.

3.      Edit the file by typing the appropriate parameters instead of the <your java class> placeholders.

4.      Save the file as AAA.properties.

 With this Java based Custom Authentication Provider is set for your IBM Cognos BI environment. Users listed in DB table can login and you can have SSO with other applications using same provider as well.

Now you can login.

To set the security privileges for users you can go IBM Cognos Administration -> Security Tab.