Configuring IBM Cognos 8 authentication against Microsoft ADAM

Transcription

1 Proven Practice Configuring IBM Cognos 8 authentication against Microsoft ADAM Product(s): IBM Cognos ReportNet, IBM Cognos8 Area of Interest: Security

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 This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to cscogpp@ca.ibm.com.

3 Contents 1 INTRODUCTION PURPOSE APPLICABILITY CAVEATS MICROSOFT ADAM INSTALLING ADAM CONFIGURING ADAM Create a bind user Assign permissions to bind user Enable read for all users of a partition Enabling Anonymous Binds Configuring SSL CONFIGURING IBM COGNOS 8 BI IMPLICATIONS OF USING AN LDAP AUTHENTICATION PROVIDER ATTRIBUTE MAPPINGS...30 PROPOSED CONFIGURATION ENABLING LDAPS OBTAIN NSS TOOLKIT CREATE THE CERTIFICATE DATABASE ADJUST COGNOS CONFIGURATION...36 APPENDIX A: TROUBLESHOOTING APPENDIX B: REFERENCES APPENDIX C: CONFIGURATION QUICK-SHEET... 41

4 1 Introduction 1.1 Purpose This document provides a walkthrough of configuring Microsoft Active Directory Application Mode (ADAM) in a Windows environment to be used for authentication in IBM Cognos 8 BI or IBM Cognos ReportNet. 1.2 Applicability ADAM is considered yet another LDAP server compatible to LDAP v3 protocol and hence is access through LDAP only. The LDAP authentication provider is available ever since the first version of IBM Cognos ReportNet and supported on all platforms. 1.3 Caveats The document covers installing and configuring ADAM SP1 in a Windows environment. As documented by Microsoft here This requires either Windows Server 2003 or Windows XP Professional SP1. In addition, on computers running Windows XP Professional that need to establish SSL connections to an ADAM instance, you must install the hotfix described in article in the Microsoft Knowledge Base Web site. However this fix is included in Windows XP SP2 and Windows Server 2003.

5 2 Microsoft ADAM 2.1 Installing ADAM First obtain the install media here: The MUI packs contain multiple languages for the installation, if you just want English choose the smaller download. Once downloaded, double click the adamsp1_???.exe executable to start the first part of the install process. This first part will run without any prompting, except you have to accept the License Agreement. Just after the install files have been prepared in this way, you will find a new Program group called ADAM in your start menu. To continue with the install one needs to create at least one instance of ADAM. So click on the Create an ADAM instance entry. The first dialog can be skipped through by pressing next. Then on the Setup Options dialog, ensure that A unique instance is selected. Press Next.

6 When prompted for an Instance Name select a name that will be easily identified. ADAM_Cognos8 was used to ensure that the ADAM instance can easily be identified as the directory server instance for the IBM Cognos application(s). Proceed by clicking Next. The next dialog will prompt for the ports to use for LDAP and LDAPs respectively. As a best practice, don t use the standard LDAP port of 389, or LDAPS port of 636, due to possible conflicts with currently running directory servers, or any future directory server installations. For this document, ports 3890 and 6360 were used.

7 The next step of the installation process is to create a partition that will store the actual data of this instance. Select the Yes, create an application directory partition radio button. For Partition name enter a DN (a Distinguished Name as defied by X509) to save the data to. Typically this DN consists of a BaseDN, something like DC=domain,DC=com, and a prefixed Organization (O) or Organizational Unit (OU) entry which will identify the data which is contained. For the course of this doc we use OU=Users,DC=Cognos,DC=com.

8 In the next dialog specify the install location for the instance and a 2 nd separate directory for recovery files. Continue by pressing Next. The next step requires selecting which account will start the ADAM service. This could either be the Network Service system account or a named domain account. The decision about which to use depends on several factors, like domain topology deployed in and security considerations. The most important factor however is the intended use of LDAPS. If the ADAM instance shall offer connections through LDAPS enter a user account which has local administrator capability on the machine hosting ADAM. Mind, that the user running the ADAM service can be changed through some command line tool only once installation is complete. Changing the user in the Services Control Panel will damage the installed instance. For the course of this section Networks Service account, a system account with minimal rights, is used.

9 In the next step, the installer asks for an account or group of accounts which shall be granted administrative access to this ADAM instance. ADAM can authenticate Windows Principals (local or domain users) and ADAM principals (users only created in ADAM). For ADAM administration though, only Windows Principals can be added to the respective group stored in the ADAM configuration schema. There is a fix available from Microsoft to enable ADAM users to become Administrators, for details refer to Appendix B ( How ADAM works ). In this example the group of local Administrators from the hosting machine was chosen.

10 The last stage in installing the ADAM application is to indicate which LDIF files will be imported and included in the starting schema for the ADAM instance. This is required to be able to create ADAM principals at all. Without those schema extensions ADAM would be able to store or proxy Windows principals only. The only two that need to be selected are the MS-InetOrgPerson.LDF and MS-User.LDF LDF files. Add them by selecting them and click Add.

11 As this is the last step, press the Next button and after the install process has finished press Finish to end the installation. The installation of the instance is completed and a new service with the specified name is visible in the Service Control Panel to start and stop the instance. 2.2 Configuring ADAM After the successful installation of ADAM the instance will be started through the windows service. However, several changes to the default configuration are required in order for ADAM to be usable via LDAP. ADAM comes with an ADSI based administration tool, an MMC plug-in called ADAM ADSI Edit. As this tool connects through ADSI (some Microsoft Windows API for Directory Services) it can leverage Windows specific authentication protocols. When attaching to ADAM through LDAP however, no Windows accounts can be used. As Best Practice for attaching through LDAP some dedicated user credentials, the Binding Credentials (BC) are required. As no users exist so far, at least one new user needs to be created and granted sufficient permission to bind and browse all required objects Create a bind user Open up the ADAM administration tool, it can be found at Start -> All Programs -> ADAM -> ADAM ADSI Edit. With the ADAM ADSI Edit interface open, right-click on the root and select Connect to This presents the Connection Settings dialog box, in which the distinguished name will have to be entered to connect to. Use the Partition name that was entered when the new instance was created in step 2.1. Supply the machine name and port number that used to run ADAM. Connect with a user account which has been assigned administrative access during installation either directly or indirectly through group membership.

12 Right click your Cognos application DN node, select New and click Object In the Create Object dialog box select the user object class. Press the Next button and then supply a value for the new user object. In this example binduser was the value that was used.

13 Do not specify additional attributes but just click Finish.

14 Once the new user object has been created, the password will need to be reset. Right-click this new user and select Reset Password. In the dialog set your new password, confirm the password, and then press the OK button.

15 Right-click this new user and select Properties, select msds- UserAccountDisabled from attribute list and press the Edit button. In Boolean Attribute Editor dialog box, if value is set to True set it to False, press the OK button. Press the OK button again to close the user properties Assign permissions to bind user The bind user needs to be assigned proper permission to browse the tree and read entries. In ADAM every schema is protected by a default set of ACLs. For ADAM those need to be managed through another command line tool which comes with ADAM, there is no GUI based way of editing those. Those ACLs out of the box define access permissions for some groups to the schema entries. There are three default groups which exist for every ADAM schema: Administrators, Readers and Users. Members of Administrators have full access to the entries including write access. By default all ADAM administrators are members of this group. Like mentioned before, this implies Windows users only. Members of Readers have read access to the entries only. There are no default members set for this group. Last, Users is a computed group which contains all the users from the instance. By default the ADAM schema is set up such that all entries can be access by members of the Administrators and Readers groups only. When we created the bind user it was not added to any of those groups and hence he would be unable to read any entry. To remedy we need to add him to the Readers group. As a result any other ADAM users stored in the instance will NOT have read access.

16 Unfortunately there s no intuitive way of doing this. To add users to a group the member attribute of the group entry needs to be edited with ADSI Edit. Start ADSI Edit and connect to the partition using administrative credentials Under your Cognos application partition expand the top node to display the default entries. Select the CN=Roles entry, and doubleclick the CN=Readers entry. In CN=Readers Properties page select its member attribute and click Edit In the Multi-valued Distinguished Name With Security Principal Editor click Add ADAM Account. In Add ADAM Account specify the new user s Distinguish name (DN) (here cn=binduser,ou=users,dc=cognos,dc=com) and click OK. You can find the value of distinguishedname attribute from Properties of the newly added user as well. Click OK to close Multi-valued Distinguished Name With Security Principal Editor and click OK again to close the Properties dialog. As a result the binduser is now capable to bind and browse the partition.

17 2.2.3 Enable read for all users of a partition If it s not applicable to grant read permission on all the schema in the partition to one dedicated set of credentials, a bind user, then it s possible to assign read access to all users stored in the partition as well without the need to grant the permission individually to each user. Read permission on the schema entries by default is granted to all members of the pre-defined READERS group of the partition. To assign read access to users they need to be added to this group. Instead of adding them individually though, the computed group USERS can be used to achieve this. The USERS group needs to become member of the READERS group and all partition users will implicitly have access to the schema entries. To do this Start ADSI Edit and connect to the partition using administrative credentials Under your application partition expand the top node to display the default entries. Select the CN=Roles entry, and double-click the CN=Readers entry. In CN=Readers Properties page select its member attribute and click Edit In the Multi-valued Distinguished Name With Security Principal Editor click Add ADAM Account. In Add ADAM Account specify the Users group DN which is cn=users,cn=roles,<partitionname> and click OK. You can find the value of distinguishedname attribute from Properties of the Users Role as well and use copy & paste. Click OK to close Multi-valued Distinguished Name With Security Principal Editor and click OK again to close the Properties dialog. As a result every user is now capable to bind and browse the partition Enabling Anonymous Binds If absolutely necessary, ADAM can be configured to allow anonymous binds. To accomplish this, the following steps will need to be executed: 1. Start ADAM ADSI Edit and right click root node, select Connect to. 2. In Connection Settings, create your new configuration partition name in Connection Name, put your ADAM server name and port number, select Well-known naming context and select Configuration, then click OK. 3. Under your configuration partition click the top node, there is the entry CN=Services, click CN=Services to expand this node, click CN=Windows NT to expand to its children, right click CN=Directory Service and select Properties,.

18 4. In CN=Directory Service s Properties page select its attribute dsheuristics and click Edit, in String Attribute Editor input the string as value and click OK Configuring SSL ADAM by default listens on two ports, both had to be specified at installation time. One is used for LDAP and the other one for LDAP over SSL (LDAPS). To enable the LDAPS protocol the machine running ADAM need to have a machine certificate installed. This certificate needs to be signed by some CA which is trusted by the machine, means the CA s certificate is Trusted Root Certifying Authority. So in summary two certificates are required, a machine certificate and the CA certificate of the CA which signed the machine certificate. To obtain a server certificate there are many ways. If the same machine runs Internet Information Services (IIS) there is a Wizard available in the IIS console which helps with this. ADAM and IIS both use the same machine certificate; hence any steps valid to enable SSL for IIS apply to ADAM as well. The certificate can be requested manually using tools like OpenSSL or the.net development environment which incorporates some command line tools for this. The certificate can be requested from Microsoft Certificate Services possibly running on one of the Windows Servers in your network.

19 All three listed alternatives will involve the same basic steps, some of them may be disguised though and happen behind the scenes. However for either approach, the subject of the certificate needs to be the fully qualified server name of the machine running ADAM, so like myserver.domain.com. Hostname only must not be used, IP is discouraged as well. If asked, be sure to specify the purpose of this certificate to include server authentication. One other important point is, that for ease of use it s recommended to run ADAM as an account which has local Administrator permissions on the box hosting ADAM. This stems from a subtle way ADAM reads the keys and certificate stores. It is possible to run with non-administrators but then additional permissions need to be granted. Refer to the links specified in Appendix B for more help. To verify if LDAPS is working, try (work through the list if the browser test fails) Open a Mozilla based browser and enter port> If you get prompted about a certificate, all looks good. You may even save out the certificate for later use. Start LDP from your ADAM program group by selecting ADAM Tools command prompt and type LDP. This will start the little LDAP browser like tool. Connect to the LDAPS port and don t forget to check the SSL checkmark. If this works things look good. Use openssl to verify the SSL handshake by calling openssl s_client connect <host>:<port> CAFile <ca.pem file> This will verify the handshake and report errors like invalid certificates, invalid key purpose etc. If the 2 nd last line reads Verify return code: 0 (ok) all is well. Capture the output and attach to communications if you contact Customer Support Example 1: Use the IIS Wizard Bring up the Internet Information Services Console Expand the explorer tree until it displays Default Website Right-Click Default Website and select properties

20 Select Directory Security tab and in the Secure Communications group click Server Certificate to start the IIS Certificate Wizard. Click Next on the Wizard welcome page Select Create a new certificate on the dialog appearing and click Next Note: Don t start thinking about if Microsoft counts different. Options 4 & 6 will not show up usually.

21 When prompted about whether to send the certifying request immediately or later on the next page select Prepare the request now, but send it later. Press Next.

22 Next the Name and security setting page will come up. Select a name for the certificate. This name will NOT be the certificate s subject but just a descriptive name to identify it in certificate stores. Using the machine name and some short description is a good practise. Next select a bit length for the encryption key, and specify any other option you might need. Press Nex to proceed. On the next dialog enter an organization and an organizational unit and press Nex to proceed. Now the wizard asks for Your site s common name. This is the most important thing, as this will define the certificate s subject. Enter the fully qualified domain name for your machine here (like myserver.domain.com ) and press Next. Depending on the policies of the CA you will send the resulting certificate request to, you may need to specify some values for Country, State and City. If unsure, just specify them, won t do any harm. Press Nex to continue. Finally, specify a file system location to store the request in form of a text file to. Press Next and Next again at the summary page plus Finish on the last page to end the wizard. The certificate signing request (CSR) created by the wizard will have to be send to a Certifying Authority (CA) for signing. The response to the CSR will be a signed certificate which should be saved in Base64 encoded ASCII format. In addition the public CA certificate is required in the same format. Usually this is attached in the response as well or can be obtained from the CA directly. In case of commercial CAs check you browser s certificate store, there s a good chance it s already in there.

23 Once the response has been obtained it needs to be imported by running the same wizard again. Bring up the Internet Information Services Console Expand the explorer tree until it displays Default Website Right-Click Default Website and select properties Select Directory Security tab and in the Secure Communications group click Server Certificate to start the IIS Certificate Wizard Click Next on the Wizard welcome page The wizard is aware of the pending request and hence it offers different options this time. Select process the pending request and press Next. Now specify the file system location the CA response was saved to and press Next. Note: If you can t see the file you re looking for, change the filter in the file dialog. The expected suffix for the file is.cer. Some summary page will display what information is contained in the response file. Press Next to import it. Finally, press Finish to end the wizard. The machine certificate has been imported. In the IIS console the View Certificate button on the Directory Security tab will be enabled now. if clicked it will show the installed certificate. If the certificate is tagged with a yellow warning sign and a message is indicating, that it could not be verified successfully, the CA certificate needs to be imported as well. To do this, open Internet Explorer and go to Tools -> Internet Options

24 change to Conten tab In the Certificates Group click on Certificates Change to the Trusted Root Certification Authorities tab Click Import A wizard is started which will run the import process. Simply follow through and specify the file system location the public CA certificate was saved to. When prompted for where to store the certificate select Trusted Root Certification Authorities. At the end of the import a security warning may pop up which informs about the possible impact of the import. To import the certificate select Yes. The CA certificate will now appear in the list of installed Trusted Root Certification Authorities. Go back to IIS console and click on View Certificate again, the warning tag will be gone now. After a restart of the ADAM service ADAM can now be accessed through LDAPS on the configured port. Techie background info: Through this wizard a new private key is generated and saved in the machine keystore which is C:\Documents and Settings\ All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys. As long as the CA response is not imported, the IIS console and inadvertently ADAM as well will be tied to this key. To override or get rid of the key, run the wizard again and delete the pending CSR. Import of PKCS#12 keys is possible however. You cannot import a certificate for this key without running through the wizard, only importing PKCS#12 certificates works when using MMC as described in Example 2.

25 Example 2: Use OpenSSL (advanced users) When not going through the wizards one has to keep in mind, that importing externally build certificates is only possible using PKCS#12 format. That means certificate AND private key in one file. Windows stores the private keys for the machine in the machine keystore which is C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys a and only corresponding certificates are eligible of course. Hence when creating the private key outside of windows the private key needs to be imported there (not copied from another store on that machine!) individually. This is possible through the use of PKCS#12 certificates. The following describes a working and tested set of commands. The parameters in <> brackets need to be replaced with desired values, <keypass> is some arbitrary password chosen to protect the private key..why not cognos. Create a new key by calling (one line) openssl genrsa -des -out <keyfile> -passout pass:<keypass> Create a new CSR for the server by issuing (one line) openssl req -new -key <keyfile> -passin pass:<keypassword> -md5 -out <csrfile> and specifying the FQDN (fully qualified domain name) of the server when prompted for Common Name. Submit the CSR to your CA and obtain response: signed cert = <certfile> and CA =<cacert>. Note: Make sure that nscerttype=server is set when signing this with OpenSSL. Convert response into PKCS#12 by calling (one line) openssl pkcs12 -export -in <certfile> -inkey <keyfile> -certfile <cacert> -name <certalias> -out <certalias>.p12 -passin pass:<keypass> -passout pass:<keypass> This will result in a file with the extension.p12 to be created. The name is arbitrary and identifies the certificate. This file can now be imported into the Windows machine certificate store.

26 Open a shell (CMD.exe) and type MMC to bring up the Microsoft Management Console. Select File -> Add Snap-In Click Add

27 Browse to Certificates Snap-In and click Add Select Computer account when asked about what this snap-in shall manage

28 Select local computer and press Finish Click Close to close the Add dialog Click OK You now have added the Snap-In to the console which displays the machines certificate store. Expand the tree and right-click Trusted Root Certification Authorities. Select All Tasks -> Import

29 The Certificate Import Wizard will appear and prompt for the certificate to import. Specify the file system location of the CA public certificate and continue to the end of the wizard. Ensure the imported certificate get s stored in the Trusted Root Certification Authorities location. Repeat the import for the signed machine certificate by right-clicking on Personal and select All Tasks -> Import. Again the Certificate Import Wizard will guide through the process. This time specify the file system location of the.p12 file obtained as result of the conversion to PKCS12. When prompted for a password, enter <keypass>. After a restart of the ADAM service ADAM can now be accessed through LDAPS on the configured port. Mind that the same certificate is automatically used for a possibly installed IIS.

30 3 Configuring IBM Cognos 8 BI Configuring authentication against ADAM implies going through an LDAP authentication provider. At the time of writing this document there was no Cognos authentication provider available which will attach to ADAM through ADSI which would be the only technical possible alternative. 3.1 Implications of using an LDAP authentication provider Using an LDAP provider has some implications though. When using an LDAP provider to authenticate there can be two different accounts being involved for binding to the LDAP server, depending on configuration. When single sign-on (SSO) is configured all access to the configured LDAP server is solely using the configured Bind Credentials (BC). However, when authenticating manually (user is prompted to type in name and password) there are two binds happening. The first bind to look up the user in the LDAP is done using the BC. Then the established connection is unbound and a new bind is issued, this time using the typed in credentials. This implies that each user who shall authenticate to ADAM manually requires read access to at least his entry and all the parent entries of it. By default ADAM does not provide this and hence additional permissions need to be granted if manual authentication is required. Anonymous binging would be another solution to this but this is less favourable as it s less secure and hence is suitable for development only. Refer to section and for configuring these changes in ADAM. Another implication of using an LDAP authentication provider is that any LDAP role - if any - is brought in as a group only; this is how the provider is designed. For ADAM however, this is irrelevant, as ADAM does not know the concept of a role at all. For example, what is stored under the <basedn>,cn=roles folder are actually entries of object class group. Members stored in multi-value attribute member, so those are really groups rather than roles. 3.2 Attribute mappings When using an LDAP authentication provider attribute mappings need to be adjusted, as the default mappings in the provider configuration are only suitable for SunONE Directory Servers (formerly Netscape DS). ADAM uses some specific object classes which will require mapping in the LDAP provider configuration for groups, the objectclass=group. There s a Group Of Names as well, objectclass=groupofnames. The name attribute for both is CN, members stored in multi-value attribute member. Both group classes can appear equally in the ADAM structure. The two main structural object classes, which represent folders to contain child entries, are organization and organizationunit. The third structural object class is container which represents a simple container which holds other entries.

31 The CAMID attribute ( Unique Identifier ) should be ObjectGUID or DN. The best practice clearly is ObjectGUID as this will help performance and protects against compromising security. The first is due to the fact that each lookup can directly search for this globally unique ID which is indexed and hence much faster than constructing possibly lengthy DN paths. The latter stems from the fact that if DN is used the user will be identified only by it s DN. If one deletes the user and later recreates a completely different user with the same name security may get compromised as the new user will be able to access all the contents secured only based on the DN. This being said, DN should be used as a fallback or general solution if for whatever reason ObjectGUID is not available. DN is the default setting in the LDAP provider only because it is available on any LDAP V3 compliant server so it allows getting started right away. However it is a sub-optimal choice for most LDAP servers because of the risk described above. NOTE: While preparing this document the author discovered an issue in IBM Cognos ReportNet and IBM Cognos 8 BI which makes it impossible to use any other attribute than DN for unique identifier when attaching to ADAM. This issue is only fixed in Cognos 8.3 release. As a consequence use DN in any release prior to Cognos 8.3. Mind, that changing this attribute is impossible without loss of CAMID assignment (object security), so changing once security has been established will lead to efforts in re-assigning object security based on a new namespace with the new attribute mapping. To avoid this, for all setups using C8 prior 8.3 use DN and stick with it keeping the implications in mind or as a best practice, start off with Cognos8.3 right away. Suitable Account object classes are either objectclass=person or objectclass=user. For Cognos either one works, they differ by defined attributes only of which almost none gets mapped anyway. The attribute mappings for contentlocale and productlocale, as well as the one for password need to be removed. The other mappings can be chose as required; some people define uid as the logon id while CN get s set as a more descriptive name. Both attributes can equally be used for user lookup and/or User Name mapping, another alternative would be UserPrincipalName if aiming for Windows principals or proxy users. The User lookup should be chosen depending on the desired logon identifier whether it be a name, a user id or something else. CN works fine but uid is just fine as well. Depending if single sign-on is required the External identity mapping can be activated, the identity mapping string should be chosen based on the same attribute as User lookup.

32 3.3 Proposed configuration In summary a proposed configuration looks like this: - only changes to default values are specified, < > indicates arbitrary values to be selected - -leave empty- means the mapping should be left empty General Namespace ID Host and Port Base Distinguished Name User lookup Use external identity External identity mapping Bind user DN and password Unique identifier Folder Mappings Object class Name Group Mappings Object class Member Name Account Mappings Account object class Content locale Password Product locale <someid> <host>:<port> <PartitionName> (cn=${userid}) True (cn=${environment( REMOTE_USER )}) <Bind credentials> For Cognos8.3+ use ObjectGUID For all other versions prior Cognos8.3 use DN organizationalunit,organization,con tainer ou,o,cn group,groupofnames member cn,cn person -leave empty- -leave empty- -leave empty-

33 4 Enabling LDAPS Attaching to ADAM through LDAPS (LDAP over SSL) is not different than attaching to any other LDAP server through LDAPS, the same steps apply. IBM Cognos 8 BI implements LDAP access based on LDAP SDKs from Netscape and Mozilla. Those SDKs dictate the possible ways for handling certificates and keys required for SSL. In case of IBM Cognos 8 (same as IBM Cognos Series 7 and IBM Cognos ReportNet) SSL certificates need to be provided stored in a certificate database. The database actually consists of up to three files (cert7.db, key3.db, secmod.db) which should be considered as one entity and to be kept together in one folder. However, the secmod.db file does not contain any information related to keys and hence can be deleted from the folder at will, it s mentioned here for the sake of completeness only. Those files are proprietary Netscape/Mozilla format files which are part of Netscape's NSS toolkit. To refer to the database Cognos Configuration expects the folder which will contain the files. As of IBM Cognos 8 MR1 there's a browse button available that allows selecting a cert7.db file directly instead of the path. IBM Cognos ReportNet only expects the cert7.db file while as of IBM Cognos 8 the key3.db file is mandatory as well. As mentioned, the secmod.db file can be deleted. 4.1 Obtain NSS toolkit To create the files, a command line tool from the NSS toolkit is required called certutil. With this tools certificate databases are managed and created. Each database can contain one or many certificates which need to be imported to it using the certutil tool. Recent versions of certutil (NSS 3.6+) no longer create cert7.db files, but the successor format cert8.db which is incompatible with IBM Cognos products. For this you have to use an older version of this tool, the build However there is an apparent issue with the NSS version as well when dealing with CA certificates (trust is not established if only CA certificate is provided in the database) so that as of now the only eligible version of NSS which delivers expected results is NSS You can download the correct version of certutil here (ftp): ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/nss_3_3_2_rtm/ On non-windows systems the package requires some underlying base libraries (NSPR) as well, download them here ftp://ftp.mozilla.org/pub/mozilla.org/nspr/releases/v4.1.2/ In both locations select the sub-folder representing your operating system (WINNT is suitable for all Windows versions though) and choose the OPT.OBJ folder. Download the ZIP file.

34 To install unzip the downloaded files. Each ZIP will unpack to some folder with the package s name, "NSS-3.3.2" or "NSPR-4.1.2", each containing /bin, /include and /lib subdirectories. The certutil executable is located in the /bin subdirectory. If not on Windows and requiring the separate NSPR libs, copy the contents of NSPR-4.1.2/lib to NSS-3.3.2/lib or add NSPR-4.1.2/lib to the library path for your system before calling certutil. Tip: SunOne LDAP, which comes with the Series7 Supplementary CD for example has this certutil in it's bin directory. So you may can spare the download if you have this installed somewhere. if it doesn't work, download the versions indicated above though. 4.2 Create the certificate database IBM Cognos ReportNet and IBM Cognos 8 can establish trust either based on the server certificate solely or the CA certification path which issued the server certificate. The first approach implies that the same server certificate which was used to enable SSL at the LDAP server is imported to the certificate database using certutil. When going forward with the CA approach, the root CA certificate as well as all intermediate CA certificates which make up the certification path need to be imported into the certificate database using certutil. Best practice is to use the root CA certificate and possibly existing intermediate CA certificates. This makes the certificate database re-usable for other Cognos installs and it renders the database independent of changes applied to the server certificate as they will occur when the certificate expires or the server name changes. To create the certificate database follow these steps a) Acquire the required certificate(s) in unencrypted Base-64 encoded format (PKCS#7). For the course of these instructions it is assumed that the server certificate is saved as server.cer, the root CA certificate was saved as ca.cer and possible intermediate CA certificates were saved as ICAxx.cer (xx=01-..). Tip: You can obtain the server certificate easily by accessing the LDAP with a browser per HTTPS at the LDAPS port (usually 636). Example: Once the browser prompts to accept or inspect the certificate, select to inspect it and save it to a file from there. This works for Internet Explorer and Mozilla/Netscape. When inspecting the certificate the certification path may also show which CA signed the certificate and if this CA certificate was possibly installed in the browser previously, from where it could be exported to t file as well. However, not all LDAP servers allow for this. Another possibility is to use OpenSSL's s_client modus to simulate an SSL client and retrieve the certificate like:

35 openssl s_client -connect host:port showcerts This will print out all the certificates the server presents (server + CA(s)) to the console where you can grab them by copy & paste. b) Create a directory to contain the certificate database, for example /mykeys. All files of the database to create will be saved to this directory. c) Create a new NSS certificate database by issuing: certutil -N -d <cert_directory> Example: certutil -N -d mykeys This will create a cert7.db file and a key3.db file (possibly a secmod.db file as well) in the directory specified in the d parameter. Those constitute the certificate database and hence the directory should be treated as a single entity, always keep these files together. You may want to delete secmod.db as it s not needed for our purposes anyway. d) Add the certificate(s) you want to use to the new certificate database: For a server cert issue: certutil -A -n <cert_name> -d <cert_directory> -i <certificate_file> -t P Example:certutil -A -n MyServer -d mykeys -i server.cer -t P For a CA cert issue: certutil -A -n <cert_name> -d <cert_directory> -i <certificate_file> -t C,C,C Example: certutil -A -n MyCA -d mykeys -i CA.cer -t C,C,C where <cert_name> is an arbitrary name you assign to the certificate in the certificate database as an alias. Using the CA name or hostname is a good practice. <cert_directory> specifies the subdirectory representing the certificate database. <certificate_file> is the file which holds the certificate to import Tip: to verify the import was successful and the trust option is correct, issue

36 certutil -L -d <cert_directory> Example: certutil L d mykeys 4.3 Adjust Cognos Configuration Once the certificate database has been created all that s left to do e) Provide the absolute path to the cert7.db file for the SSL Certificate Database property in Cognos Configuration. This may or may not include the file name cert7.db. Recent versions of Cognos Configuration will allow browsing for the file to ease this. For example you could copy the whole subdirectory you created in b) to <COGNOS_ROOT>/configuration, in order to keep these files together. f) Change the port in the Host and port property to reflect the LDAPS port g) If you're running IBM Cognos 8 BI, you can now right-click and test the LDAP namespace. If the test fails, start troubleshooting by looking up errors in the Knowledge Base and Appendix A:. Note: After testing an LDAPS enabled namespace Cognos Configuration will crash. This is due to a known issue currently addressed by development. Please excuse the inconvenience. h) Restart the Cognos product to initialize the provider with the new configuration.

37 Appendix A: Troubleshooting After entering credentials the following error is shown CAM-AAA-0056 Unable to authenticate CAM-AAA-0026 The function call to 'ldap_simple_bind' failed with error code: '49' C: LdapErr: DSID-0C090336, comment: AcceptSecurityContext error, data 52b, vece -> This is a known issue in versions prior to IBM Cognos 8.3, as of IBM Cognos 8.3 this is fixed. When entering wrong credentials the provider should re-prompt the user and display invalid credentials. For details contact Cognos Customer Support. When testing the provider in Cognos Configuration or when starting the product the following error surfaces CAM-AAA-0134 Unable to retrieve information for the user CAM-AAA-0172 The main identity returned by the provider is invalid. The number of results returned must be equal to one -> Either the specified binding credentials or the user itself does not have sufficient permission to access the user entry in ADAM. Check with dsacls command line tool (part of ADAM install). dsacls \\host:port\entrydn When installing ADAM on XP in a workgroup only local Windows users can connect. -> This is a known configuration issue as by default any non-local user is considered GUEST and hence insufficient permissions are assigned. This only affects WINDOWS users coming in through ADSI, ADAM users can connect remotely through LDAP. The fix is to set the registry key HKLM\SYSTEM\CurrentControlSet\Control\Lsa\forceguest to 0 instead of 1 which is the default. For more information, see Enable binding to ADAM instances running on Windows XP Professional computers joined to a workgroup. For information about other functional considerations when running ADAM on Windows XP Professional, see Running ADAM on Windows XP Professional.

38 Cannot connect to ADAM via LDAPS from any computer running Windows XP through ADSI (ldp for example). -> This is a limitation of ADSI which was removed in a hotfix described in Microsoft Knowledge Base Article in the Microsoft Knowledge Base Web site. This fix is included in Windows XP Sp2 though. The general steps for setting up SSL for ADAM are as follows: Install a certificate from a trusted CA onto the computer running ADAM. The certificate must be marked for server authentication. If you want to use the certificate for applications other than ADAM, you must store this certificate in the local computer certificate store. Otherwise, you can store the certificate in the ADAM service store. When you request the certificate, specify the fully qualified domain name (FDQN) of the computer on which ADAM is running as the identifying name for the certificate. Note: If Internet Information Services (IIS) is running on the same computer as ADAM, you can verify that the certificate is properly installed by attempting an SSL connection to IIS first, before attempting an SSL connection to ADAM. Before you attempt to use the certificate with ADAM, you must ensure that the service account under which ADAM is running has Read access to the certificate that you installed. The certificate is located in the following directory: C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys Note: To determine the appropriate certificate on which to set permissions for the ADAM service account, run certutil -store my from a command prompt. The Key Container value that is shown for each certificate matches the file name of the certificate as it appears in the C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys directory. To test the certificate with ADAM, run Ldp.exe on the computer running ADAM and connect to the local ADAM instance using SSL. For information about LDP, see the ADAM Administrator's Guide. To open the ADAM Administrator's Guide, click Start, point to Programs, point to ADAM, and then click ADAM Help. Note: When you use LDP to make an SSL connection to ADAM, you must specify the FQDN of the computer running ADAM. FQDNs are required, according to the SSL standard. To connect to ADAM from a client over SSL, the client must trust the certificate on the computer running ADAM. This trust can be achieved by adding a certificate from the CA to the Trusted Root Certification Authorities store on the client. Use LDP from a client to make an SSL connection to the ADAM instance. Notes: When you use LDP to make an SSL connection to ADAM, you must specify the fully

39 qualified domain name (FQDN) of the computer running ADAM. FQDNs are required, according to the SSL standard. On a standalone ADAM server, add a primary DNS suffix under the computer name properties. This is done to enable SSL, as it requires a FQDN structure to function and this server is not a domain member. On client computers running Windows XP Professional that need to establish SSL connections to an ADAM instance, you must install the hotfix that is described in article , Active Directory Services Does Not Request Secure Authorization Over an SSL Connection, in the Microsoft Knowledge Base.

40 Appendix B: References Microsoft ADAM documentation a294-9b82781c mspx?mfr=true Help troubleshooting LDAPS for ADAM OpenSSL toolkit Enabling LDAPS for CRN/Cognos8 KB =1&dr=kb1&uniqueid= Certutil documentation Some forum thread providing hints on installing an SSL cert for ADAM Documentation for Microsoft version of certutil which is used for troubleshooting ADAM SSL installation. WARNING: NOT ELIGIBLE FOR GENERATING CERT7.DB FILES!!!

41 Appendix C: Configuration quick-sheet