Setting up multi-tenancy environment in IBM Cognos 10.2 BI using LDAP

Multi-Tenancy has always been supported in IBM Cognos BI either by authentication source or with distributed installation & configuration. Cognos 10.2 BI has greatly enhanced it by newly provided built-in multi-tenancy capability which is incredibly valuable to IBM Cognos ISVs and business partners. It is particularly very useful to the organizations those have deployed Cognos BI in a federated manner and are looking to segment different sub-organizations within their shared IBM Cognos platform architecture more easily.

Multitenancy provides the capability to support multiple customers or organizations (tenants) by using a single deployment of an application, while ensuring that the users belonging to each tenant can access only the data that they are authorized to use. Such applications are called multi-tenant applications. IBM Cognos Business Intelligence (BI) provides capabilities that make it easier to administer and secure multi-tenant applications at the same time minimize the extra costs associated with these environments.

The following diagram shows how the Cognos BI multitenancy capabilities isolate access to objects in your content store. Users can access only the objects that they are authorized to access within each tenant grouping.

Figure. Content store configured to use the Cognos BI multitenancy capabilities

The system administrator can access all objects in the content store. In this example, the users would have access to the following objects:

• Users belonging to Tenant 1 can access object_1, object_2 exclusively.
• Users belonging to Tenant 2 can exclusively access object_4, object_5, and object_6.
• object_3 is shared between users from both tenants but based on tenant properties they can access permitted data thru object_3.

This newly introduced multi-tenancy feature does not require performing additional administration tasks to manage tenants because it reuses your existing authentication infrastructure. When multi-tenancy is enabled, it does not affect how you currently manage your users and groups. It allows the administrator to create a TenantID and use the TenantID session parameter in Cognos modeling tool (Framework Manager) to restrict the access to the different components on Cognos Connection, using security features in the Cognos Namespace.  It also provides the ability to audit by Tenant and makes it much easier to administer and maintain the environment.

This article describes the step by step procedure to

1)     Configuring multi-tenancy feature in IBM Cognos 10.2 BI environment.

2)     Implementing multi-tenancy for sample tenants (exclusive & shared access)

Configuring Multi-tenancy in Cognos BI

1) First of all, identify how tenancy information (grouping) is determined in technical environment for the individual users. Then, the tenancy information can be associated to specific multi-tenancy properties. You can use any LDAP authentication provider here but for illustration we are using ApacheDS to determine tenancy information. 

If you are new to LDAP and need help in creating Apache Directory Server (ApacheDS) based LDAP environment to secure IBM Cognos 10.2 BI please refer my blog –
Using ApacheDS based LDAP to secure IBM Cognos 10.2 BI environment

It would take you thru steps of installation, configuration of ApacheDS along with Cognos LDAP integration. It’ll also help you manage ApacheDS environment using Apache Directory Studio.

Users	Attribute value for ‘l’
admin (domain administrator)	0
user1	1
user2	2
user3	3
user4	4

2) It is assumed that Cognos 10.2 BI server is already installed & configured and LDAP integration is completed. LDAP setting can be verified with ‘IBM Cognos Configuration’ (Start -> All Programs -> IBM Cognos 10 (‘IBM Cognos 10 – 64’ in case of 64-bit installation) in the Explorer window, under Security-> Authentication. For example, ‘ADS’ namespace shown with its properties.

3) Select ‘Advanced Properties’ from right window (Resource properties) and add two new values -

a)     Name – ‘multitenancy.TenantPattern’ value – ‘~/parameters/tenantID’

b)     Name – ‘AdditionalUserPropertiesToQuery’ value – ‘parameters’

4) Now, select ‘Custom Properties’ from right window (Resource properties) and add a new value –

Name – ‘tenantID’ value – ‘l’

5) From the File menu, click Save. Test connectivity to the namespace by right clicking on the name under Security, Authentication and selecting test. If the test is successful, this message box will appear.

Save the new configuration and restart Cognos service from toolbar.  

 

Implementing Multi-tenancy for sample tenants (exclusive access)

After multi-tenancy is enabled, the system administrator assigns tenant IDs to the existing content store 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 IBM Cognos Business Intelligence, or the system administrator impersonates the tenant. Tenant IDs can also be created using the software development kit.
In our case we have 5 tenants with Tenant IDs assigned as shown in below chart -

Tenants	Tenant ID assigned
admin (domain administrator)	0
user1	1
user2	2
user3	3
user4	4

1) Now we’ll make ‘admin’ as a system administrator so login as ‘admin’ and launch IBM Cognos Administration.

Click on ‘Users, Groups, and Roles’ under ‘Security’ tab and select Cognos Namespace.

Scroll to bottom and select ‘set properties’ for the ‘System Administrators’ Group

From the ‘Members’ tab, we need to add some valid administrators (‘admin’ in our case) by selecting ‘Add’. Check ‘Select Users in the List’

Now we can remove the ‘Everyone’ group from the ‘System Administrators’ by selecting the checkbox next to everyone and selecting ‘Remove’. Select OK.

2) 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 exclusively. Having separate folders for each tenant helps to preserve the uniqueness of names in the Cognos BI environment.

Every object (folder, package, report, connection etc) in the content store has a tenant ID value that indicates which tenant the object belongs to. This value is based on the tenant ID associated with the session of the user who created the object. Here we’ll provide exclusive access of folders to respective tenants.

As shown below, 5 folders are created having same name as users. Click on ‘Set properties’ icon.

On the General tab, click Set next to the Tenant ID. Choose a tenant ID from the list of available IDs, and click OK. Choose ‘1’ for user1. Similarly set respective tenant ID on folder for all tenants (users). The LDAP administrator can add the ‘l’ attribute to those users who do not have this property set now, without having to reconfigure IBM Cognos BI v10.2.

3) Now for testing purpose, logoff as ‘admin’ and login as ‘user1’. Notice that user1 can only see folder ‘user1’.

If you try to set properties for ‘user1’ folder, notice that ‘TenantID’ property does not exist because user1 is not system administrator.

Implementing Multi-tenancy for sample tenants (shared access)

Now, we’ll see how to provide the shared access to an object which behaves differently for different tenant based on their tenant ID value. There are two ways.

• No tenant ID assigned to publicly available objects hence they are available to all tenants without any change in behavior.

• Using the TenantID session parameter in Cognos modeling tool (Framework Manager) to restrict the access at runtime. Multitenancy would be implemented to all the objects (reports, queries, analysis etc.) that are based on such metadata model/packages. Even if you don’t set tenantID property for these objects from Cognos Connection, objects would be available to all tenants but behave differently for different tenants.

Here we’ll quickly filter the metadata model using tenant ID session parameter and export the package to create a demo report to be used by all tenants.

1) Open ‘IBM Cognos Framework Manager’ (Start -> All Programs -> IBM Cognos 10). If it is not available then first install, configure and make sure its working. 

Here’s we are using two tables ‘ORDER_HEADER’ and ‘ORDER_DETAILS’ from ‘GOSALES’ schema of ‘great_outdoors_sales’ datasource connection (GS_DB). Tenant_ID is added in ORDER_HEADER, as you can see in below snapshot. We created a copy of ORDER_HEADER in GS_DB database and renamed its ORDER_METHOD_CODE column with TENANT_ID.

2) Test the results for TENANT_ID, RETAILER_NAME, QUANTITY and UNIT_SALE_PRICE with Auto Sum box checked. Notice that all the values for TENANT_ID would be from 1 to 7. Click on ‘Close’ button.

3) Double click on ‘ORDER_HEADER’ query subject and add a filter in ‘filters’ tab with “[great_outdoors_sales].[ORDER_HEADER].[TENANT_ID] = #sq($tenantID)#” expression.

Save project and publish the package (‘multitenancy_pack’ in our case).

4) Launch Report Studio from Cognos Connection using ‘multitenancy_pack’ package. Create a report to demonstrate multitenancy feature, as shown in below snapshot.

In a 1x2 table, two objects are placed – one bar chart and one list using RETAILER_NAME, QUANTITY and UNIT_SALE_PRICE query items. REVENUE is the calculated field –

REVENUE = QUANTITY * UNIT_SALE_PRICE

TENANT_ID is placed in title as a ‘Singleton’ object with ‘Aggregate function’ property set to ‘none’.

Save the report as ‘Demo Report’ and close Report Studio.

5) Logoff and login as ‘user3’ and run the ‘demo report’ created in above step. Notice that data values are filtered for respective tenant ID value which is ‘3’ for user3. Report title shows the tenant ID as area code.

Now logoff again and login as ‘user4’ to run the same report. You can notice the change in data values for user4. Similarly many such reports can be created using package multitenancy_pack. 

Besides the capabilities shown above, you can export and import the tenant content using the Cognos deployment capabilities. The deployment archive includes all tenant content and all public content associated with the tenant.

After multi-tenancy is enabled, you can also record tenant activities using an audit logging database. Cognos provides sample audit reports that show how to use the tenancy information to monitor certain user activities. For more information about how to use Cognos configuration to set up a logging database, see the IBM Cognos Business Intelligence Installation Guide and Configuration Guide.