IBM Cognos BI: Setting up multi-tenancy environment using Custom Java Provider

In one of my previous blog, we saw how to set up IBM Cognos BI security using Java based Custom Authentication Provider. We’ll use this work as base and advance it here by enabling multitenancy so it is highly recommended to go thru previous blog before proceeding further.  If you are new to multitenancy concept you may also want to go thru “Setting up multi-tenancy environment in IBM Cognos 10.2 BI using LDAP”. Here we’ll see that how we can set up similar multi-tenancy environment in IBM Cognos 10.2.1 BI using Custom Java Provider.

Multitenant environments

Multitenancy provides the capability to support multiple customers or organizations, called tenants, by using a single deployment of an application while ensuring that each tenant users can access only the data that they are authorized to use. Such applications are called multitenant applications. Multitenant applications minimize the extra costs associated with these environments.

IBM Cognos BI provides built-in multitenancy capabilities. It does not require you to perform additional administration tasks to manage tenants because it reuses your existing authentication infrastructure. That means even when multitenancy is enabled you continue manage your users and groups in similar way.

Enabling Multitenancy

Determine whether you must apply the multitenancy settings to all configured namespaces or to individual namespaces. Multitenancy properties for a specific namespace override any multitenancy properties that are set globally. If a namespace is not configured to use multitenancy, then policies and permissions for objects are used to determine who can access the objects. If multitenancy is applied to multiple namespaces, the tenant IDs in all namespaces must be unique.

In our case we created two tables “USERS” & “GROUPS” in DB2 database to be used by MyJavaAuthProvider class. I’ve added few records as shown below.

 

Lets follow the steps to enable multitenancy with “MyJavaAuthProvider” -

1. Open IBM Cognos Configuration.
2. Choose if you want to configure multitenancy settings globally for all namespaces, or for a specific namespace.
• To configure multitenancy for all namespaces, in the Explorer window, for the Security category, click Authentication.

• To configure multitenancy for one namespace like in our case its “MyJavaAuthProvider”, click the namespace that you want to configure.
2. Under Multitenancy, click the edit button for the “Tenant ID Mapping” property. Specify one of the following properties:

Pattern - To use specific object attributes from your authentication provider, such as a TenantID, you could specify the following value for this property:

“~/parameters/tenant” in our case.

Provider class - To use a custom Java class, you only need to specify the name of the Java class that you created.

4. In the Explorer window, right-click Authentication, and click Test. If multitenancy is properly configured, your tenant ID is displayed in the details. If multitenancy is not properly configured, the tenant ID is not displayed. If the latter is true, ensure that the multitenancy property values are correct and test again.

5. I’ve also stopped anonymous access from Cognos Namespace property. From the File menu, click Save.
6. Restart the IBM Cognos service for the changes to take effect. You can observer message “Multi-tenancy is enabled” in Details>> as shown below.

On success service start you can see Login screen before entering Welcome page.

Tenant administration

Tenant administration tasks are performed by members of the System Administrators role. System administrators can view and manage all objects in the content store. By default, objects created by a system administrator are tagged with his or her tenant ID. Because users who belong to the System Administrators role have their own tenant IDs, impersonation (Impersonate Tenant) must be used when performing tasks on behalf of a specific tenant. Here in our case let ‘admin’ user and ‘administrators’ group join System Administrators role. Here are the steps.

1.      Login as admin user and open Security tab from Cognos Administration screen.

2.      Click on Cognos Namespace.

3.      Last entry would be “System Administrators”. Open its ‘properties’, go to ‘members’ tab and add ‘admin’ user and ‘administrators’ group from ‘MyJavaAuthProvider’. Click OK.

System administrators must create a tenant in Cognos Administration before the tenant users can access Cognos server. The Multitenancy tab in IBM Cognos Administration is the central area for tenant administration. On this tab, the administrator can view and manage all tenants registered in the current Cognos environment. Lets register our tenants –

1.      In IBM Cognos Administration, click the Multitenancy tab. On the toolbar, click the New Tenant icon.

2.      Specify the Name and Tenant ID parameters as shown below. Name can be anything but Tenant IDs should be same if you are using the same data shown in above tables.

Name: Customer – A           Tenant ID: CustomerA

Name: Customer – B           Tenant ID: CustomerB

If you want to update the tenant settings later, from the tenant Actions drop-down menu, click Set properties and change the settings on the General tab. For example, you can change the tenant name.

Assigning tentant IDs to existing content

After multitenancy is enabled and the tenant object is created in Cognos Administration, the system administrator assigns tenant IDs to the existing BI objects. All objects belonging to a tenant have the same tenant ID. The tenant IDs are created when a user from a specific tenant logs on to Cognos or the system administrator impersonates the tenant. Tenant IDs can also be created using the software development kit.

In a multitenant environment, all objects in the content store are either public or belong to a single tenant. As a system administrator, you must ensure that the existing objects have a proper tenant ID or are meant to remain public. For example, you can assign tenant IDs to data source connections, but leave the data source itself public.

If the tenant content is not organized into separate folders, you can create a root folder in Cognos Connection for each tenant. This helps to preserve the uniqueness of names in the Cognos BI environment. The Tenant ID is displayed on the General tab in the object properties page. The tenant name associated with each object is shown in the Tenant column in Cognos Connection and Cognos Administration.

Tenant content Deployment

You can export and import the tenant content. You can export:

• Content that belongs to the selected tenants and public content
• Content that belongs to the selected tenants only.
• Public content only

Later, you can import the archive into the target environment. The tenant content can be imported from the deployment archive into the target environment.

When public content is excluded from the tenant export, and a tenant object has public ancestors, the public ancestors are included in the export so that the content references can be preserved in the target system. For example, in a situation where a data source connection belongs to a tenant, but the data source itself is public, the data source is exported.

In Cognos BI version 10.2.0 there was no option to exclude user account information when public content was deployed. This option exists in the product starting with version 10.2.1.

Export operation can be performed from Multitenancy tab In IBM Cognos Administration from the tenant Actions drop-down menu.

Disabling or Deleting tenants

You can disable a tenant when you want to prevent the tenant users from accessing Cognos BI and modifying the tenant content. This should typically be done before deploying a tenant and all of the tenant content. As a best practice, you should disable the tenant before terminating its active user sessions.

You can delete a tenant from Cognos BI environment. This might be needed if the tenant was permanently moved to a different or no longer required. Before deleting a tenant, you must terminate the tenant active user sessions. Otherwise, you will not be able to delete the tenant.

When you delete a tenant, you also delete all content associated with the tenant, such as reports, user profiles, or content store utilization tasks.

Both the operations can be performed from Multitenancy tab In IBM Cognos Administration from the tenant Actions drop-down menu.

 

References - 

IBM Cognos Business Intelligence 10.2.1 Administration and Security Guide 
Hint: On Windows Cognos server you'll find it here - C:/Program Files/IBM/cognos/c10_64/webcontent/documentation/en/ug_cra.pdf

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.