Configuring IBM Cognos 8 Components to Use LDAP

You can configure IBM Cognos 8 components to use an LDAP namespace as the authentication provider. You can use an LDAP namespace for users that are stored in an LDAP user directory, Active Directory Server, IBM Directory Server, Novell Directory Server, or Sun Java System Directory Server.

You can also use LDAP authentication with DB2 and Essbase OLAP data sources by specifying the LDAP namespace when you set up the data source connection. For more information, see the Administration and Security Guide.

You also have the option of making custom user properties from the LDAP namespace available to IBM Cognos 8 components.

To bind a user to the LDAP server, the LDAP authentication provider must construct the distinguished name (DN). If the Use external identity property is set to True, it uses the External identity mapping property to try to resolve the user's DN. If it cannot find the environment variable or the DN in the LDAP server, it attempts to use the User lookup property to construct the DN.

If users are stored hierarchically within the directory server, you can configure the User lookup and External identity mapping properties to use search filters. When the LDAP authentication provider performs these searches, it uses the filters you specify for the User lookup and External identity mapping properties. It also binds to the directory server using the value you specify for the Bind user DN and password property or using anonymous if no value is specified.

When an LDAP namespace has been configured to use the External identity mapping property for authentication, the LDAP provider binds to the directory server using the Bind user DN and password or using anonymous if no value is specified. All users who log on to IBM Cognos 8 using external identity mapping see the same users, groups, and folders as the Bind user.

If you do not use external identity mapping, you can specify whether to use bind credentials to search the LDAP directory server by configuring the Use bind credentials for search property. When the property is enabled, searches are performed using the bind user credentials or using anonymous if no value is specified. When the property is disabled, which is the default setting, searches are performed using the credentials of the logged-on user. The benefit of using bind credentials is that instead of changing administrative rights for multiple users, you can change the administrative rights for the bind user only.

Important: If you use a DN syntax, such as uid=${userID}, ou=mycompany.com, for the properties User lookup, External identity mapping, or Bind user DN and password, you must escape all special characters that are used in the DN. If you use a search syntax, such as (uid=${userID}), for the properties User lookup or External identity mapping, you must not escape special characters that are used in the DN.

To use an LDAP namespace and set up single signon, do the following:

Configure IBM Cognos 8 components to use an LDAP namespace

Make custom user properties available to IBM Cognos 8 components, if required

Enable secure communication to the LDAP server, if required

Enable single signon between LDAP and IBM Cognos 8 components, if required

Configure an LDAP Namespace

You can configure IBM Cognos 8 components to use an LDAP namespace when the users are stored in an LDAP user directory. The LDAP user directory may be accessed from within another server environment, such as Active Directory Server or eTrust SiteMinder.

If you are configuring an LDAP namespace for a directory server other than LDAP, see the appropriate section:

For Active Directory Server, see Configure an LDAP Namespace for Active Directory Server.
For IBM Directory Server, see Configure an LDAP Namespace for IBM Directory Server.
For Novell Directory Server, see Configure an LDAP Namespace for Novell Directory Server.
For Sun Java System Directory Server, see Configure an LDAP Namespace for Sun Java System Directory Server

Steps

On every computer where you installed Content Manager, open IBM Cognos Configuration.
In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace.
In the Name box, type a name for your authentication namespace.
In the Type list, click the appropriate namespace and then click OK.
The new authentication provider resource appears in the Explorer window, under the Authentication component.
In the Properties window, for the Namespace ID property, specify a unique identifier for the namespace.
Specify the values for all other required properties to ensure that IBM Cognos 8 components can locate and use your existing authentication provider.
If you want the LDAP authentication provider to bind to the directory server using a specific Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication provider binds as anonymous.
If external identity mapping is enabled, Bind user DN and password are used for all LDAP access. If external identity mapping is not enabled, Bind user DN and password are used only when a search filter is specified for the User lookup property. In that case, when the user DN is established, subsequent requests to the LDAP server are executed under the authentication context of the end user.
If you do not use external identity mapping, use bind credentials for searching the LDAP directory server by doing the following:
If you do not specify a user ID and password, and anonymous access is enabled, the search is done using anonymous.
Check the mapping settings for required objects and attributes.
Depending on the LDAP configuration, you may have to change some default values to ensure successful communication between IBM Cognos 8 components and the LDAP server.
LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings, and Account mappings must be accessible to all authenticated users. In addition, the Name property must not be blank.
From the File menu, click Save.
Test the connection to a new namespace. In the Explorer window, under Authentication, right-click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Configure an LDAP Namespace for Active Directory Server

If you configure a new LDAP namespace for use with an Active Directory Server, you must modify the necessary settings and change the values for all properties of the Active Directory objects.

Steps

On every computer where you installed Content Manager, open IBM Cognos Configuration.
In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace.
In the Name box, type a name for your authentication namespace.
In the Type list, click the appropriate namespace and then click OK.
The new authentication provider resource appears in the Explorer window, under the Authentication component.
In the Properties window, for the NamespaceID property, specify a unique identifier for the namespace.
Tip: Do not use colons (:) in the Namespace ID property.
Specify the values for all other required properties to ensure that IBM Cognos 8 components can locate and use your existing authentication provider.
The following settings are examples:
If you want the LDAP authentication provider to bind to the directory server using a specific Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication provider binds as anonymous.
If you do not use external identity mapping, use bind credentials for searching the LDAP directory server by doing the following:

To configure the LDAP advanced mapping properties for use with the Active Directory Server objects, use the values specified in the following table.

LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings, and Account mappings must be accessible to all authenticated users. In addition, the Name property must not be blank.

Mappings	LDAP property	LDAP value
Folder	Object class	organizationalUnit,organization,container
	Description	description
	Name	ou,o,cn
Group	Object class	group
	Description	description
	Member	member
	Name	cn
Account	Object class	user
	Business phone	telephonenumber
	Content locale	(leave blank)
	Description	description
	Email	mail
	Fax/Phone	facsimiletelephonenumber
	Given name	givenname
	Home phone	homephone
	Mobile phone	mobile
	Name	displayName
	Pager phone	pager
	Password	unicodePwd
	Postal address	postaladdress
	Product locale	(leave blank)
	Surname	sn
	Username	sAMAccountName

These mapping properties represent changes based on a default Active Directory Server installation. If you have modified the schema, you may have to make additional mapping changes.

From the File menu, click Save.
Test the connection to a new namespace. In the Explorer window, under Authentication, right-click the new authentication resource and click Test.

IBM Cognos 8 loads, initializes, and configures the provider libraries for the namespace.

Configure an LDAP Namespace for IBM Directory Server

If you configure a new LDAP namespace for use with an IBM Directory Server, you must modify the necessary settings and change the values for all properties of the IBM Directory objects.

Steps

In each location where you installed Content Manager, open Cognos Configuration.
In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace.
In the Name box, type a name for your authentication namespace.
In the Type list, click LDAP, and then click OK.
The new authentication namespace resource appears in the Explorer window, under the Authentication component.
In the Properties window, for the NamespaceID property, specify a unique identifier for the namespace.
Tip: Do not use colons (:) in the Namespace ID property.
Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and use your existing authentication namespace.
- For User lookup, specify (cn=${userID})
- For Bind user DN and password, specify cn=root
If you want the LDAP authentication provider to bind to the directory server using a specific Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication namespace binds as anonymous.
If you do not use external identity mapping, use bind credentials for searching the LDAP directory server by doing the following:

To configure the LDAP advanced mapping properties for use with IBM Directory Server objects, use the values specified in the following table.

Mappings	LDAP property	LDAP value
Folder	Object class	organizationalunit,organization,container
	Description	description
	Name	ou,o,cn
Group	Object class	groupofnames
	Description	description
	Member	member
	Name	cn
Account	Object class	inetorgperson
	Business phone	telephonenumber
	Content locale	(leave blank)
	Description	description
	Email	mail
	Fax/Phone	facsimiletelephonenumber
	Given name	givenname
	Home phone	homephone
	Mobile phone	mobile
	Name	cn
	Pager phone	pager
	Password	userPassword
	Postal address	postaladdress
	Product locale	(leave blank)
	Surname	sn
	Username	uid

These mapping properties represent changes based on a default IBM Directory Server installation. If you have modified the schema, you may have to make additional mapping changes.

From the File menu, click Save.

Configure an LDAP Namespace for Novell Directory Server

If you configure a new LDAP namespace for use with a Novell Directory Server, you must modify the necessary settings and change the values for all properties of the Novell Directory objects.

Steps

On every computer where you installed Content Manager, open IBM Cognos Configuration.
In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace.
In the Name box, type a name for your authentication namespace.
In the Type list, click LDAP and then click OK.
The new authentication namespace resource appears in the Explorer window, under the Authentication component.
In the Properties window, for the NamespaceID property, specify a unique identifier for the namespace.
Tip: Do not use colons (:) in the Namespace ID property.
Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and use your existing authentication namespace.
- For User lookup, specify (cn=${userID})
- For Bind user DN and password, specify the base DN for an administration user, such as cn=Admin,0=COGNOS
If you want the LDAP authentication provider to bind to the directory server using a specific Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication namespace binds as anonymous.
If you do not use external identity mapping, use bind credentials for searching the LDAP directory server by doing the following:

To configure the LDAP advanced mapping properties for use with Novell Directory Server objects, use the values specified in the following table.

For users to successfully log in to IBM Cognos Connection, they must have permission to read the ou and o attributes.

Mappings	LDAP property	LDAP value
Folder	Object class	organizationalunit,organization,container
	Description	description
	Name	ou,o,cn
Group	Object class	groupofnames
	Description	description
	Member	member
	Name	cn
Account	Object class	inetOrgPerson
	Business phone	telephonenumber
	Content locale	Language
	Description	description
	Email	mail
	Fax/Phone	facsimiletelephonenumber
	Given name	givenname
	Home phone	homephone
	Mobile phone	mobile
	Name	cn
	Pager phone	pager
	Password	(leave blank)
	Postal address	postaladdress
	Product locale	Language
	Surname	sn
	Username	uid

These mapping properties represent changes based on a default Novell Directory Server installation. If you have modified the schema, you may have to make additional mapping changes.

From the File menu, click Save.

Configure an LDAP Namespace for Sun Java System Directory Server

If you configure a new LDAP namespace for use with Sun Java System Directory Server, you must modify the necessary settings and change the values for all properties of the Sun Java System Directory objects.

Steps

On every computer where you installed Content Manager, open IBM Cognos Configuration.
In the Explorer window, under Security, right-click Authentication, and then click New resource, Namespace.
In the Name box, type a name for your authentication namespace.
In the Type list, click LDAP and then click OK.
The new authentication namespace resource appears in the Explorer window, under the Authentication component.
In the Properties window, for the NamespaceID property, specify a unique identifier for the namespace.
Tip: Do not use colons (:) in the Namespace ID property.
Specify the values for all other required properties to ensure that IBM Cognos 8 can locate and use your existing authentication namespace.
The following settings are examples:
If you want the LDAP authentication provider to bind to the directory server using a specific Bind user DN and password when performing searches, then specify these values.
If no values are specified, the LDAP authentication namespace binds as anonymous.
If you do not use external identity mapping, use bind credentials for searching the LDAP directory server by doing the following:

To configure the LDAP advanced mapping properties for use with Sun Java System Directory Server objects, use the values specified in the following table.

Mappings	LDAP property	LDAP value
Folder	Object class	organizationalUnit,organization
	Description	description
	Name	ou,o
Group	Object class	groupofuniquenames
	Description	description
	Member	uniquemember
	Name	cn
Account	Object class	inetorgperson
	Business phone	telephonenumber
	Content locale	preferredlanguage
	Description	description
	Email	mail
	Fax/Phone	facsimiletelephonenumber
	Given name	givenname
	Home phone	homephone
	Mobile phone	mobile
	Name	cn
	Pager phone	pager
	Password	userPassword
	Postal address	postaladdress
	Product locale	preferredlanguage
	Surname	sn
	Username	uid

These mapping properties represent changes based on a default Sun Java System Directory Server installation. If you have modified the schema, you may have to make additional mapping changes.

From the File menu, click Save.

You must also use the NSPR library, which is available from ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.6.7.

Steps

Create a directory for the certificate database.
Create the certificate database by typing
certutil -N -d certificate_directory
where certificate_directory is the directory that you created in step 1.
This command creates a cert8.db file and a key3.db file in the new directory.
Add the certificate authority (CA) certificate or the directory server certificate to the certificate database by typing the appropriate command for the type of certificate:
- For a CA certificate, type
  certutil -A -n certificate_name -d certificate_directory -i CA.cert -t C,C,C
- For a directory server certificate, type
  certutil -A -n certificate_name -d certificate_directory -i server_certificate.cert -t P
where certificate_name is an alias that you assign, such as the CA name or host name; and server_certificate is the prefix of the directory server certificate file.
Copy the certificate database directory to the c8_location/configuration directory on every computer where Content Manager is installed.
Configure the directory server to use LDAPS and restart the directory server.
For more information, see the documentation for the directory server.
In each Content Manager location where you configured the LDAP namespace to use the directory server, start Cognos Configuration.
In the Explorer window, under Security, Authentication, click the LDAP namespace.
In the Properties window, for the Host and port property, change the port to the secure LDAPS port.
For the SSL certificate database property, specify the path to the cert7.db file.
In the Explorer window, right-click the LDAP namespace and click Test.
If the test fails, revise the properties, ensuring that the correct certificate is used.
From the File menu, click Save.
From the Actions menu, click Restart.
Repeat steps 6 to 11 on every other computer where Content Manager is installed.

Enabling Single Signon Between LDAP and IBM Cognos 8 Components

You achieve single signon to IBM Cognos 8 components by configuring the External Identity mapping property.

The External Identity mapping can refer to a CGI environment variable or an HTTP header variable. In the case of an application server gateway or dispatcher entry pointing to IBM Cognos 8 components, the External Identity mapping can refer to the userPrincipalName session variable. The resolved value of the External Identity mapping property at runtime must be a valid user DN.

When an LDAP namespace is configured to use the External Identity mapping property for authentication, the LDAP provider binds to the directory server using the Bind user DN and password or using anonymous if no value is specified. All users who log on to IBM Cognos 8 using external identity mapping see the same users, groups, and folders as the Bind user.

If you want IBM Cognos 8 components to work with applications that use Java or application server security, you can configure the External identity mapping property to obtain the user ID from the Java user principal. Include the token ${environment("USER_PRINCIPAL")} in the value for the property. For more information, see the online help for IBM Cognos Configuration.

You can apply limited expression editing to the External Identity mapping property using the replace operation.

Replace Operation

The replace operation returns a copy of the string with all occurrences of the old substring replaced by the new substring.

The following rules apply:

The character \ escapes the characters in the function parameters. Characters such as \ and " need escaping.
Nested function calls are not supported.
Special characters are not supported.

Syntax

${replace(str , old , new)}

Parameter	Description
str	The string to search.
old	The substring to be replaced by the new substring.
new	The substring that replaces the old substring.

Examples

${replace(${environment("REMOTE_USER")},"NAMERICA\\",)}

${replace(${environment("REMOTE_USER")},"NAMERICA\\","")}

	Configure IBM Cognos 8 components to use an LDAP namespace
	Make custom user properties available to IBM Cognos 8 components, if required
	Enable secure communication to the LDAP server, if required
	Enable single signon between LDAP and IBM Cognos 8 components, if required