IBM Support

How to configure Controller to use Active Directory authentication with Cognos BI

Troubleshooting


Problem

Customer would like their end users to logon to Controller by using their Windows (domain / active directory) username and password.
  • How can they achieve this?
NOTE: This Technote only relates to when using Cognos BI as the authentication mechanism.
  • If using Cognos Analytics, then see separate IBM Technote #302865
  • If using Windows Authentication (direct) then see separate IBM Technote #6209654.

Symptom

Cognos Controller can use the following 3 different types of security logon authentication methods:
1. Native
2. CAM (also known as 'Cognos')
3. Widows (direct) - This is a new feature from Controller 10.4.2 onwards - see separate IBM Technote #6209654.

Cause

Controller has two main systems for providing security:

(1) Native security (default)
This is the default authentication method. The usernames and (encrypted) passwords are entirely stored inside the Controller database itself).

This is the simplest mechanism, and works entirely inside the Controller architecture.
  • It allows Administrative users (including the default user 'ADM') to determine access rights for other users within the Controller product.

(2) CAM authentication (optional)
This is also known as 'Cognos' security. This allows users to log in to Controller via Cognos (CAM) namespace users.

In other words, user's Controller user IDs (e.g. "ADM") are mapped to user IDs inside a Cognos namespace (configured in the Cognos platform via Cognos Configuration / Cognos Connection).
  • All Cognos user IDs (that are to be used with Controller) must be members of the 'Controller Users' built-in role/group (in Cognos Security). All 'administrative' Cognos user IDs must be members of the 'Controller Administrators' built-in role.

Limitation when using more than one Cognos 'namespace:
Currently, the Controller GUI has a limitation where it can only fully configure one namespace.
  • Therefore (where the customer has multiple Active Directory namespaces) customers must use a workaround (see separate TechNote 1371936) which requires a small amount of configuration outside of the Controller GUI. Essentially:
    • One separate administrative user needs to be created/configured (in Controller security) for each of the Active Directory namespaces
    • This user can only administer/configure (map / link) users which belong the namespace they all belong to.
    • Once configured with multiple Active Directory namespaces (each of which has its own Administrative User defined in Controller security per TN 1371936), the administrative users (e.g. ADM, ADM2, ADM3) for each of the namespaces can define links between their Active Directory namespace and Controller user IDs, and grant rights to those users in Controller.
    • Users who then log in to Cognos will be prompted to select a namespace and to provide a userID and password to log on to that namespace (unless SSO is enabled, where this process is automatic). They can select any Cognos namespace, and use the appropriate credentials (in the case of an AD namespace, this would be the same UserID and Password they use to log in to Windows) to log in to Cognos Connection, or to log in to Controller.

Environment

Customer using Cognos BI.

This can be either:
(a) a 'full' Cognos BI instance
or (b) the cut-down 'runtime' Cognos BI engine that is supplied (and installed by default) with the Controller 10.3.0 (and earlier) product.

Resolving The Problem

For almost all circumstances, to configure Controller to use Active Directory authentication, you should choose 'Cognos' as your authentication/security method.

This is achieved in three separate stages:
(a) Configure Controller to run with authenticated access
(b) Add Controller users to the (built-in) Cognos roles "Controller Users" and "Controller Administrators"
(c) Inside the Controller application, map the 'Controller' users to the 'Cognos CAM' users
(d) OPTIONAL - Configure Controller Web (optional separate feature) to use Cognos CAM authentication.

Typically:
  • The customer's I.T. department would perform task (a) and (d)
  • The finance department's ‘superusers’ would perform (b) and (c).

Steps:
The following steps are based on Controller 10.2.
  • For other versions of Controller, the screens may look slightly different. However, the concept/solution is the same for other versions of Controller.
  • TIP: For older versions of Controller, the attached document ("04. Configuring Controller 8.2 to use Active Directory authentication - Proven Practice _document v1.0b_.pdf") may be useful for reference purposes.

The following steps assume that the Controller system is a simple/standard 'all-in-one' deployment, with everything installed on one single application server (using standard/default settings).
  • Naturally the instructions will need to be modified if you have any non-standard settings/architecture.

(a) Configure Controller to run with authenticated access

Typically, the customer's I.T. department would perform this task:
1. Obtain downtime (no users on the system)
2. Logon to the Controller application server as a Windows administrator
3. Launch Cognos Configuration
4. Inside "Security - Authentication - Cognos" modify "Allow anonymous access?" to "False":


5. Inside "Security - Authentication" modify "Restrict access to members of the built-in namespace?" to "True":


6. Right-click "Authentication" and choose "New resource - Namespace":


7. Give it a sensible name, and choose "Active Directory":


8. Fill in the following details:
  • Namespace ID: TIP: Choose a short 'friendly' name
  • Host and port: This should be the name of a domain controller, plus the appropriate TCP port (by default 389)
    • IMPORTANT: Make sure that this domain controller is close to the Controller application server. In other words, make sure that there are fast network connections (between the two servers), and that the domain controller is suitably powerful. This is to ensure that the Cognos authentication is quick.


TIP: In most environments, do NOT modify the section ‘Binding credentials
  • This is because most Windows domains allow anonymous LDAP querying.

If you specify Binding Credentials (i.e. if you fill in this section), then:
  • (in some environments) it can lead to performance problems. This is because it causes Cognos to ‘unbind’ its original user and re-bind as the ‘specified’ user
  • You must ensure that the password (of the user that you choose) does not change/expire

=> Therefore, only fill in the ‘Binding credentials’ section if your “test” (see later) fails. If authentication fails, specify a Windows user ID and password for the Binding credentials property.
  • Use the credentials of a Windows user who has at least ‘search’ and ‘read’ privileges for that server.
  • This should be a domain user who can ‘see’ the folders inside the AD where the Controller users are located.

9. OPTIONAL: Enable "ChaseReferrals" and/or "MultiDomainTrees".
  • IMPORTANT: Do not enable these unless absolutely necessary. This is because they cause the authentication system to search through a larger part of your Active Directory tree/forest. This can lead to performance loss.

If you decide that you must use these options, then you can enable one or both of the following:
  • ChaseReferrals - This will allow users from 'child' domains (i.e. domains below the domain that your namespace is connected to) to logon
  • MultiDomainTrees - Allows users from ALL domains (inside the forest) to logon.
    • For full details, see separate IBM Technote #1366722.

10. Click the "Save" icon (top left corner)
11. Right-click on your new namespace (e.g. 'DEMO') and choose 'test':
    12. Click "Restart" icon

    13. Launch Controller Configuration
    14. Inside 'Server Authentication' change 'Select authentication method' to 'CAM Authentication' then click 'Save':


    15. OPTIONAL: Enable Single Sign On (SSO)
    This means that users will no longer have to manually type in their username/password to Controller.
    • Instead, those credentials will automatically be sent (via IIS Windows authentication) to Controller directly.
    • For full details, see separate Technote #1380099.


    (b) Add Controller users to the (built-in) Cognos roles "Controller Users" and "Controller Administrators"

    Typically, the finance department's ‘superusers’ would perform this task:
    1. Launch Cognos Connection.
    2. If prompted, click 'Administer IBM Cognos content', and open the section 'Security':


    3. Open the namespace 'Cognos'
    4. If this is a brand-new system (which therefore contains the default settings, and has not been locked down in any way) then it is recommended that you now take the time to lock down the 'System Administrators' group:
    • Locate the group "System Administrators":
      • Click 'More...'
      • Click 'Set Members'
      • Add the relevant administrative Windows AD users/groups (for example the I.T. department's administrative account(s))
      • Remove the group 'Everyone':


      5. Now locate the Cognos Controller user groups:
      • Locate the group "Controller Administrators"
      • Click 'More...'
      • Click 'Set Members'
      • Add the relevant Windows AD users. These will be the finance department's super-user Windows user accounts (for example perhaps 5 people in the Finance department's HQ division)
      • Locate the group "Controller Users"
      • Click 'More...'
      • Click 'Set Members'
      • Add the group 'Controller Administrators' (located in the namespace 'Cognos')
      • Add the relevant Windows AD users. These will be all the finance department's Windows user accounts (everyone who will be using the Controller system)
      • Remove the group 'Everyone':

       
      6. To avoid future problems (see separate IBM Technote #374925 for full details), add the role "Controller Users" so that they the following required permissions for the Cognos Viewer capabilities:
      • Read
      • Execute
      • Traverse
      In other words, click on this:
      image 3040
      ...to add these permissions:
      image 3041

       
      (c) Inside the Controller application, map the 'Controller' users to the 'Cognos CAM' users

      Typically, the finance department's ‘superusers’ would perform this task:
      1. Launch Controller and logon
      • IMPORTANT: The first person to logon to the Controller database (after performing the above process) must be a member of the 'Controller Administrators' Cognos security group

      2. Click "Maintain - Rights - Users...":


      3. Highlight each user that exists (e.g. 'Fred'):

      4. Inside 'CAM User' click the browse button (..), and choose the CAM User which corresponds to that user

      5. Repeat for each and every one of your users (so that every Controller user has a corresponding CAM user).

      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
      TIP: For more information on topics related to the above, click on links to separate Technotes below.
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

      (d) *OPTIONAL* - Configure Controller Web (optional separate feature) to use Cognos CAM authentication.

      If you have chosen to use the optional 'Controller Web' feature, then you must also configure Controller Web to use Cognos CAM authentication.
      • For more details, see separate IBM Technote #2014043.

      04. Configuring Controller 8.2 to use Active Directory authentication - Proven Practice _document v1.0b_.pdf

      [{"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Controller","Platform":[{"code":"PF033","label":"Windows"}],"Version":"10.3;10.2.1;10.2.0","Edition":"Not Applicable","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

      Document Information

      Modified date:
      18 May 2020

      UID

      swg21380097