IBM Cognos Proven Practices

Securing the IBM Cognos 10 BI Environment

Nature of Document: Proven Practice; Product(s): IBM Cognos 10 BI; Area of Interest: Security; Version: 1.1


Content series:

This content is part # of # in the series: IBM Cognos Proven Practices

Stay tuned for additional content in this series.

This content is part of the series:IBM Cognos Proven Practices

Stay tuned for additional content in this series.


This document provides a set of proven practices and guidelines, to be taken into consideration when securing the IBM Cognos 10 BI environment.

The intended audience for this paper are IBM Cognos 10 BI application administrators, who will be responsible for designing the IBM Cognos 10 architecture and/or developing the project. The contents are not end user relevant as most of the recommendations need to be implemented by IBM Cognos administrators prior to end user roll out.


The recommendations and practices described in this document are not specific to any platform or deployment architecture. Examples are provided based off a Windows install though and all statements apply to the products listed on the cover page (including Fix Pack (FP) and Refresh Pack (RP) releases) unless explicitly stated otherwise.

Exclusions and Exceptions

While designed to be as generic as possible to be applicable to the majority of installations, some statements might not apply to specific environments. Special consideration must be taken to ensure that the recommendations given here meet the requirements set out for your deployment and adhere to any security policies applicable to your environment.

Guidelines on Securing IBM Cognos 10 BI Environments

IBM Cognos 10 products offer flexible and versatile security features which facilitate integration in most, if not all, existing security environments. The challenge is to start off from a solid base configuration which is sufficient for testing and/or development environments and then move on to thorough security implementations and integrations. IBM Cognos 10 offers all that out of the box.

The following chapters will describe some guidelines and recommendations broken out by the tool used to configure them. We'll cover authentication and authorization topics and provide some Best Practices to follow.

Before starting, the first step is to clearly define the requirements, below is a list of questions that should be answered regarding IBM Cognos 10 BI security prior to starting the implementation.

  • What authentication source(s) are being used? The most common authentication sources are LDAP and Active Directory but there are others. Ensure that you have a contact available to help you understand the authentication source contents and structures as well as the necessary technical information such as server, port and required credentials. Specific pieces of information may be required to follow some Best Practice recommendations.
  • Are you using a single security namespace or multiple security namespaces? Depending on the requirement one may face the challenge of “automatically” authenticating a user to multiple namespaces upon login. While this is not supported by IBM Cognos 10 BI, it can be solved with .NET or JavaScript scripting techniques.
  • Will users be authenticated to IBM Cognos BI explicitly or shall there be some sort of Single Sign-On (SSO) based on authentication from some other security layer? If SSO from another source to IBM Cognos 10 is required, make sure you evaluate whether this is a nice-to-have or a must-have feature. If it is required, then solve the SSO challenge technically first before defining authorization since SSO may have implications on the required namespaces or their configuration. In particular SSO can impact scheduling, because many SSO credentials may not be appropriate for being stored with schedules as they may expire. This leads to users being prompted for user name and password which they might not know since they are used to SSO.
  • Should the same credentials used to authenticate to IBM Cognos BI 10 also be used to authenticate to a query database (user pass-through)? This can be a complex and challenging setup and not supported in all combinations of authentication source and databases. Evaluate if alternatives using stored database signons are feasible but note that this may have implications on authorization because the signons must be maintained and properly secured in IBM Cognos 10 BI.
  • What level of security is required? Is this system accessible externally or only internally? It is a recommended Best Practice to implement the Secure Socket Layer (SSL) protocol on the web server hosting the IBM Cognos 10 BI Gateway if the system is accessible externally. Most likely your company's security policies will demand this and potentially other additional security measures. This will have implications on the configuration of SSL in IBM Cognos 10 BI.
  • How sensitive is the data for internal/external users? Depending on the security requirement you will want to look at encrypting temporary files and encrypting all traffic over the network even internally. Again, these considerations have implications on the configuration of the IBM Cognos 10 BI install.
  • Will IBM Cognos 10 BI be integrated with other IBM products such as Lotus Connections, IBM Cognos TM1 or IBM Cognos Planning? Integration may imply changes to the security after the fact if not planned carefully. Discuss integration scenarios with your IBM Cognos representative ahead of performing any security implementation.

Those are just some examples but what this demonstrates is how many aspects of security may become relevant to IBM Cognos 10 BI. There are obviously many security aspects to consider but the good news is that all of those can be handled in IBM Cognos 10 BI. The Best Practice recommendations listed in this document refer to general applicability. For more specific topics, try researching for documents on IBM's developerWorks web site located at

IBM Cognos Configuration

This section will discuss the settings and configuration items related to security that are specified in IBM Cognos Configuration. These are usually implemented right after installation and provide the basis for the subsequent tasks that are covered later.

Secure Installation

Service Account

The first decision affecting security may have already been made. It is possible that IBM Cognos 10 was installed onto your platform using a particular account and this account may have sufficient file system privileges to run the application. However it is possible that policies or the environment will demand that specific accounts be used for running an application. We refer to that account as the Service Account.

IBM Cognos 10 BI is for the most part a Java web application which is deployed to a Java application server such as IBM WebSphere. Out of the box though, IBM Cognos 10 is delivered pre-deployed to Apache Tomcat, which is not a full Java application server but a subset of one. For the sake of this explanation though, we simply refer to Apache Tomcat as an application server.

If IBM Cognos 10 is run using the out of the box Apache Tomcat, there is a service named cognosbootstrapservice.exe which will start Apache Tomcat and can be configured in IBM Cognos 10 BI Cognos Configuration. On Windows platforms this service is registered as a Windows Service, run by the Local System account by default. On UNIX/LINUX platforms the service is run by the account calling the start script. Thus the Service Account is the account running the application server.

If IBM Cognos 10 BI is deployed to a different application server, usually that server will determine the account used to run IBM Cognos 10 BI and is therefore the Service Account.

It's important to choose a proper Service Account because:

  • This account will instantiate the Java Runtime Environment (JRE) hosting IBM Cognos 10 and all other processes spawned by IBM Cognos 10 such as BiBusTKServerMain, CAM_LPSvr, BmtMDProviderMain and others. All IBM Cognos 10 processes, being either Java or native processes, require file system privileges of different levels to the IBM Cognos 10 installation directory and it's sub-directories.
  • This account is used for printer access.
  • If running on Windows platforms, this account will be used for Microsoft Kerberos interaction required for SSO to IBM Cognos 10 and possibly for authentication to Microsoft databases like SQL Server or Analysis Services.
  • This account will be used to create temporary files and transient files.
  • This account will be used to interact with the platform logging facilities when IBM Cognos 10 is being configured for directing Auditing output to the operating system logging facilities.

A Best Practice is to use a named account specifically assigned to IBM Cognos 10 to perform the installation (provides file system ownership) and the running of IBM Cognos 10. The installation account and the Service Account can be different but additional care must be applied regarding file system permissions.

On Windows platforms where using a named domain account as the Service Account rather than Local System or Network Service, the account must be allowed to authenticate on the machine and should have sufficient file system privileges as well as being properly configured in User Account Control. Depending on the use of sophisticated features like Kerberos SSO, user passthrough to Microsoft data bases and logging to operating system loggers, additional Windows privileges might be required.

On Linux/UNIX platforms the Service Account should share a primary group with the installation account to simplify the question of file system access. The Service Account and it's primary group should be given full access to the installation directory including sub-directories, and all file system permissions for “other” should be revoked. It is recommended that ownership of the installation directory and sub-directories should be granted to the installation owner and the shared primary group only.

Information about the Service Account can be found at the following link from the IBM Cognos 10 Information Center.

Temporary Files

Like most products, IBM Cognos 10 BI utilizes temporary files during the course of ordinary reporting functions. By default, temporary files are written to a temporary folder on the disk. The default location for this is <COG_ROOT>/temp, where <COG_ROOT> denotes the IBM Cognos 10 BI installation directory. The directory is configurable in IBM Cognos Configuration though. The property is named Temporary files location and it resides under the Environment section. To restrict access to the temporary files found in this directory, it is suggested that file system permissions be set to only allow the Service Account full control to the directory, all other accounts should be denied access. If the temporary file location is moved to a directory outside of the IBM Cognos 10 BI installation directory, it is possible that the file system permissions may need to be adjusted.

IBM Cognos 10 BI can also save user session files to the local file system to help reduce the load on Content Manager. If this feature is configured, the location specified for the user session files should be accessible by the Service Account only. Keep in mind that this feature only affects installed instances of Application Tier components. For more information on saving user session files to the local file system refer to the following link from the IBM Cognos 10 Information Center.

Encrypting Temporary Files

If models or recently viewed reports contain sensitive data, then extra precaution should be taken when dealing with these temporary files that are generated. IBM Cognos 10 BI offers the ability to encrypt these temporary files, so that they are unable to be viewed by unauthorized consumers. This does not apply to the user session files though. The property to enable temporary file encryption can be modified using IBM Cognos Configuration. The property is named Encrypt temporary files? and it resides under the under the Environment section. The value should be set to True to enable this feature. The encryption applied is based on a session-based key that is fed to the configured confidentiality cipher.

Dispatcher Passwords

Starting with IBM Cognos BI 8.4, there is a Dispatcher password property which must match between all installed instances of Dispatchers, including installs of just the Application Tier and Content Manager components. The password acts similar to a shared secret in that it prevents Dispatchers which don't know the secret from joining the IBM Cognos 10 BI system. As a Best Practice this password should be changed from the default on all Application Tier and Content Manager installs. The property to set the Dispatcher password can be modified using IBM Cognos Configuration. The property is named Dispatcher password and it resides under the under the Environment section.

Content Store Database

The Content Store database is the central repository for the IBM Cognos 10 BI system. It should be obvious that maximum precaution should be taken to make sure that the database is available and properly secured. The IBM Cognos 10 BI Content Manager component handles access to the Content Store database through a single database signon. The signon is specified in IBM Cognos Configuration and will be saved in an encrypted format to the main IBM Cognos 10 BI configuration file <COG_ROOT>\configuration\cogstartup.xml. However, if the database is accessible from outside of IBM Cognos 10 BI, this will compromise the IBM Cognos 10 BI system stability and security. Though sensitive data will be saved in encrypted form inside the Content Store, saved report outputs or other information which is not necessarily sensitive by default is not encrypted, thus it is important to ensure that no other accounts have read/write access to the Content Store database at the database level. This must be implemented at the database level. For details consult your database administrator.

Authentication concepts

IBM Cognos 10 BI authentication works by deferring the authentication to an external authentication source through a piece of software called an authentication provider. Each authentication provider attaches to a specific type of authentication source such as LDAP, Microsoft Active Directory or SAP BW and implements logic to read security objects and handle the authentication process with it. On top of that, many authentication providers provide support for SSO. Except for a special type of provider, each authentication provider exposes the objects read from the external authentication source in the form of a namespace to IBM Cognos 10 BI. For a single IBM Cognos 10 BI system multiple namespaces can be configured at the same time and thus users from multiple authentication sources can access IBM Cognos 10 BI.

There is a special namespace in IBM Cognos 10 BI called the Cognos namespace. It's not attached to any authentication source and cannot contain users but only groups and roles. The Cognos namespace is not available for authentication but rather it is used to provide a logical mapping layer for security objects from namespaces attached to external authentication sources and application defined authorization objects. An administrator would create groups and roles in the Cognos namespace and assign external security objects, such as users, groups and roles to those objects created in the Cognos namespace. Authorization concepts will be discussed later in the document.

Both the external namespaces and the Cognos namespace are configured in IBM Cognos Configuration. There are also some general settings which influence the authentication which apply regardless of namespace type. We'll start off with some Best Practices for specifying the general settings.

Inactivity timeout

The inactivity timeout setting specifies how many seconds it will take before an authenticated session from a client to IBM Cognos 10 BI is considered expired. A shorter expiry setting may lead to more frequent authentication prompts, a longer expiry setting increases the risk of someone accessing a browser on an unattended workstation if no screen lock protection is in place. If SSO is set up though, this will re-authenticate the user silently in the background without any negative impact. It is recommended to have SSO configured whenever possible. The inactivity timeout is set in IBM Cognos Configuration by setting the Inactivity timeout in seconds property located in the Security > Authentication section. As a Best Practice this should be set according to your security policy. A good starting point is 900 seconds or 15 minutes. That's a quarter of the default value of 3600 seconds but it represents a good trade-off between resource consumption for every active session and user convenience.

Passport encryption

A successful authentication will lead to session objects being created in memory on the Content Manager component. These session objects will contain sensitive user data. If required, it is possible to encrypt these in-memory objects to prevent access to the information by malware or other memory readers. To enable the encryption, use IBM Cognos Configuration to set the Enable the encryption of passport credentials? property located in the Security > Authentication section to True. Keep in mind that this will have a slight impact on performance of authentication and other operations requiring access to the user credentials. As a Best Practice, leave this disabled unless explicitly required by your security policy.

Session sharing

When multiple clients (Framework Manager, Transformer, Planning, etc.) on a single workstation access the same IBM Cognos 10 BI system, it is possible for them to share an authenticated session. While this helps reducing the number of concurrent active sessions that exist in IBM Cognos 10, it's potentially less secure than having separately managed sessions for each client. On the other hand this is required to achieve SSO between multiple clients on a single workstation. The property to set in IBM Cognos Configuration is Allow session information to be shared between client applications? under the Security > Authentication section. The default value for this property is False and the Best Practice is to leave it as False unless there are multiple client applications on a single workstation for which SSO is desired.

Restricting access to IBM Cognos Connection

When a namespace has been configured for authentication it is implied that all users from the underlying authentication source shall be able to authenticate to IBM Cognos BI and access IBM Cognos Connection. This however might not always be the case, as there might be a requirement to limit the access to a subset of all the users contained in the configured authentication source. In IBM Cognos 10 BI this can be achieved by leveraging the configuration property Restrict access to members of the built-in namespace under the section Security > Authentication in IBM Cognos Configuration. If this property is set to True, access will be denied to any user who is not a member of the Cognos namespace either directly or indirectly. The Cognos namespace is the built-in namespace used to map users, groups and roles from external authentication sources to a defined application specific security model. For more information regarding the Cognos namespace, refer to section titled “Authorization Concepts and Best Practice”. By assigning a user or a group/role from an external namespace that the user is a member of to a group or role in the Cognos namespace, the user becomes a member of the Cognos namespace implicitly.

Example: The users Robert Smith and Marla Spears are defined in an LDAP source which is configured as an LDAP namespace for IBM Cognos 10. Robert is assigned to the Consumers role in the Cognos namespace while Marla is not assigned to any group or role in the Cognos namespace. If the Restrict access to members of the built-in namespace? property is set to True, Robert will be able to authenticate to IBM Cognos 10 and have access to Cognos Connection but Marla won't because she's not a member of any group or role in the Cognos namespace.

Auto-renew trusted credentials

As of IBM Cognos 10 there is a new feature which allows IBM Cognos 10 BI to “automatically” update stored credentials for schedules. This feature can be set in IBM Cognos Configuration through the Automatically renew trusted credential property under the Security > Authentication section. To understand the impact of this setting we need to look at some details.

When a user creates a trusted credential to be saved with a schedule or to provide them to a different user for them to use for running reports instead of the user saving the credentials, there is an object created which contains credentials for all namespaces that the user is currently authenticated to. As a result because a single user can authenticate to multiple namespaces in a single session, trusted credentials can potentially contain multiple sets of credentials, one for each namespace. The first namespace the session is authenticated to is called the primary namespace.

A trusted credential is special because the namespace credentials it stores must be usable at any time, not depending on any timestamp. This rules out SSO tickets like Kerberos tokens or SAP tokens as they will expire after a short time and will become unusable. A suitable trusted credential therefore usually is a pair consisting of a user name and a password. However, for SSO based authentication to IBM Cognos 10 BI, there is no password available to the namespace that can be stored into the trusted credential. Therefore, this feature will only work for basic authentication, when the user provides a user name and password to the login screen. In this case, the system will look at all trusted credentials for that user and update them with the credentials they just entered.

When the property is set to Primary namespace only (the default value) this means that trusted credentials will be updated with a single credential only while the value of All namespaces implies that credentials for all namespaces currently authenticated to will be updated. The Best Practice is to set this to a value of Primary namespace only if authentication to the namespace is not by SSO, otherwise it should be set to a value of Off.


There are some guidelines specific to the type of namespace:

LDAP unique identifier

Once a user has been authenticated to gain access to the IBM Cognos Connection portal, a user account reference known as a CAMID is stored in the Content Store database. This CAMID is partly made up of the value returned from the attribute mapped to the Unique identifier property for the definition of the namespace under the Security > Authentication section in IBM Cognos Configuration. By default, this property is mapped to dn (Distinguished Name). All LDAP servers will have this dn attribute populated for each single entry so this ensures that regardless of the type of LDAP server there's always an attribute on which to base the unique identifier. This practice however does not ensure that user accounts are truly unique. Consider the following scenario,

Company ABC purchased IBM Cognos 10 BI and has successfully rolled out the product to their user base. An LDAP namespace was used to connect to the corporate directory server. The default IBM Cognos 10 BI LDAP namespace configuration is historically based on Sun One Directory Server so their value for the Unique identifier property was set to dn. The Vice President of North American Sales, John Q. Smith, is a frequent user of IBM Cognos 10 BI and has been storing sensitive sales and forecasting reports in his “My Folders” portion of the IBM Cognos Connection portal. Using the corporate naming convention of “last name, first initial”, his network user account is SMITHJ and was created in the North America user folder. This gives John Q. Smith a dn of:

uid=SMITHJ, cn=North America, dc=Company ABC, dc=com

So far, business as usual. However, John Q. Smith decides to take a position with another company, so his user account is removed from the corporate LDAP hierarchy. A few months later an entry level manager, John X. Smith, is hired. Once again, using the naming conventions at Company ABC, John X. Smith receives a network account of SMITHJ, because it is available. This gives John X. Smith a dn of:

uid=SMITHJ, cn=North America, dc=Company ABC, dc=com

When John X. Smith logs into IBM Cognos Connection and goes to save a report to his “My Folders” for the first time, he notices that his folder is filled with reports containing sensitive data. The reason that this happened, is because the unique identifier was based on an attribute that MAY not be unique over time, as demonstrated in the previous example. The only way to ensure that this type of scenario does not occur is to use an attribute for unique identifier which provides globally unique values for every entry read from the LDAP server.

Most LDAP servers provide such an attribute, often as part of the operational attributes. Operational attributes are read only and maintained by the LDAP server only. Some LDAP browsers won't show them by default and require explicit action to read/display them. Consult your LDAP server documentation to learn which attribute is used as a globally unique identifier of an entry. Some examples are ibm-entryuuid used by IBM Tivoli LDAP, objectGUID used by Active Directory when accessed as an LDAP source or nsuniqueid which is used by Sun One Directory server.

The Best Practice for LDAP namespaces is to use this globally unique attribute for the Unique identifier property.

Of course, a solid security infrastructure built within Company ABC would have not allowed for two SMITHJ accounts to have been created (at least not with the same internal unique identifier) but making this simple configuration change will add an extra level of security for your deployment.

NOTE: The attribute mapping must be changed before applying authorization in the IBM Cognos Connection portal and/or allowing users to access IBM Cognos 10 BI. If the attribute mapping is an afterthought and is changed later on, all object security will be nullified and the users will not see their personal content. This is because after a change to this setting, a new CAMID will be created for each user logging in based on the new attribute for unique identifier thus creating, in essence, a new user account in the Content Store. It is also important to note that the attribute used must be an attribute available for all objects such as groups, folders and users. If the selected attribute only exists for users, some objects will not appear in IBM Cognos Connection when administering the namespace.

LDAP connections

The IBM Cognos 10 BI LDAP authentication provider can be configured in many ways regarding connection handling and the credentials used to bind to the LDAP server. At this time many of these methods are still being investigated for how best to implement.

Essentially the provider uses two types of connections, one for look-up searches and one for searches related to user session actions.

The look-up connections will be established using the provided binding credentials and get pooled and therefore reused. The default pool size is 20 and connections are not closed until the product is stopped. To configure the pool size and influence whether connections are dropped for a provider of that type one can specify the minimumLDAPPoolSize and maximumLDAPPoolSize in Advanced properties for the definition of the namespace under the Security > Authentication section in IBM Cognos Configuration. If both properties are set to 0, connections won't get pooled and will be closed immediately after use.

For user session connections, the user credentials provided when logging in are used to bind to the provider unless the Use bind credentials for search property is set to true. This would trigger the use of the values specified in the Bind user DN and password property instead. Those connections would remain connected until the user session ends. If one wants to minimize connection use, one can specify the property unbindLDAPHandleAfterUse in Advanced properties and set it to a value of true. Using these advanced properties together one can achieve minimal open connections to the LDAP server.

The Best Practice for larger user bases (in excess of 50 concurrently logged in users) is to use the unbindLDAPHandleAfterUse property and leave the pool unchanged as 20 connections won't cause noticeable impact on the LDAP server. If your policies demand keeping open connections to a minimum, disable the look-up connection pool.

Microsoft Active Directory

When configuring a Microsoft Active Directory (AD) namespace, it's possible to leverage the Microsoft DNS based locator service which allows finding an available domain controller in fail-over scenarios. This allows the ability to not specify a specific domain controller's name or IP address for the host in the Host and port property of an AD namespace but rather the domain's DNS alias like This will allow the DNS service to return an available domain controller in all situations as and a result, is considered to be a Best Practice that has been adopted by many clients.


IBM Cognos 10 BI leverages Public Key Infrastructure (PKI) concepts to implement encryption and the basis for supporting the Secure Socket Layer (SSL) protocol for encrypted HTTP communication. The specifics are beyond the scope of this document but some settings should be changed from the defaults to implement basic security requirements and adhere to Best Practices.


Each installed instance, referring to an installation of one or multiple installed components to a single directory on a supported platform, has an identity to IBM Cognos 10 BI. So even two installed instances on two separate directories on the same box are considered different entities. This is relevant when cryptography, which is used to encrypt saved, temporary or transient data in IBM Cognos 10 BI, comes into play. The identity, whose concept originates from the X.509 standard, is defined by a Distinguished Name comprised of the fields Server common name, Organization name and Country or region code in the Security > Cryptography > Cognos > Identity name section of IBM Cognos Configuration. These fields should be changed from their default so as to guarantee that each install has a different identity. This is most important when the internal communication for IBM Cognos 10 BI will be switched to SSL but in general it is a Best Practice to define those properties.

Best Practice is to specify a unique Server common name property. The value should be the server's fully qualified Domain Name System (DNS) name. In the case of multiple installed instances on a single host which share a DNS name, adjust the Organization name property in each configuration to distinguish the instances.

CA Service password

One of the central elements of a PKI is the Certifying Authority (CA) which represents the root of trust and issues and signs certificates thus approving the identity of other entities. IBM Cognos 10 BI contains it's own CA service located within the Content Manager component and, by default, will be used to sign the certificates used by IBM Cognos 10 BI. This is meant for installations where the client does not run corporate CA services or the security requirements allow using an application specific CA to be feasible.

When saving configuration on any installed instance for the first time, the CA service will be asked to sign some certificates for that particular installed instance, approving the instance's identity. It is therefore crucial for the integrity and security of the IBM Cognos 10 BI deployment that only trusted instances have access to the CA service. This is why the built-in CA service is protected by a password. This password is specified in IBM Cognos Configuration in the Password property of the Certificate Authority settings section under Security > Cryptography > Cognos.

The Best Practice is to change this password from the default. To do that, specify a new password in the configuration of the Content Manager install component before saving the configuration for the first time. Subsequently adjust the password for all other instances before initial save of configuration on each install.

Keystore Passwords

Certificates are stored in special files called key stores. The files are in a binary format and they are encrypted based on a password required to access them. IBM Cognos 10 BI uses three different key-pairs and correlating certificates on each instance, one for encryption, one for signing and one for the Certifying Authority. Each key-pair and the certificate issued for it are held in a separate key store, which is protected by a password.

Each certificate has it's own settings in a separate section in IBM Cognos Configuration under Security > Cryptography > Cognos. The key store passwords are specified in the <key purpose> password property where <key purpose> is one of Signing key store, Encryption key store or Certificate Authority key store.

It is considered a Best Practice to change the key store passwords from their defaults before first saving configuration for the instance.

Cognos Application Firewall

The Cognos Application Firewall (CAF) is a tool designed to supplement the existing IBM Cognos 10 BI security infrastructure. This application firewall acts as a smart proxy for the IBM Cognos 10 BI Dispatcher and ensures that incoming HTTP and XML requests sent to it are safe to be handled and that outgoing responses to external clients or services are properly encoded and safe.

Safe in this context refers to parameter data, HTTP POST data and malicious requests being sent to the product aiming to compromise the system's security. The most common forms of malicious data are buffer overflows, cross-site scripting attacks (XSS links), either through script injection in valid pages, redirection to other web sites or SQL injections, and session identifier or cookie based attacks. The Cognos Application Firewall will reliably secure IBM Cognos 10 BI against those and ensure only validated parameters and data in general is processed.

The Cognos Application Firewall is controlled by settings made in IBM Cognos Configuration under Security > IBM Cognos Application Firewall. The Enable CAF validation? property must be set to True for CAF to be enabled.

Due to it's critical contribution to overall system security and stability, the Best Practice is to never disable CAF in a production environment.

Valid Domains or Hosts

The most important property of CAF configuration is the list of valid domains or hosts to allow re-direction to or to allow pulling data from. This refers to functionality such as displaying a feed on a dashboard from an external URL, including pictures from external servers, integrating IBM Cognos TM1 Contributor or redirecting to a Lotus Connection host to create an Activity.

Each of the scenarios mentioned above requires an entry to be added to the list of valid domains or hosts for the CAF. The CAF will compare the URL used to access an external (to IBM Cognos 10 BI) resource with the list of valid domains or hosts and only if a match is found, the request will be sent to the external resource. This list of explicitly allowed host names or domain suffixes to which access is allowed is often referred to as a white-list. Any URL that is not on the white-list would be blocked by CAF. One can specify a host name in NetBIOS notation (e.g. “MyServer”) or specify domain suffixes using wild cards (e.g. * to allow all hosts from a specific domain.

The comma separated list is specified in IBM Cognos Configuration under the Security > IBM Cognos Application Firewall > Valid domains or hosts property.

The Best Practice is to explicitly name the hosts if possible and use more general domain suffix specifiers in trusted networks only.

IBM Cognos Connection

In IBM Cognos 10 BI the IBM Cognos Connection portal is where almost all security related settings regarding authorization must be specified and managed. This starts with defining which external security objects such as users, groups and roles that are brought in from an external authentication source will be assigned to secured features and functions as well as defining object security for application content such as packages, reports and dashboards.

The IBM Cognos 10 Information Center has a considerable amount of information about details and specifics in this area, which is why we will refer to there for the basics and only describe additional recommendations which add value over what's already documented.

Authorization Concepts and Best Practice

The first step in understanding authorization for IBM Cognos 10 BI is to understand the objects involved. In simple words, authorization works by defining permissions for securable objects and functions organized in a hierarchy kept in Content Store. This hierarchy of objects is initialized upon the first start of IBM Cognos 10 BI when the Content Store tables are created and pre-populated with the default objects and permissions to them. Among those objects is the Cognos namespace to which predefined roles and built-in objects such as the Everyone group and the Anonymous user are added.

Refer to the following IBM Cognos 10 Information Center links below for more information on the initial built-in objects and predefined roles.

The default permissions, like any other set of permissions, define what type of access users, groups or roles from any namespace, including the Cognos namespace, has to the secured object or function. Upon initialization, there are no assignments for external security objects to any permissions in the Cognos namespace. The authorization is defined based only on objects from the Cognos namespace. This is actually a good starting point for implementing the Best Practice about authorization since this the most flexible and manageable approach to use and therefore the Best Practice to strive for.

The initial access permissions can be found at the following IBM Cognos 10 Information Center links,

To elaborate, one defines authorization by assigning users, groups and roles to permissions which in turn are defined for a securable object such as a report, a schedule, a secured function or a capability. Since users can only originate from external namespaces, the Cognos namespace doesn't support users (with the exception of the built-in Anonymous user), an administrator would have to assign users to the securable Cognos objects explicitly or implicitly. Implicitly refers to assigning groups or roles the user is a member of.

If in a permission a user is referenced explicitly, this permission is dependant on the namespace the user originates from. If the namespace becomes unavailable or the user's unique identifier changes, this reference will be broken. This is one of the reasons why the unique identifier of a user should be based on some globally unique attribute from the authentication source and not on structurally dependant information. For LDAP servers, the DN is actually a path to the entry. If the user is moved around in the LDAP object hierarchy, that path changes and if the user was identified in Cognos by the DN (which is the default), the user's unique identifier to Cognos would be changed and permissions will be broken. By following the Best Practice for unique identifiers that mentioned above, in particular for LDAP namespaces, you will be shielded from this. Active Directory is safe since the objectGUID is not dependant on structural information. The scenario applies to implicit references as well, since the same statement holds true for external group or role references, they are identified by their unique identifier to IBM Cognos 10 BI.

Another challenge is that it is possible that the underlying authentication source might need to change. Where today an LDAP might be used for the test environment, in production an Active Directory instance may be used. This means that in this case objects from the external namespaces have been assigned to permissions and functions directly, and the references to the those namespaces will be broken as well because a different namespace will assign different unique identifiers to the objects.

To alleviate these challenges there is a simple Best Practice for authorization - All references in permissions, capabilities and secured functions should only be made to groups and roles from the Cognos namespace. This means only groups and roles created in the Cognos namespace should be used to define permissions. For example, to allow a certain set of users to use an IBM Cognos 10 Studio, one would either use one of the predefined roles from the Cognos namespace or create a new role explicitly for this purpose and assign this role to the corresponding capability. While this might appear cumbersome to create multiple new groups or roles in the Cognos namespace it actually adds great value. The reasons for this are,

  • All references to objects used in permissions will remain intact even if the members of the role/group referred to will change.
  • The contents of the Cognos namespace can be migrated via deployments to other IBM Cognos 10 Systems.
  • The creation or assignment of external objects to Cognos namespace entries can be automated through the IBM Cognos 10 SDK.

Consider a simple example,

A project is developed in a test environment using a simple LDAP provider with some test users. The project team sets up authorization so that several project-specific group and role objects get added to the Cognos namespace, ignoring or deleting the default Cognos namespace entries. In the next step they assign users and groups from the LDAP provider to the new project-specific Cognos namespace objects entries and subsequently define permissions for studio capabilities, package access and even IBM Cognos Framework Manager security filters (filters which are built into the model for querying the data), based on the new Cognos namespace objects.

When the development has been completed in the test environment, the IBM Cognos 10 application consisting of packages, reports, etc., is deployed to the pre-production environment which uses Active Directory with many thousands of users. This implies that different users will need to be added and existing references to external namespace objects will be broken.

However, since the project followed the Best Practice by having all references in permissions, capabilities and secured functions made only to groups and roles from the Cognos namespace, they can export the IBM Cognos 10 application into a deployment that includes the Cognos namespace. This will preserve all permissions and in the target environment the only thing left to do is adjust the assignments of users and groups from the Active Directory to the roles and groups defined in the Cognos namespace. All the rest remain intact with no need to re-define or adjust a single permission. This is a great time-saver and keeps the project flexible. In addition, if they define groups in their Active Directory to hold the users and only assign those AD groups to the Cognos namespace groups and roles, they can even manage part of the authorization in AD rather than in Cognos. For some clients this is important since identity management integration or access management processes might be in place already.

Users, Groups and Roles

User Maintenance

IBM Cognos 10 BI stores its user profiles, and their associated content, in the Content Store database. In an environment where there are many users, this could potentially consume quite a bit of space. Users being removed from authentication sources, is an everyday occurrence at most companies, so why keep outdated user profiles and content in the Content Store?

The following Best Practice assumes that the user's profile is deleted in IBM Cognos 10 BI prior to removing the user account from the authentication source.

  • Login to IBM Cognos Connection with a userid that is a member of the Directory Administrator role.
  • Click Launch > IBM Cognos Administration.
  • In IBM Cognos Administration select the Security tab.
  • Click on the namespace containing the user account to be deleted.
  • Locate the user whose profile needs to be deleted. Use the Search feature if the namespace hierarchy is deep and/or the location of the user account is unknown. The search icon is a magnifying glass and is in the upper right.
  • In the Actions column, click the More... link.
  • Click on the Delete this user's profile link to delete the profile.
  • Click OK to confirm the deletion of the user profile.

In most environments, the ability to pro-actively delete a user account may not be a reality. Fortunately, IBM Cognos 10 BI provides a mechanism to synchronize the set of profiles held in Content Store with the underlying external namespaces regarding user accounts.

  • As a user with administrative access to IBM Cognos 10, log in to all namespaces which shall be verified/checked.
  • From IBM Cognos Connection, select Launch > IBM Cognos Administration.
  • Select the Configuration tab and click on Content Administration in the left menu.
  • Click on the down arrow on the New Content Maintenance button and select the New Consistency Check link.
  • Enter a name and optional description and/or screen tip then click Next.
  • Select the external namespace(s) to be verified by the consistency check and click Next. The user must be authenticated to all selected namespaces, for the task to work effectively. Missing authentication to a namespace at this point will exclude the namespace from the task.
  • Choose Save and run once to execute the task only one time, Save and schedule to schedule the execution of the task for later and possibly in reoccurring intervals or Save only to not run the task and click Finish.
  • If chosen to run once, specify a time to execute the maintenance task and then choose to either Find only or Find and fix any inconsistencies for the selected namespaces. As mentioned earlier, this requires that the user running the task right now is authenticated to all the selected namespaces. Click Run to start the task, then in the upcoming dialogue don't forget to check the View the details of the content maintenance task after closing the dialog option. This will forward to a page which can be refreshed by clicking Refresh in the upper right until the status changes to succeeded or failed. Any messages regarding specific users will be displayed in the list on this page.
  • If chosen to schedule the task, a new schedule will be saved along with trusted credentials based on the current authentication. The trusted credentials will include all of the namespaces currently authenticated to. Specify the interval and time of execution and select either Find only or Find and fix as the mode to use.

The task will run a consistency check to verify that the user profiles stored in Content Store database are in sync with the users in the external namespace(s). If any users cannot be located in the external authentication source and they have an existing profile in Content Store, a message will be logged stating that the account no longer exists in the external authentication source. If the Find and Fix mode has been selected, the user profile will be deleted from the Content Store.

It is considered a Best Practice to schedule a Content Store maintenance task performing this action at least one a month to avoid wasting space in the Content Store.

More information on this topic can be found in the IBM Cognos 10 BI Administration and Security Guide located in the IBM Cognos 10 Information Center at,

Role/Group Naming

To help organize roles in the Cognos namespace, which can become very abundant in a large deployment, it is recommended to create folders to allow for a logical separation of the roles. These folder names then assume part of the search path of the role. The search path refers to the path describing the location of the object in the Content Store object hierarchy. For example, two folders could be created and within each of these folders, a role could be created and the name of the role can be the same. To illustrate, two folders were created within the Cognos namespace, one called Roles East and the other Roles West. In each folder, a role called Data Administrators was created.

Directory > Cognos > Roles East > Data Administrators
Directory > Cognos > Roles West > Data Administrators

Two roles with the same name were permitted because the name of the parent folder becomes part of the search path for each object. At the same time, for objects in the Cognos namespace the internal ID of those objects, referred to as the CAMID, contains part of the search path as well.

CAMID(":Roles East:Data Administrators")
CAMID(":Roles West:Data Administrators")

Although this type of naming convention works and is supported within IBM Cognos 10 BI, it is not a recommended approach. This technique can easily lead to mistakes when defining permissions or object security as the objects appear to be the same when displayed in the list of members. If the person applying security was not aware of the two distinct groups, incorrect access could be granted or denied to an object. The following illustration shows an example of this, since there is no additional context provided by IBM Cognos Connection to properly identify, at a glance, which role object belongs to which folder.

Illustration 1: A member list of a role in IBM Cognos Connection showing two members with the same name which are not distinguishable at first glance
Illustration 1: A member list of a role in IBM Cognos Connection showing two members with the same name which are not distinguishable at first glance
Illustration 1: A member list of a role in IBM Cognos Connection showing two members with the same name which are not distinguishable at first glance

If the deployment absolutely requires roles of the same name to be created, using a tool tip can help identify which role is which. Then by simply hovering the mouse over the ellipsis (…) the tool tip will display the full path to the object as can be seen in the following illustration.

Illustration 2: A member list of a role in IBM Cognos Connection showing again two identically named members but the tooltip provides context by showing the search path
Illustration 2: A member list of a role in IBM Cognos Connection showing again two identically named members but the tooltip provides context by showing the search path
Illustration 2: A member list of a role in IBM Cognos Connection showing again two identically named members but the tooltip provides context by showing the search path

A naming convention should be established to avoid duplicate naming for roles and/or groups. A common practice is to prefix the entries with something like “R_” for role, “G_” for group and add additional prefixes to indicate where they come from if required. For example, “R_HR_Approver” and “R_Marketing_Approver” could be two roles from different search path or even the same path. In the example above the prefix enables to distinguish them.


The IBM Cognos 10 Information Center provides sufficient detail about permissions and their use. It is important to understand the concepts described there to avoid traps.

Deny takes precedence

You can grant access or deny access to entries. Denied access has precedence over granted access. Therefore when you deny specific users, groups or roles access to an entry but you replace other security policies that grant access to the entry, the grant and deny permissions are in conflict and access to the entry is always denied. For example, a user belongs to two groups. One group has access granted to a report and the other group has access denied to the same report. Access to this report is denied for the user.

As a Best Practice, deny access only when it is really required. Typically, it is a better administrative practice to explicitly grant permissions than to deny them.

Breaking inheritance by explicit override only

Access permissions are acquired from parent entries. If access permissions are not defined explicitly, the entry acquires permissions from its parent entry. You can replace/override this functionality and thus break the inheritance of parent permissions by explicitly defining permissions for the child entry.

Objects that exist only as children of other objects always acquire permissions from their parents. Examples of such objects are report specifications and report outputs. These objects can be manipulated using the IBM Cognos 10 SDK but you cannot set permissions for those objects using IBM Cognos Connection.

Deleting predefined groups and roles

When you delete a predefined group or role from the Cognos namespace, access permissions based on it are also deleted. In IBM Cognos 10 you can restore them by creating a new group or role in the Cognos namespace with the exact same name which will lead to the same internal ID (CAMID). For external groups or roles (those read from an external authentication source through the authentication provider) check how your authentication provider deals with such situations. Typically, you cannot recreate access permissions if they are based on IDs but you can if they are based on names. An example for this would be an LDAP namespace using the DN attribute for unique identifier which is only a string. However, as pointed out before, this bears the risk of unwanted access to user profiles as well and is not a Best Practice so the statement about deleting groups and roles should be considered generally applicable. Don't remove groups or roles unless you're absolutely sure you don't need them any longer. All permissions assigned to the group or role will be lost.


In IBM Cognos 10 BI there are many secured functions and features which are controlled by assigning permissions to corresponding capabilities. The following link in the IBM Cognos 10 Information Center contains more information on secured functions and features. It is important to read the descriptions provided and fully understand the impact of allowing access to a feature or capability for your security design. There's probably more to it than simply removing the Everyone group from various roles and capabilities.

After the initialization of the Content Store database default permissions are set which allow for a basic out of the box configuration to start. The initial Content Store objects and permissions are documented in the IBM Cognos 10 information Center at,

However, the initial permissions don't always reflect the optimal setup for your design nor do they implement any licensing model or compliance to such. They are simply an example of a configuration that could be used. To effectively apply a security policy, one must revisit various capabilities and modify the default permissions. Refer to the following link in the IBM Cognos 10 Information Center for more information on specifying security settings,

Capabilities not only exist at general level but at package level as well. Use this feature to control access by the IBM Cognos 10 studios to packages and consequently data sources.

As a Best Practice, start with defining your objects in the Cognos namespace and only then assign Cognos namespace roles/groups to capabilities.

Data Source Credentials

As of IBM Cognos 10 BI, there is a new feature whereby users can manage their own database credentials if granted access to the Manage own data source signons capability. This can remove the onus of maintaining or managing a large number of stored signons from the IBM Cognos 10 administrator and empower users to maintain their own credentials.

As a Best Practice, decide on whether you want to empower your users to do this before implementing data sources. The reason is that if users were allowed to manage their signons and at a later point an administrator defines a static signon, this will overwrite any user saved credentials thus potentially breaking reports and/or schedules. This can be tricky to find and can take a significant effort to remedy. As a result this is a decision best made before starting implementation.

Downloadable resources


Sign in or register to add and subscribe to comments.

Zone=Big data and analytics, Information Management, Security
ArticleTitle=IBM Cognos Proven Practices: Securing the IBM Cognos 10 BI Environment