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.

 

IBM SPSS Statistics integration with Cognos BI

In today’s data-driven landscape, the ability to analyze information to drive decision-making and solve problems is fundamental for success. IBM SPSS Statistics is commonly used tool by statisticians/analytics professionals for ad hoc analysis and hypothesis testing. Rich in Extensive data preparation, analysis and visualization features, IBM SPSS Statistics provides insight into a sample of data and tools for prediction and forecasting. Generally speaking, it helps in:

• Understanding how to leverage the data collected and being able to fill in the gaps
• Understanding the underlying relationships in data from the data warehouse or various repositories and how they impact decisions
• Recognizing what influences business outcomes and to what degree by recognizing what variables drive outcomes
• Testing assumptions before applying the theory to real world events. Also when to adjust or abandon these assumptions

IBM SPSS Statistics offers the full scope of statistical and analytical capabilities that organizations require. It’s an easy-to-use, comprehensive software solution that:

1. Addresses the entire analytical process from planning and data preparation to analysis, reporting and deployment
2. Allows application of statistical information to data to improve understanding and decision quality throughout the enterprise.
3. Provides advanced analysis using statistical algorithms (for regression, correlation, segmentation etc.), and display of those results.
4. Enterprise scale and extensibility as part of the SPSS suite of products.
5. Works with all common data types, external programming languages, operating systems and file types
6. Use with Cognos BI for statistical information in reports, dashboards and scorecards.

Here in this blog I would like to focus on last bullet which says how IBM SPSS Statistics can work with IBM Cognos BI. If you are new to Cognos BI please refer my previous blog “IBM Business Intelligence Software & Its Core Capabilities”. I’ve installed IBM SPSS Statistics 22 and IBM Cognos BI 10.2.1 on 64-bit Windows 7 Professional environment.

Reading Cognos data

Lets read Cognos BI data by choosing menu “File > Read Cognos Data”

Next, Specify the URL for the Cognos server (external dispatcher URI). Description of each field is given as under.

Cognos server URL. The URL of the IBM Cognos Business Intelligence server. This is the value of the "external dispatcher URI" environment property of IBM Cognos Configuration on the server. Contact your system administrator for more information

Mode. Select Set Credentials if you need to log in with a specific namespace, username and password (for example, as an administrator). Select Use Anonymous connection to log in with no user credentials, in which case you do not fill in the other fields.

Namespace ID. The security authentication provider used to log on to the server. The authentication provider is used to define and maintain users, groups, and roles, and to control the authentication process.

User name. Enter the user name with which to log on to the server.

Password. Enter the password associated with the specified user name.

Save as Default. Saves these settings as your default, to avoid having to re-enter them each time.

 

Now, specify the location of the data package or report as shown below. 

  

And select the data fields or report that you want to read.

Optionally, you can:

• Select filters for data packages.
• Import aggregated data instead of raw data.
• Specify parameter values.

 

Once you Run and finish it, you can see the data in Statistics Data Editor. Now you are ready to work & analyze your data using SPSS statistical features.

Export Cognos Active Report

Once you are done with your analysis and ready with output, you may want to export it. Export Output saves Viewer output in HTML, text, Word/RTF, Excel, PowerPoint (requires PowerPoint 97 or later), and PDF formats. Charts can also be exported in a number of different graphics formats.

Note: Export to PowerPoint is available only on Windows operating systems and is not available in the Student Version.

To Export Output

1. Make the Viewer the active window (click anywhere in the window).
2. From the menus choose: File > Export...
3. Enter a filename (or prefix for charts) and select “Web Report (*.htm or *.mht)” as export type as shown below.

4. Now click on “Change Options” button

This Cognos Active report is now ready and  users can easily export their output with others to view & interact on smart devices (iPhone, iPad, iPod, Android and Windows 8)

Cognos Active reports enables quick decision-making anytime and anywhere. Also users can take advantage of IBM Cognos Mobile app (available on iPad) by exporting their output as Cognos Active Report (.mht format).

IBM Cognos Active Report provides an interactive analytics experience in a self-contained Cognos Business Intelligence application for browsing and exploring data offline. Report authors can build reports targeted to users needs, keeping the user experience simple and engaging. Mobile workers can take their data with them to discover opportunities and analyze trends even when they are nowhere near a network.

Want to know more about Cognos Active Report? Please refer www.ibm.com/software/analytics/cognos/business-intelligence/active-report.html

Now, whatever steps we just followed above generates scripts which can be used to automate entire job. The scripting facility allows you to automate tasks, including:

• Opening and saving data files.
• Exporting charts as graphic files in a variety of formats.
• Customizing output in the Viewer.

A number of scripts are included with the software, in the Samples subdirectory of the directory where IBM SPSS Statistics is installed. You can use these scripts as they are or you can customize them to your needs. For more information on scripting and automation please refer http://pic.dhe.ibm.com/infocenter/spssstat/v22r0m0/topic/com.ibm.spss.statistics.help/spss/base/scripts_overview.htm

 

References:

IBM SPSS Statistics 22 product documentation is available at:

http://pic.dhe.ibm.com/infocenter/spssstat/v22r0m0/

Join SPSS Community

http://www.ibm.com/developerworks/spssdevcentral

Cognos Active Report

www.ibm.com/software/analytics/cognos/business-intelligence/active-report.html