The Active Directory Story

The Active Directory Story
Product(s): IBM Cognos ReportNet, IBM Cognos 8

BI
Area of Interest: Security
The Active Directory Story 2
Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to
cscogpp@ca.ibm.com .
Cognos Proprietary Information

Contents
1 INTRODUCTION ............................................................................................ 4
1.1 PURPOSE ............................................................................................................4
1.2 APPLICABILITY .....................................................................................................4
1.3 EXCLUSIONS AND EXCEPTIONS ..................................................................................4
2 ACTIVE DIRECTORY ...................................................................................... 5
2.1 ACTIVE DIRECTORY TERMINOLOGY .............................................................................5
2.1.1 Overview ..........................................................................................................5
2.1.2 Domain Relationships.........................................................................................6
2.1.3 Global Catalog...................................................................................................7
3 IBM COGNOS REPORTNET AND IBM COGNOS 8 BI ...................................... 8
3.1 AUTHENTICATION PROCESS ......................................................................................8
3.1.1 Application Start Up ...........................................................................................8
3.1.2 Basic Sign On....................................................................................................8
3.1.3 Domain Failover .............................................................................................. 10
3.2 BIND USER CREDENTIALS ...................................................................................... 10
3.2.1 LDAP Provider ................................................................................................. 10
3.2.2 Active Directory Provider .................................................................................. 11
3.3 SINGLE SIGN ON................................................................................................. 12
3.3.1 Kerberos Prerequisites...................................................................................... 12
3.3.2 Verification of the Prerequisites ......................................................................... 13
3.3.3 Single Sign On Using REMOTE_USER ................................................................. 16
3.4 MULTIPLE DOMAINS ............................................................................................. 16
3.5 MULTIPLE FORESTS ............................................................................................. 16
3.6 CONFIGURING THE ACTIVE DIRECTORY PROVIDER ......................................................... 16
3.6.1 Standard Parameters ....................................................................................... 16
3.6.2 Advanced Properties ........................................................................................ 17
3.7 CONFIGURING THE LDAP PROVIDER ......................................................................... 18
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated), an IBM Company. All rights reserved.
1 Introduction
1.1 Purpose
This document details how IBM Cognos ReportNet and IBM Cognos 8 BI fits
into a multi domain Active Directory environment.
1.2 Applicability
Due to the use of the Active Directory authentication provider, the document
content does not apply to UNIX installations, unless the Content Manager
component is installed on a Windows server. For installations where all
components are located on UNIX servers, the LDAP provider will have to be
used.
1.3 Exclusions and Exceptions

The document does not cover environments with multiple Active Directory
forests. Although most of the information could apply, this is, as of yet, not a
fully tested environment. As with any software application, changes may be
made which introduce new functionality, thus nullifying some, or all, of the
accuracy of the document contents. This document, at the time of creation, is
accurate for all IBM Cognos Reportnet versions up to and including MR3, as
well as builds up to and including IBM Cognos 8 BI MR1.

2 Active Directory
2.1 Active Directory Terminology
2.1.1 Overview
Part of a successful deployment of the IBM Cognos suite into an Active
Directory environment, is the ability to understand the meaning of Microsoft’s
terminology and how each component of Active Directory fits into the
environment as a whole. Part of this document will focus on distinguishing
between domains, domain trees (trees), and forests.
The smallest component in Active Directory that can be reproduced on a

single domain controller (DC) is called a domain. In the diagram below,
myCorp.com represents the first domain, of many to be created, for the
myCorp company. Because this is the first domain to be created in a series of
domains, it also becomes the root of the domain tree.
A domain tree is a series of domains connected together in a hierarchical

fashion all using a contiguous naming scheme. All subsequent domains that
are created after the root myCorp.com domain has been established will all
contain the myCorp.com suffix. The domain tree is called by the name given
to the root of the domain tree. In the example above, the domain tree
example would be referred to as the myCorp.com tree. It is possible for a
domain tree, commonly simplified to just tree, to contain just one domain.
In addition to the domain tree being automatically formed when the

myCorp.com domain was first created, a new forest was also automatically
created. A forest is a number of separate domain trees that all have a
transitive trust, the same trust that domains in a domain tree have. If domain
A trusts domain B, and domain B trusts domain C, transitive trust implies that
domain A trusts domain C. If domain trees do not share any trust, they are
referred to as being in separate forests. A forest exists as a set of cross-
referenced objects and trust relationships known to the member trees. Trees
in a forest form a collection (referred to as a ring by Microsoft) for the
purposes of trust.
2.1.2 Domain Relationships

Now that the domain structure has been reviewed, let’s take a look at the
terminology revolving around the relationships shared by the actual domains,
using the domain hierarchy from the previous section.
Root – The root domain identifies which domain is at the foundation of the
domain tree. Whether the domain tree is made up of multiple domains or is a
stand-alone single domain, there will always be a domain root. In the
myCorp.com domain tree example shown below, the root domain would be
the myCorp.com domain.
Children – A child domain is a sub-domain located immediately under a

domain in the hierarchy. If the myCorp.com was selected, the child domains
of myCorp.com would be the Finance.myCorp.com and Sales.myCorp.com
domains.
Parent – Similar to the child domain, the parent domain is the domain
located immediately above the selected domain in the hierarchy. The parent
domain to Finance.myCorp.com would be myCorp.com.
Descendant – Descendant domains are all of the domains located beneath

the selected domain in the hierarchy irregardless of their location. That
means that the descendants of myCorp.com would be all the domains in the
domain tree, as myCorp.com is the root domain. The Sales.myCorp.com
domain would have both Pre.sales.myCorp.com and Post.sales.myCorp.com
domains as descendants. In this case, these two domains would also be child
domains of Sales.myCorp.com.
Ancestor – The opposite of descendant domains. All domains above the

selected domain right up until to the root domain. If Pre.sales.myCorp.com
was the selected domain, both Sales.myCorp.com (also the parent domain)
and myCorp.com would be ancestor domains.

Sibling – Sibling domains are domains that share a common parent domain.
In The myCorp.com domain tree, Sales.myCorp.com and
Finance.myCorp.com are siblings, as are the Pre.sales.myCorp.com and
Post.sales.myCorp.com domains.
Disjointed – Disjointed domains are domains that are in the same forest but
not hierarchically related.
2.1.3 Global Catalog

Microsoft defines the global catalog (GC) as “a partial replica of every
Windows domain in the directory. The GC lets users and applications find
objects in an Active Directory domain tree given one or more attributes of the
target object. It also contains the schema and configuration of directory
partitions. This means the global catalog holds a replica of every object in the
Active Directory, but with only a small number of their attributes. The
attributes in the global catalog are those most frequently used in search
operations (such as a user’s first and last names, logon names, and so on),
and those required to locate a full replica of the object. The GC allows users
to find objects of interest quickly without knowing what domain holds them
and without requiring a contiguous extended namespace in the enterprise.
The global catalog is built automatically by the Active Directory replication
system.”
Because the global catalog does not contain all of the attributes, configuring
the AD authentication provider to look at the GC may not always be a feasible
solution.
3 IBM Cognos ReportNet and IBM Cognos 8 BI

3.1 Authentication Process
3.1.1 Application Start Up
Once the details have been supplied for the newly created Active Directory
authentication provider, the configuration needs to be saved and the service
to be started. When the IBM Cognos 8 or IBM Cognos ReportNet service
starts for the first time, the application recognizes that there is a new
authentication provider and attempts to connect to it using the parameters
supplied. If the connection is successful, some basic information will be
gathered regarding the Active Directory domain topology, the provider
initializes and becomes available to users logging in.
Depending on whether any advanced properties are used, some additional

information regarding the Active Directory domain topology will be gathered
during the start up process. See section 3.8.2 for more information regarding
the advanced properties that can be used with the Active Directory
authentication provider.
3.1.2 Basic Sign On

The diagram below details the authentication process, at a high level, when
dealing with a single Active Directory namespace using basic signons as the
authentication method. Following the diagram is a more comprehensive look
at what happens during phases of the authentication process that require
additional details.

Phase 2 – The dispatcher looks for the presence of the cam_passport session
variable. Because this is the first request to the dispatcher from the browser
session, the request is sent to CAM.
Phase 3 – Anonymous Access has been set to false in Cognos Configuration

which means that a namespace must be logged into prior to gaining access
to Cognos Connection. External identity mapping is not set by using the
singleSignOn advanced property (section 3.3.7) or Integrated Windows
Authentication is disabled in IIS.
Phase 4 – CAM receives the request and returns a camAuthUserRecoverable

to the dispatcher asking for user input.
Phase 6 – Leveraging the Microsoft API’s, the user name and password is
passed encrypted to the Active Directory domain handling the authentication.
This is true as long as the CAM component is running in the same forest as
the domain to which the user is attempting to logon to.
10
Phase 7 – If a user account in Active Directory matches the credentials being
supplied, a cam_passport session variable is created in the user’s browser
session and access to Cognos Connection is granted.
3.1.3 Domain Failover

When the IBM Cognos 8 and IBM Cognos ReportNet MR3 (or latest MR2
hotsite) service is started, the AD provider will automatically gather some
basic topology information regarding the AD domain. If the domain controller
specified in the configuration goes offline AFTER the IBM Cognos ReportNet
or IBM Cognos 8 service has been started, and an authentication request
comes in, Active Directory will route the request to another domain controller
and the authentication will occur. This is not configurable through Cognos
Configuration as it is the behaviour of Active Directory that dictates this.
3.2 Bind User Credentials

3.2.1 LDAP Provider
Bind user credentials need to be supplied whenever the individual user
accounts do not have sufficient access to bind to the Active Directory domain
to search for their user account. Being able to log into the Windows domain
does not automatically imply that the user has bind privileges to Active
Directory. Tools such as LDAP Browser can be used to test whether the
domain allows anonymous binds, and if it does not, a specific user account
can be tested.
By default, the binding credentials are left blank which indicates that the
application should bind anonymously to Active Directory. To set the binding
credentials, locate and click on the option in the list of available parameters
for the Active Directory authentication provider. Once the parameter is
selected, click on the pencil icon on the far right of the value box.
This will display the ‘Value – Binding credentials’ dialog box in which the user
account that will be used to bind to Active Directory will be entered. It is
important to note that the full DN (Distinguished Name) to the user account
should be supplied, not just the user ID.

When basic signons are being used to access Cognos Connection, and
binding credentials are supplied in Cognos Configuration, the authentication
process will bind to Active Directory using the supplied credentials in order to
locate the account logging in. Once the account is located, the authentication
provider connects to Active Directory using the credentials supplied at login in
order to retrieve the users’ information. This information would include user
name, email address, group membership, etc. If the user Lookup parameter
value is contained within parentheses “()” then the previous behaviour holds
true. If the parameter value is not within parentheses, then the value will be
considered the DN containing the user accounts, so no search will be
performed, and IBM Cognos 8 will attempt to bind as the user.
In the case of Single Sign On, the password of the account attempting the
login is not available to the authentication process. This means that the
binding credentials will be used to bind to Active Directory to locate the user
account, as well as retrieving the users’ details. The authentication works in
this manner because without the password, the application is unable to
connect to Active Directory as the login user account in order to execute the
query to retrieve the account information. This also means that when SSO is
being used, all Active Directory objects where read privileges have been
granted to the user account being used as the binding credentials, will be
displayed on the ‘Tools -> Directory -> Users, Groups, and Roles’
administrative page within Cognos Connection. Special consideration should
be taken when assigning administrative rights to users, when using SSO.
3.2.2 Active Directory Provider

By default, the Active Directory authentication provider uses Kerberos
authentication which means that bind credentials are never used. There does
exist a bind credential dialog box, but the credentials will only play a role in
two distinct situations:
12
1. When using basic authentication (user is prompted for username and
password) and a failure while authenticating occurs, more information
regarding the failure can be obtained in the log files by specifying
valid bind credentials. Upon an unsuccessful login attempt, the error
messages returned from Active Directory may not reveal the true
reason nature of the failure. If valid bind credentials are supplied, the
messages returned to the application may be more detailed because
AD knows that the request comes from a ‘trusted’ source.
2. When identity mapping is being used (section 3.3.5) bind credentials
MUST be supplied. For more information, consult section 3.2.1.
3.3 Single Sign On

Single Sign On (SSO) is usually the preferred authentication method used by
customers. That being said, there are some prerequisites that must be
satisfied before SSO can occur in an Active Directory environment. This is
commonly referred to as the ‘checklist’ and all points must be verified in order
for SSO to occur.
3.3.1 Kerberos Prerequisites
• Active Directory server is running in native mode.
• The user trying to logon does not have the Account is sensitive and
cannot be delegated attribute checked.
• For each server that will participate in the delegation:

o Web Server (IIS)
This computer is part of the Active Directory domain.
Process is running as Local System Account
• This computer has the Trust computer for
delegation attribute checked.
Process is running as a Domain User Account.
• The domain user has the Account is trusted for
o ReportNet Content Manager
This computer is part of the Active Directory domain.
Process is running as Local System Account
• This computer has the Trust computer for
Process is running as a Domain User Account.
• The domain user has the Account is trusted for
• Kerberos authentication MUST be the active WWW-Authenticate

header

• Kerberos will NOT work in an internet zone
3.3.2 Verification of the Prerequisites

This section demonstrates how each of the settings for items on the checklist
can be verified. The first point is to verify that the domain operation mode is
set to native. This can be accomplished via the Active Directory Server Users
and Computers interface. Once opened, right click on the domain name and
select ‘Properties’.
The screen capture shows a

domain that is NOT running in
native mode, but that is running
in domain mode. This would need
to be changed to allow SSO to
function properly.
The next item to verify is that the user logging in to the application does not
have the ‘Account is sensitive and cannot be delegated’ attribute checked.
This can be verified by examining the users properties in the ADS Users and
Computers interface. The required information is located on the ‘Account’ tab.
14
AD 2000: Ensure that the

‘Account is sensitive and cannot
be delegated’ attribute is not
selected. This screen also
displays the ‘Account is trusted
for delegation’ attribute which is
part of the next points to check.
This attribute must be enabled if
the services are being started
with this user account.
AD 2003: Ensure that the user

has been trusted for delegation.
This can be verified by going to
the ‘Delegation’ tab from within
the users’ properties.
For every server that makes up the environment, namely the Content
Manager server(s) and web server(s), the following three settings must be
verified.
• The server must be part of the Active Directory domain.

• If the IIS and/or Cognos service is started as a named domain
account, the ‘Account is trusted for delegation’ attribute must be
enabled. (see previous screen capture)
• If the IIS and/or Cognos service is started as a local system account,
the server must have the ‘Trust computer for delegation’ attribute
checked.

AD 2000: To verify that a

computer has the ‘Trust
computer for delegation’ attribute
set, open the ADS User and
Computers interface. In either
the Computers or Domain
Controllers container, locate the
computer and view the
properties. This attribute must be
enabled.
AD 2003: To verify that a

computer has been trusted for
delegation open ADS User and
Computers interface. In either
the Computers or Domain
Controllers container, locate the
computer and view the
properties. On the ‘Delegation’
tab there will be radio buttons
indicating whether or not
delegation has been set.
The last item on the checklist that needs to be in place is that Kerberos
authentication must be the active WWW-Authenticate header. This is more
difficult to verify but can be determined by enabling the CAM IPF tracing.
Examining the IPF trace will show the value for the AUTH_TYPE variable:
<item>
<name xsi:type="xsd:string">AUTH_TYPE</name>
<value xsi:type="xsd:string">Negotiate</value>
</item>
The ‘Negotiate’ value indicates that Kerberos authentication is being used. If

the value is anything other than Negotiate, then SSO using the out of the box
AD provider will fail.
16
3.3.3 Single Sign On Using REMOTE_USER

If after verifying that all of the settings in the checklist are valid, single sign
on via Kerberos still fails, there is another option that can be employed. It is
very important to note that if this advanced property is used, single
sign on will be possible into Cognos Connection, but single sign on
to Microsoft Analysis Services will fail because Kerberos
authentication is required.
To leverage the REMOTE_USER variable, thus bypassing Kerberos, an

advanced property called singleSignOnOption can be used. The value
required for this setting is IdentityMapping. Once enabled, Kerberos
authentication will be ignored and the value of the REMOTE_USER session
variable set by the web server will be used to initiate the SSO.
3.4 Multiple Domains

As mentioned in section 3.1.4, the Active Directory provider will gather some
basic topology information regarding the Active Directory domain when the
IBM Cognos ReportNet or IBM Cognos 8 service is started. This permits
failover for the authentication process. If full multi domain support is required
(accessing groups from other domains, logging in from other domains, etc)
some additional parameters must be supplied to the authentication provider
(see section 3.6.2).
3.5 Multiple Forests

At this time, authentication across multiple Active Directory forests is
supported, but Single Sign On is not possible.
3.6 Configuring the Active Directory Provider
3.6.1 Standard Parameters

There are very few parameters that are required when configuring an Active
Directory authentication provider. The values that need to be supplied are:
Namespace ID – This is a unique value that will be used to identify the

namespace. This value can NOT be changed after the authentication provider
has been initialized.

Host and Port – Machine name, or IP Address, as well as the port number
of the active directory domain to be used for authentication purposes. For
more details regarding which domain should be specified, section 3.6.2
should be consulted.
Bind Credentials – See section 3.2.
Both the Time out in seconds and Size limit parameters should be left at
the default -1 value which forces the value to be pulled from the underlying
security provider.
3.6.2 Advanced Properties

Since the release of the IBM Cognos ReportNet build 414.30, two advanced
properties have been introduced for the Active Directory authentication
provider, to be used within a multi Active Directory domain environment. The
two properties are chaseReferrals and multiDomainTrees and must have a
value of True to be enabled.
18
chaseReferrals – When this advanced property is enabled, value set to
True, the topology gathering process (as described in section 3.1.1) changes
slightly. The chaseReferrals parameter indicates that there may be
descendants of the domain specified in the ‘Host and Port’ parameter of the
Active Directory authentication provider. When the IBM Cognos ReportNet or
IBM Cognos 8 service is started on the Content Manager server, this setting
will be read and all descendants of the configured domain will be retrieved
and stored in the domain topology. This means that users from the
configured domain and any of the descendant domains will be able to log into
Cognos Connection. The use of this parameter is not dependant on the use of
the multiDomainTrees property. If multiDomainTrees is not enabled, then
only users of a descendant domain would have access to Cognos Connection.
multiDomainTrees – Similar to chaseReferrals, enabling the

multiDomainTrees property affects the topology gathering process at start
up. This parameter indicates that there are multiple domains in the forest and
will add ancestor, descendant and disjointed domains to the domain
topology. When this property is enabled, the chaseReferrals property will
automatically be enabled as well.
3.7 Configuring the LDAP Provider
As mentioned in section 1.3, when configuring a UNIX only IBM Cognos 8

solution, the Active Directory authentication provider will not be available. In
these cases, the generic LDAP authentication provider must be used.
NOTE: When using the LDAP provider within a multiple AD domain

environment, it is important to note that multiple domains are not accessible
through a single LDAP provider. One provider would have to be configured
for each domain required for authentication. In IBM Cognos 8, using the
LDAP provider will also eliminate the ability to leverage single sign on to MS
OLAP cube sources and SQL Server data sources.
Because the LDAP authentication provider was designed to communicate with

any LDAP version 3 compliant LDAP source, certain parameters need to be
modified in order to successfully retrieve the necessary information from
Active Directory. The first group of parameters that need to be set are the
ones dealing with the connection information.

Shown above is an example of a connection being made to an Active

Directory source, where Single Sign On is not being used. When using basic
signons, the most common attribute that is mapped to Active Directory is
sAMAccountName. Depending on the environment or project requirements,
other attributes may be used as part of the user lookup string, but when
using basic signons, the piece that must not change is the ${userID} suffix.
This indicates that the value to be passed to Active Directory at login is to be
taken from the userID variable found on the login form.
The unique identifier should be changed to objectGUID, which is the unique

attribute that pertains to all objects in Active Directory. Changing this
mapping is a recommended proven practice and more information can be
found in the Securing Cognos 8 Environment document.
For more information regarding the use of bind credentials and Single Sign
On, please consult sections 3.2 and 3.3 respectively.
20

The Active Directory Story

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

The Active Directory Story

Uploaded by

Copyright:

Available Formats

The Active Directory Story

Product(s): IBM Cognos ReportNet, IBM Cognos 8

Cognos Proprietary Information

1.3 Exclusions and Exceptions

Cognos Proprietary Information

The smallest component in Active Directory that can be reproduced on a

A domain tree is a series of domains connected together in a hierarchical

In addition to the domain tree being automatically formed when the

2.1.2 Domain Relationships

Children – A child domain is a sub-domain located immediately under a

Descendant – Descendant domains are all of the domains located beneath

Ancestor – The opposite of descendant domains. All domains above the

Cognos Proprietary Information

2.1.3 Global Catalog

3 IBM Cognos ReportNet and IBM Cognos 8 BI

Depending on whether any advanced properties are used, some additional

3.1.2 Basic Sign On

Cognos Proprietary Information

Phase 3 – Anonymous Access has been set to false in Cognos Configuration

Phase 4 – CAM receives the request and returns a camAuthUserRecoverable

3.1.3 Domain Failover

3.2 Bind User Credentials

Cognos Proprietary Information

3.2.2 Active Directory Provider

3.3 Single Sign On

3.3.1 Kerberos Prerequisites

• Active Directory server is running in native mode.

• For each server that will participate in the delegation:

• Kerberos authentication MUST be the active WWW-Authenticate

Cognos Proprietary Information

• Kerberos will NOT work in an internet zone

3.3.2 Verification of the Prerequisites

The screen capture shows a

AD 2000: Ensure that the

AD 2003: Ensure that the user

• The server must be part of the Active Directory domain.

Cognos Proprietary Information

AD 2000: To verify that a

AD 2003: To verify that a

The ‘Negotiate’ value indicates that Kerberos authentication is being used. If

3.3.3 Single Sign On Using REMOTE_USER

To leverage the REMOTE_USER variable, thus bypassing Kerberos, an

3.4 Multiple Domains

3.5 Multiple Forests

3.6 Configuring the Active Directory Provider

3.6.1 Standard Parameters

Namespace ID – This is a unique value that will be used to identify the

Cognos Proprietary Information

Bind Credentials – See section 3.2.

3.6.2 Advanced Properties

multiDomainTrees – Similar to chaseReferrals, enabling the

3.7 Configuring the LDAP Provider

As mentioned in section 1.3, when configuring a UNIX only IBM Cognos 8

NOTE: When using the LDAP provider within a multiple AD domain

Because the LDAP authentication provider was designed to communicate with

Cognos Proprietary Information

Shown above is an example of a connection being made to an Active

The unique identifier should be changed to objectGUID, which is the unique

Cognos Proprietary Information

You might also like