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