Configuring LDAP authentication for TM1 9 · Configuring LDAP authentication for TM1 9.5 If now...

Configuring LDAP authentication for TM1 9.5

Nature of Document: Proven Practice

Product(s): TM1 9.5

Area of Interest: Security

Version: 1.1

Business Analytics


Copyright and Trademarks Licensed Materials - Property of IBM.

© Copyright IBM Corp. 2010

IBM, the IBM logo, and Cognos are trademarks or registered trademarks of InternationalBusiness Machines Corp., registered in many jurisdictions worldwide. Other product andservice names might be trademarks of IBM or other companies. A current list of IBMtrademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

While every attempt has been made to ensure that the information in this document isaccurate and complete, some typographical errors or technical inaccuracies may exist. IBMdoes not accept responsibility for any kind of loss resulting from the use of informationcontained in this document. The information contained in this document is subject to changewithout notice.This document is maintained by the Best Practices, Product and Technology team. You cansend comments, suggestions, and additions to [email protected].

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarksor trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, IntelXeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks ofIntel Corporation or its subsidiaries in the United States and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, orboth. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of MicrosoftCorporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. inthe United States, other countries, or both.

Business Analytics

2

http://www.ibm.com/legal/copytrade.shtml

mailto:[email protected]


Table of Contents1 Introduction .................................................................................................................. 4

1.1 Purpose ........................................................................................................................ 4 1.2 Applicability .................................................................................................................. 4 1.3 Exclusions and Exceptions .............................................................................................. 4

2 Background ................................................................................................................... 4

2.1 LDAP authentication in TM1 ........................................................................................... 4 2.2 SSL secured communication in TM1 ................................................................................ 5

3 Configuration Steps ....................................................................................................... 8

3.1 Verifiy LDAP server information ...................................................................................... 8 3.2 Install TM1 9.5, select LDAP authentication .................................................................... 9 3.3 Run ETLDAP tool ......................................................................................................... 10 3.4 Log on to TM1 using LDAP Credentials .......................................................................... 23

4 Troubleshooting ........................................................................................................... 24

4.1 Add debug logger for LDAPAuth .................................................................................... 24 4.2 Verify certificate .......................................................................................................... 24 4.3 Verify tm1s.cfg settings ................................................................................................ 25 4.4 Most frequent error codes in tm1s.log with enabled logger LDAPAuth .............................. 25 4.5 No attributes shown in ETLDAP tool .............................................................................. 26

Business Analytics

3


1 Introduction

1.1 Purpose

This document is meant to supplement the TM1 9.5 Operations Guide as it describes the task ofconfiguring LDAP authentication for TM1 9.5 in greater detail. It adds value though as it coversdocumentation gaps, documents yet undocumented configuration items and helps to overcome pitfallsnot mentioned in documentation at all.

1.2 Applicability

The configurations described in this document apply to all versions of Microsoft Windows and TM1 9.5only. While the concepts may work in earlier versions of TM1 they have not been verified by theauthor.So far the following LDAP servers have been verified to work in conjunction with TM1 9.5: OpenLDAP,Sun ONE LDAP, Novell eDirectory, Tivoli Directory Services, Microsoft Active Directory. While there isno official statement about the support of LDAP servers it's safe to assume that all LDAP V3 compliantLDAP servers will work.

1.3 Exclusions and Exceptions

TM1 9.5 does currently not support LDAP authentication on any other platform than MicrosoftWindows. In particular it's impossible to get this working on UNIX as there is no LDAP client APIavailable in TM1 9.5 on those platforms.The document will refer to concepts of Public Key Infrastructures (PKI) like certificates, CertifyingAuthorities and key- and truststores. The reader is expected to be familiar with those concepts as thedocument won't explain them.

2 Background

2.1 LDAP authentication in TM1

When TM1 is configured to use LDAP authentication it will verify user credentials against theconfigured LDAP server. However IBM Cognos TM1 does not support a stand-alone LDAPconfiguration. As pointed out in the Operations Guide Chapter 7, TM1 will always use a look-up in theTM1 database (it's internal security) too. Technically the steps are

• TM1 users log in through any client and present credentials. • TM1 provides the credentials to the configured LDAP server for verification• If LDAP server accepts credentials TM1 checks whether the provided user name has a matching

entry in the }Clients.dim. If so the user is logged in to TM1.

With that being stated it evolves that before being able to use LDAP authentication users and groupsfrom the LDAP must be imported into the TM1 database. This is handled by the ETLDAP tool.The ETLDAP tool will create user name entries in the }Clients.dim and entries in the }ClientProperties.dim.

Business Analytics

4


2.2 SSL secured communication in TM1

IBM Cognos TM1 makes use of Secure Socket Layer (SSL) encrypted connections for two purposes. First there is the internal communication between the TM1 Server(s) and clients like Architect,Perspectives and the (web-)client. Since version 9.1 TM1 supports encrypting those connections bySSL which is considered best practice. (refer to TM1 Operations Guide, Chapter 1).Second, for LDAP authentication there is communication between the TM1 server(s) and the LDAPserver. The LDAP protocol too can be encrypted by SSL which is denoted as Lightweight DirectoryAccess Protocol over SSL (LDAPS). As of version 9.1 TM1 requires LDAPS, the use of unencryptedLDAP is deprecated and unsupported as of that version. It's important to anticipate thatcommunication to the LDAP is always handled by the TM1 server only, clients don't connect to theLDAP directly.

Business Analytics

Figure 1 - SSL Communication in TM1 9.5

5


The internal SSL communication by default is based on Keys created by TM1 and certificates signedby the Certifying Authority (CA) built into TM1. They get stored to the <TM1 ROOT>/bin/ssl folderby default. At the same time this implies that the server certificates used for the internal SSL aretrusted by all TM1 components. For this trust, a client must trust the CA which signed the servercertificates. For internal SSL that is the “Applix CA” (the name the TM1 built-in CA uses) of course.Since TM1 leverages the Windows Operating System cryptographic functions to verify SSL trust thisimplies importing the “Applix CA” certificate into the Windows LocalComputer truststore as a trustedroot authority. This is done by the installer automatically so after installation the system is completelyconfigured for internal SSL. It is suggested though to replace the default certificates by certificates signed by a commercial CA forproduction use. Doing so requires providing TM1 with a server certificate, the private key, the CAcertificate which signed them and a Certificate Revocation List (CRL) certificate for that CA. Due to thefact that TM1 uses the Windows API for cryptographic functionality that new CA certificate is not yetpresent in the Windows truststore and has to be imported manually (refer TM1 9.5 Operations Guide ,Chapter 12: "Running TM1 in Secure Mode Using SSL", Paragraph: "Using Independent Certificates"). If this isa CA certificate of a commercial CA like Thawte or Verisign there is a good chance these CAs arealready trusted by windows as even Windows comes with some pre-installed CA certificates in it'struststore. To check use the Certificates snap-in for Microsoft Management Console (MMC) and viewthe “Trusted Root Certification Authorities” node like shown below.

Figure 2 - Windows Truststore with Trusted CA certificates

The screenshot shows all trusted root CA certificates in a default Windows 2003 Server plus twoadditional certificate which have been added so far (CS Germany CA and Applix).

Note: There is an undocumented tool “importsslcert.exe” in the <TM1_ROOT>/bin/ssl folder which automates theprocess of importing a certificate into the windows truststore. It's used by TM1 internally but it can do the job for anycertificate and saves the hassle of using the MMC Snap-in.

Only after importing the certificate into the Windows truststore TM1 Server will be able to use theserver certificate to establish the SSL socket.

Business Analytics

6


If now focussing on external SSL the same concept applies. For TM1 Server to trust the servercertificate presented by the LDAP server upon SSL connect the certificate of the CA which signed theLDAP server certificate must be imported into the Windows truststore as well. If the LDAP server is using a self-signed certificate (a certificate where subject and issuer are identicaland which does not have the “is CA” attribute set) it serves as server AND CA certificate at the sametime, so the server certificate has to be imported to the windows truststore. Mind that self-signedcertificates are considered bad practice for production servers and certificates signed by a CA shouldbe used instead. Since the LDAP server is an external 3rd party software the configuration of SSL support is outside ofTM1's scope. A TM1 administrator must obtain some information from the LDAP Administrator.

The ETLDAP utility used to run the initial user import to TM1 is coded in JAVA and hence leveragesother truststores and APIs to establish an SSL connection. Extra steps are required to connectETLDAP by LDAPS. The Operations Guide describes them though there is a small glitch indocumentation which is pointed out in the next section. For sake of understanding the bigger pictureit's sufficient to anticipate that ETLDAP uses the “external SSL” connection.

Business Analytics

7


3 Configuration StepsWhile the Operations Guide of TM1 9.5 covers the most basic concepts and tasks of configuring LDAPauthentication it unfortunately misses out on mentioning some important/interesting configurationoptions. Some other steps which are required may pose a challenge if not implemented correctly.

This section provides a step-by-step walk-through in configuring LDAP authentication for TM1 9.5. Ithas worked several times for different LDAP servers and installs. It is a proven practice.

3.1 Verifiy LDAP server information

The first step before even installing TM1 9.5 is to verify all the required information about the LDAPserver is available and it's possible to connect to it via LDAPS.

1. For a start the first piece of information required is the type of LDAP server. This can be any LDAPV3 compliant LDAP server like Tivoli Directory Service (TDS), OpenLDAP, SunONE LDAP and evenincluding Microsoft Active Directory (AD). Very roughly spoken AD really is “just an LDAP” built intoWindows - heavily extended by Microsoft, so it can be used for LDAP authentication to TM1 9.5.The type of LDAP will determine the attributes of a user entry which potentially could be used forTM1 login names and, in case of Active Directory, how TM1 server authenticates to the LDAPserver. For AD there is a special Single Sign-On feature available, it will be discussed later.

2. Second the connection information of the LDAP is required. This includes • host IP, Netbios name or preferably the fully qualified DNS name.

Tip: In case of AD using the domain name is valid as well and is a best practice as this will allow to leverage the Windows DC Locator feature (AD failover support).

• port , LDAPS by default uses port 636• Base Distinguished Name (BaseDN), something like o=Business Analytics,dc=ibm.com

3. Third, and most important, the information whether the LDAP server uses a self signed certificateor a certificate signed by some CA is required. In case of a self signed certificate the server certificate is required.In case of a CA signed certificate, the CA certificate of the CA which signed the server certificate isrequired.Obtain either certificate in Privacy Enhanced Mail (PEM) format (Base64 encoded ASCII).

4. Last piece of information required are some Binding Credentials (BC), basically an LDAP accountwhich can be used to bind to the directory and search it. This BC need to have browsing and readaccess to at least all the user entries which should be imported into TM1.In case of Active Directory the BC can be some domain user account, note the account.

Business Analytics

8


After obtaining all this information it's a good idea to verify some arbitrary LDAP client can connect tothe LDAP via SSL. Use an LDAP browser of your choice and connect to the LDAP using the host,port ,BaseDN and BC collected. IF the connection works continue, if not try troubleshooting theconnection issue. TM1 won't be able to connect if an LDAP client can't. A good test is to use the “LDP” utility which is part of the Windows Server Tool package fromMicrosoft (included in Win2008 server by default). Another LDAP client with SSL support is ApacheDirectory Studio (Open Source) or Softerra LDAP browser (commercial). It's even possible to test with the OpenSSL toolkit using the “s_client -connect host:port -ca <cert>” command.

3.2 Install TM1 9.5, select LDAP authentication

If not already done, install TM1 9.5 running the install wizard. Make sure to select the LDAPAuthentication check box.

Provide the information gathered about the LDAP in the previous step. The actual value for LDAPsearch field depends on your type of LDAP. It can be changed later if you're unsure. This will createthe required entries in the server's tm1s.cfg file.

If TM1 has been installed already then tm1s.cfg will already have some settings in place for thecurrently configured authentication mode. The settings for LDAP must be added manually in this case.Mind that depending on the current authentication mode additional configuration settings might berequired for ETLDAP so it can connect to the TM1 server.

Business Analytics

Figure 3 - TM1 Installation Wizard - LDAP Authentication option checked

9


3.3 Run ETLDAP tool

As mentioned in section 2.1 to use LDAP authentication for TM1 one of the prerequisite steps is to runthe ETLDAP utility to create users and groups in the TM1 database. ETLDAP connects to the LDAPand TM1 and writes data to the TM1 database which it has extracted from the LDAP. It is coded inJAVA and hence uses a JAVA API to handle cryptographic functions. ETLDAP does not use theWindows truststores like TM1 server but JAVA truststores. Thus an additional step is required toestablish ETLDAP's trust to the LDAP server's certificate. In addition several settings are required to achieve a successful import.

Before starting with ETLDAP ensure that in the tm1s.cfg file for your Server the property for thepassword source is set to TM1 (PasswordSource=TM1) as pointed out in the Operations Guide,Chapter 10, “Configuring LDAP validation”. It cannot be switched to LDAP yet because there are nousers imported into TM1 yet and ETLDAP must be able to connect to TM1 to import the users andgroups.

3.3.1 Make ETLDAP trust the LDAP server's certificate

ETLDAP is invoked via a Microsoft Windows command file which calls a Java Runtime Environment(JRE) and explicitly passes the name and location of a truststore (a file containing certificates whichshould be trusted). By default the truststore being referenced is the one used for internal SSL, it'sbeing passed in two parameters passed to the JRE like this

-Djavax.net.ssl.trustStore="%APPLIXPath%bin\ssl\tm1store"-Djavax.net.ssl.trustStorePassword=applix

The truststore is <TM1_ROOT>/bin/ssl/tm1store and it's password is “applix”. While it's fine to change those parameters in <TM1_ROOT>/bin/etldap.cmd to use a separatetruststore it's easiest to simply add the certificate required for ETLDAP's trust to the truststore forinternal SSL. There are no adverse effects to the internal SSL nor does it raise security concerns,hence this is what is described below. If you absolutely want to use a separate truststore for ETLDAPadjust the batch file and don't forget to import the Applix CA certificate into it as well, without itETLDAP won't be able to connect to TM1.

To establish trust, the CA certificate which signed the LDAP server certificate or the server certificateitself (in case it's self signed) must be imported into the tm1store. To import issue the followingcommand (mind there is a WRONG path in the Operations Guide, the glitch has been reported andwill be fixed in the future) while being in the <TM1_ROOT>\axajre\jre\bin folder:

keytool -import -keystore <TM1_ROOT>\bin\ssl\tm1store" -storepass applix -alias LDAPTrust -file <your_cert>

The tool will print the certificate and ask whether it should be imported. Press “y” and press ENTER .That's it, the certificate has been added and ETLDAP will trust each certificate presented to it whichwas signed using the imported certificate.Trust for the LDAP server's certificate has hence been established now for the ETLDAP tool.

Business Analytics

10


3.3.2 Connect to LDAP

Run the ETLDAP tool by starting <TM1_ROOT>\bin\etldap.cmd.

Figure 4 - The ETLDAP tool

Once the tool opens click Edit -> Login -> LDAP.In the upcoming dialogue provide the LDAP connection information and BC gathered in section 3.1.Click Test. If the connection was established successfully, that is the SSL handshake worked, a message in greenwill indicate so. Press OK to complete the login.

Business Analytics

Figure 5 - LDAP Login Dialogue - SSL option checked

11


If the connection cannot be established refer to the Troubleshooting section for hints. Basically ensure• the certificate is correct• the correct certificate has been imported into the truststore provided to ETLDAP in the

command file• the Binding Credentials are valid , test them using some other LDAP client software• the LDAP server is up and running.

3.3.3 Connect to TM1

Make sure the Administration Server and the TM1 Server are started. By default the installer will havecreated two Windows Services for those. The account running those services is yet irrelevant.

Next, connect to TM1 by clicking Edit -> Login -> TM1.

Type in the host name of the box running Admin Server and click the button next to “Server”. Adialog displaying all the active TM1 servers will appear. Select the TM1 server you want to connect toby double-clicking on it. Finally provide user name and password, if this is a new server “admin” and “apple” will do. Click Test. If the connection succeeds click OK to complete the login.

If the connection cannot be established verify that• TM1 Server and Administration server are running• tm1s.cfg is configured for the correct authentication mode. This must not be LDAP yet.

Note: If some other authentication mode is used, ensure that all the proper settings are in place toallow ETLDAP to connect to TM1 server.

Business Analytics

Figure 6 - TM1 Login Dialogue

12


3.3.4 Search LDAP

You're now connected to LDAP and TM1 and can start importing users from the LDAP. Click File -> Connect. This connects ETLDAP to the LDAP. The “Search” button will become enabled now. The next step is to craft an LDAP search which will return a set of entries to import into TM1. Thissearch consists of • a “SearchDN” which is a DN where to start the search of• a filter which defines which entries to find • a comma separated list of attribute names which defines which attributes of the entries

in the result set to display. (the DN of the entry is displayed by default).• a search scope which defines whether child entries of the Search DN will be searched or not

Contact your LDAP administrator and/or refer to the Operations Guide for more information aboutsearching LDAP servers.

Press “Search” to run the defined search.

The tool will display the result set,if any, in a list view where each column represents one attribute.By right-clicking on an entry one can display all attributes of the particular entry. This is a preview of the data which potentially get's imported, however this is just informal to verifythe search parameters. To define which attributes of an entry found by the search go in to TM1another dialogue is used.

Business Analytics

Figure 7 - LDAP Load tool dialogue

13


3.3.5 Define mapping

In the TM1 database each user has several properties. Each TM1 user has a unique user name, hebelongs to at least one group and he may have an email address. To make LDAP authentication workthose user properties must be populated with data read from the LDAP. The dialogue shown belowallows for mapping attributes of an LDAP user to those properties. To get to the mapping click Edit -> Mapping

First there is the TM1 user name (“client”) a user provides to authenticate to TM1. It must be uniqueand is case-sensitive. The client field will be used to create the user in the }Clients.dim and }ClientProperties.dim. Choose an attribute which contains strings adhering to the requiredcharacteristics from the drop-down, mind that the attribute specified here determines what the userhas to type in for login. The listed attributes depend on LDAP server type (the schemas supported bythe LDAP) and BC permissions. Usual mapping is an attribute like “uid”, “cn” or sAMAccountName forActive Directory but even “email” is fine if user's shall authenticate using their email to authenticate.

Note: In case no attributes appear in the drop-down refer to Troubleshooting section for a work-around or verify LDAP permissions of the BC in a third party LDAP browser tool. The BC must be ableto view all the attributes of a user.

The next property is “group”. This property denotes the name of a group the user is a member of andit's value will be used to create entries in the }Groups.dim. One may choose an LDAP attribute whichcategorizes the user into groups like a department ID, a building or location ID/name.

Finally one can specify an LDAP schema attribute to map to the email property of a TM1 user. MostLDAP server schemas support an attribute holding the user's email address. Map this one here andthe users created in TM1 will have the email property populated.

Business Analytics

Figure 8 - ETLDAP TM1 Mapping dialogue

14


When done click OK. By now the “Export” button should have become activated and it's time to start the export to TM1.During the export ETLDAP will read data from the LDAP and create the users and groups in TM1.Verify the log by clicking View -> Log after the export to learn which users and groups have beencreated and which failed. The assignment of users to groups will have to be done manually after the export though. For detailsrefer to the TM1 9.5 operations Guide “Running the ETLDAP tool”. This is of particular interest sincemost probably none of the imported users will be part of the ADMIN group, refer to section 3.3.7 fordetails.

3.3.6 Edit TM1s.cfg

Now after users have been created in TM1 the authentication for the TM1 server can eventually beswitched to LDAP. For this the Passwordsource property in TM1s.cfg must be changed to LDAP.Next the general connection information for the LDAP server must be provided as well. However there are quite a few other things to be aware of. As explained in Section 2.2.1 the TM1server will connect to the LDAP server to verify the user credentials. Since the LDAP server runs SSLthe process of establishing a connection to it consists of two steps.First the network connection must be established which in this case means network layer connection(which we assume is provided) and more important the SSL handshake. This handshake involvesverification of the LDAP server's certificate and acknowledgement of the trust to it. The second step is to bind to the LDAP server, that is authenticate and establish a session forretrieving data. Both steps can configured by settings in the TM1s.cfg file and hence an administrator can tweak theprocessing of those steps to adjust to specific setups. In general tm1s.cfg must be tailored in three areas which are discussed now. After the tm1s.cfg file has been adjusted, don't forget to save it.

3.3.6.1 General settings

To enable LDAP authentication for TM1 edit the PasswordSource property to “LDAP”.

PasswordSource=LDAP

Next provide the basic LDAP connection information in these properties

Business Analytics

Figure 9 - ETLDAP TM1 Mapping defined

15


LDAPHost=<host>LDAPPort=<port>LDAPSearchBase=<baseDN>LDAPSearchField=<mapped client attribute>

Specify host and port, the default LDAPS port is 636 but it could be anything, depends on what portthe LDAP server uses. The SearchBase should be the same DN used during running the ETLDAP tool,the BaseDN requested in 2.2.1. The LDAPSearchField must be the same LDAP schema attributespecified for the client mapping in 2.2.3.

3.3.6.2 Verifying the SSL certificate

TM1 leverages the Microsoft Windows API for cryptographic functions. This includes verification ofSSL certificates. By default TM1 will open a secure socket to the configured host and port and expectthe server on the other end to initiate an SSL handshake by presenting it's certificate. The certificatewill then be passed to the Windows API for verification. This implies that the Windows operatingsystem must be able to verify the trust relationship to the certificate. For this to work the CAcertificate which signed the LDAP server certificate or, in case of a self signed certificate, the LDAPserver's certificate itself, must be trusted by Windows which means they must be a “Trusted RootCertifying Authority”. After this trust is confirmed the Windows API will request the CertificateRevocation List (CRL) certificate for the Trusted Root CA if applicable to ensure the certificate is notalready revoked. Only then it will signal to the caller that the presented certificate was successfullyverified.This most convenient handling of the SSL handshake can be overridden to address some challenges.TM1 expects the subject of the certificate received to match the server name of the configuredendpoint. If there is a mismatch the verification will fail as TM1 requests the windows API to verifythe received certificate against the configured server name. If the configured host and port don'tactually represent an LDAP server but for example a proxy this will fail. For that reason it's possible todelegate the verification of the SSL certificate to TM1. This is achieved by addingLDAPVerifyServerSSLCert=T to the tm1s.cfg. This will instruct TM1 to handle the verificationitself.If TM1 is handling the certificate validation it will process the two steps of verification (trust, CRLchecking) like the Windows API would have done but uses a slightly different approach. Instead of verifying the received certificate against the configured host name and validate trust it willfirst look at a list of server names. This list is a white list, meaning all server names which should beaccepted are explicitly listed. The entries must exactly match the subject of the certificate presentedto TM1 in the SSL handshake by the server on the other end. Per server there must be an entry likethis: LDAPVerifyCertServerName=<server_cert_subject>. Only if a match is found TM1 willcontinue to process. If the certificate subject matches one of the servers on the white list TM1 callsthe Windows API explicitly asking to verify this single certificate only. Again this requires Windows totrust the certificate which implies to have the correct trusted root CA imported. If for whatever reason that trust doesn't work one can skip the trust verification step by specifyingLDAPSkipSSLCertVerification=F. With this setting TM1 will not verify the server certificate atall but simply accept it.

Business Analytics

16


Once trust is confirmed (or that test has been skipped) TM1 will want to verify the CRL certificate.This again works by calling the Windows API so the CRL certificate for the trusted root must havebeen imported to Windows. If that certificate doesn't exist in Window's truststore one must skip theCRL processing by specifying LDAPSkipSSLCRLVerification=T otherwise TM1 will insist onchecking the CRL. If LDAPVerifyServerSSLCert=F (Window handles all) this is notrequired as the API in that case is smart enough to tolerate an empty or not existent CRL certificate.If all the tests above signal success the SSL handshake is complete and TM1 will now try toauthenticate to the LDAP server.

3.3.6.3 Authenticate to LDAP server

Authentication to the LDAP server can happen two ways.If the LDAP server really is a Microsoft Active Directory then TM1 can use Windows integratedauthentication protocol to authenticate to the LDAP (AD in this case). Theoretically this could work forother LDAP servers as well but it will require specific modules to be configured for the LDAP server. Ifunsure whether the targeted LDAP server supports integrated Windows authentication ask your LDAPadministrator. For now we assume this only applies to Microsoft AD. So if integrated Windows authentication should be used, the LDAPUseServerAccount=T entrymust be added to the tm1s.cfg. This will instruct TM1 to authenticate to the LDAP using Windowsintegrated authentication for the account running the TM1 server. That is, whichever account runsTM1 server will authenticate to the Active Directory and hence this account must have sufficientprivileges in AD.As an additional hint it's a best practice to specify the domain name for host rather than an actualhost name. This way the Windows Domain Locator process can be leveraged which will route requeststo the Domain controller “best suited” to handle it. This can be based on availability (fail-over),geographical proximity or load, a Windows Domain administrator can configure this. If a specificdomain controller is referenced by it's IP or DNS requests will only handled by this single host.Usually the mapping for clientID should be sAMAccountName which is the user's windows login name.

Example for tm1s.cfg attaching to some AD

PasswordSource=LDAPLDAPPort=636LDAPHost=some.domain.comLDAPSearchBase=dc=some,dc=domain,dc=comLDAPSearchField=sAMAccountNameLDAPUseServerAccount=T

# Should TM1 verifiy the cert (=T)or Windows (=F)?LDAPVerifyServerSSLCert=F # only if LDAPVerifyServerSSLCert=T # verify based on a whitelist (=F)or simply default to true (=T) LDAPSkipSSLCertVerification=F # whitelist of accepted servers

Business Analytics

17


LDAPVerifyCertServerName=wcsfrkxp99.mydomain.com # skip CRL processing (=T) or process (=F) LDAPSkipSSLCRLVerification=T

In case the LDAP server does NOT support integrated Windows authentication tm1s.cfg must specifyLDAPUseServerAccount=F and explicitly provide Binding Credentials for the TM1 server to use.Those get specified in several properties however. First there is the absolute DN of the binding user,which TM1 labels as “Well Known User Name”. This is specified in LDAPWellKnownUserName. Thepassword for this user is not specified in the file in clear text. Rather the TM1 took tm1crypt must beused to store the password into an encrypted file. Run the tm1crypt utility like this:

<TM1_ROOT>/bin/tm1crypt -pwd <password> -keyfile <key_output_file> -outfile <encrypted_output_file> [-validate]

For password specify the password for the WellKnownUser, so the password from the BC. Forkey_output_file chose a file name which indicates that this is a key for an encrypted file like“ldappasskey.dat”. For encrypted_output_file chose a file name which indicates that this is anencrypted password file like “ldappass.dat”.In tm1s.cfg one specifies the encrypted file and the key file which holds the key used to encrypt thepassword in LDAPPasswordKeyFile and the encrypted password file in LDAPPasswordFile. Example for tm1s.cfg attaching to OpenLDAP

PasswordSource=LDAP

LDAPHost=wcsfrkxp99.mydomain.comLDAPPort=636LDAPSearchBase=ou=people,dc=cognos,dc=comLDAPSearchField=uid

LDAPUseServerAccount=FLDAPWellKnownUserName=cn=binduser,dc=cognos,dc=comLDAPPasswordFile=e:\cognos\tm1\9.5\bin\ssl\ldappass.datLDAPPasswordKeyFile=e:\cognos\tm1\9.5\bin\ssl\ldappasskey.dat

# Should TM1 verifiy the cert (=T)or Windows (=F)?LDAPVerifyServerSSLCert=F # only if LDAPVerifyServerSSLCert=T # verify based on a whitelist (=F)or simply default to true (=T) LDAPSkipSSLCertVerification=F # whitelist of accepted servers

Business Analytics

18


LDAPVerifyCertServerName=wcsfrkxp99.mydomain.com # skip CRL processing (=T) or process (=F) LDAPSkipSSLCRLVerification=T

3.3.7 Add a user to ADMIN group.

At this point everything is ready to recycle the TM1 server and activate the LDAP authentication.When doing so however, there won't be any administrator account available. This is because ETLDAPonly created users and groups based on the LDAP data but it didn't assign any user to a group.Further more, the users which were assigned to the ADMIN group won't be accessible any more onceauthentication is switched to LDAP. It's hence necessary to promote at least one user to administratorbefore finally switching to LDAP authentication. • To do so bring up Architect.• Double-click the TM1 server to be switched to LDAP authentication• Login as an administrator (admin/apple might do).• Right-Click the server name and choose Security -> Clients/Groups

Figure 10 - Navigate to Security -> Clients/groups

• Find one of the newly created user imported form the LDAP and make him an administrator bychecking the box for the ADMIN group. This account will now be your new Administration account.

• Close Architect

3.3.8 Recycle

To finally activate the LDAP authentication for this server make sure the changes to tm1s.cfg havebeen saved and recycle the TM1 Admin Server and the TM1 server configured for LDAPauthentication.

3.3.9 Import trusted root CA certificate into Windows truststore

The final step to complete the setup is to import the right certificate into the Windows truststore sothat Windows trusts the server certificate presented by the LDAP server.

Business Analytics

19


This can be done two ways: • Using the Microsoft Windows certificate snap in for the Microsoft Management Console (MMC)

either directly or via Internet Explorer Wizard.• Use the importsslcert tool from TM1

3.3.9.4 Use importsslcert

There is an undocumented tool which TM1 uses silently when setting up it's certificates for internal sslcalled importsslcert. This tool will place a certificate along with it's CRL certificate into Window'struststore. This is by far the easiest way to do it since there's basically no room for errors.

To call the tool go to <TM1_ROOT>/bin and call it like thisimportsslcert -ca <certificate> [-crl <crl_certificate>]

For certificate provide the absolute path to the file containing the CA certificate (or the servercertificate in case you use self-signed certificate). One can optionally provide a CRL certificate as well.The tool will print out either success or failure notices.That's it, your done.

3.3.9.5 Use Windows Certificate snap-in

To importing a certificate into Windows as a trusted root CA is straight forward with one slightexception. One must be careful when Windows is asking about the certificate store to place thecertificate in. There is a subtle difference between logical stores and physical stores. The WindowsAPI expects certificates to be in the physical store on the local host. If for some reason they are notplaced in there trust cannot be established although Windows may show the certificate as a trustedroot CA.

To import using the Internet Explorer Browser • open the browser• go to Internet Options, Content tab• Find the Certificates section and click on Certificates• Click “Import...” , the Certificate Import Wizard will appear• Click Next• Browse to the certificate file to import and click Next• The Certificate Store selection dialogue will come up. Make sure to check “Place all certificates in

the following store” option. Then click Browse.

Business Analytics

20


• In the upcoming dialogue, check the “show physical stores” option and navigate to Third PartyRoot Certification Authorities -> Local Computer and click on it to select it. Press OK.

• Back in the Certificate Import Wizard click Next

Business Analytics

Figure 11 Windows Certificate Import Wizard

Figure 12 Select Certificate Store dialogue

21


• On the final summary page click Finish• Once the message box announcing the successful outcome of the import appeared the certificate

should appear in the list on the “Trusted Root Certification Authorities”.

This completes the import task.

Note:You can achieve the same by using the Certificates snap-in for the Microsoft MMC. Ensure that once nyou selected the Trusted Root Certification Authorities element you click on View-> Options andspecify the “physical certificate stores” option.

Business Analytics

22


Import the certificate into Trusted Root Certifying Authorities -> Local Computer -> Certificatesfolder.

3.4 Log on to TM1 using LDAP Credentials

Now that the setup is complete you should be able to log in to TM1 using any client with your LDAPcredentials. Mind that a TM1 administrator will yet have to map users to groups if not alreadycompleted earlier as the LDAP import step doesn't bring over the group memberships.

Business Analytics

23


4 TroubleshootingThis section tries to provide answers to the most common issues observed when setting up LDAPauthentication for TM1 9.5.By far the most common error is the “Connection Error” with error code 0x51 /81. This almost alwaysindicates SSL handshake issues. The below points may help resolving those.

4.1 Add debug logger for LDAPAuth

When TM1 is configured to verify the certificate there is a logger which can be added to the thetm1s-log.properties file. With this logger tm1.log will contain additional information about whythe certificate validation failed or what else went wrong. If Windows is validating the server certificate(LDAPVerifyServerSSLCert=F) the logger will only show LDAP ERROR: 0x51 - ldap_connectfailed. In that case it's a good idea to have TM1 verify the SSL certificate (change toLDAPVerifyServerSSLCert=T) and enable this logger to gather more information.

To enable the logger edit <TM1_SERVER_ROOT>/ tm1s-log.properties.Right after the line log4j.logger.TM1=INFO, S1 add a new line like this

log4j.logger.TM1=INFO, S1log4j.logger.TM1.LDAPAuth=DEBUGSave the file and stop the tm1 server. Move out or delete the old tm1.log and restart the server.Retry the authentication and review the new error messages in the log.

4.2 Verify certificate

To ensure the certificate presented by the LDAP server is actually valid try looking at it in eitherWindows (rename to *.cert to get it recognized by windows) or use some PKI tools to view it.OpenSSL is useful too. Things to look at are

• is the subject/CN the Netbios hostname or the fully qualified domain name of the LDAP server ?• Is this a self signed certificate ? You would recognize a self signed certificate by the fact that

subject and issuer fields contain the same string while there is no certificate attribute setindicating this is a CA certificate. In case it is a self-signed make sure this certificate has been imported to Windows.

• Each certificate has an expiry. Make sure the certificate is NOT expired• Ensure the certificate is not revoked. If the trusted root CA has a CRL provided check that the

certificate is not listed there as being revoked. • Can you connect to LDAP using other LDAP clients like Microsoft LDP, OpenSSL, Softerra

LDAP...

Business Analytics

24


4.3 Verify tm1s.cfg settings

A good approach to troubleshooting is to leverage the advanced settings in tm1s.cfg. Change theconfiguration to have TM1 process the certificate validation and skip certificate validation and CRLchecking in a first step like this:...# Should TM1 verifiy the cert (=T)or Windows (=F)?LDAPVerifyServerSSLCert=T # only if LDAPVerifyServerSSLCert=T # verify based on a whitelist (=F)or simply default to true (=T) LDAPSkipSSLCertVerification=T # whitelist of accepted servers LDAPVerifyCertServerName=wcsfrkxp99.mydomain.com # skip CRL processing (=T) or process (=F) LDAPSkipSSLCRLVerification=T

If this doesn't work the issue is not about SSL handshake but network connection or LDAPauthentication for the BC or the Service Account. In case of using the ServerAccount(LDAPUseServerAccount=T) switch to use explicit BC and run tm1crypt to generate the requiredfiles. Even for AD the explicit BC work and this rules out issues with the integrated Windowsauthentication.

If the above configuration worked, re-enable the SSLCertVerification and enable the LDAPAuth loggerif not already in place. Scan the error code in tm1.log.

4.4 Most frequent error codes in tm1s.log with enabled logger LDAPAuth• LDAP ERROR: 0x800b0109

The following error stack indicates an issue with the white list of acceptable server names:

LDAP ERROR: 0x800b0109 - Error verifying server certificate chain validity LDAP ERROR: Error verifying server certificate no match for <server> LDAP ERROR: 0x51 - ldap_connect failed.

Basically this means that the subject of the presented server certificate (the one printed for<server> didn't match any entry in the white list. The next action is to obtain the certificate'ssubject string and copy and paste it to the white list in an entry ofLDAPVerifyCertServerName=<subject>.

• LDAP ERROR: 0x800b010f The following error stack indicates the certificate is not trusted by Windows

LDAP ERROR: 0x800b010f - Error verifying server certificate chain validity LDAP ERROR: Error verifying server certificate no match for <server> LDAP ERROR: 0x51 - ldap_connect failed.

This indicates an issue with the trust to the LDAP server certificate by Windows. Suggested actionis to ensure the certificate has been imported to Windows correctly , refer to section 2.2.6

Business Analytics

25


The following error stack indicates an issue with the CRL processing.

LDAP ERROR: 0x80092012 - Error verifying server certificate chain validity LDAP ERROR: Error verifying server certificate no match for <server> LDAP ERROR: 0x51 - ldap_connect failed.

Either the certificate is revoked or TM1 is looking for the CRL certificate but cannot find it in theWindows store. Suggested action is to skip the CRL processing (setLDAPSkilSSLCRLVerification=T) of import the CRL certificate from the CA.

4.5 No attributes shown in ETLDAP tool

In case ETLDAP mapping dialogue drop-downs don't show any LDAP attributes to map this indicates apermission issue with the BC. If you cannot run ETLDAP using proper BC with sufficient privileges youcan work around the issue by specifying the mapping in a configuration file instead. This requires toknow the names of the attributes to map of course.To do so, after having connected to the LDAP and having run the search go to File -> save asThis will allow to save the configuration setting made in the ETLDAP tool to a file. Specify adescriptive name like ETLDAP.conf.

Open the saved configuration file and add the following settings or change if already existing.

mapval:tm1client || <client_mapping>mapval:tm1group || <group_mapping>mapval:rep.email || <email_mapping>

Save the file. You may now re-Open ETLDAP and load the configuration file via File -> Open.

Business Analytics

26

Configuring LDAP authentication for TM1 9 · Configuring LDAP authentication for TM1 9.5 If now...

Documents

Transcript of Configuring LDAP authentication for TM1 9 · Configuring LDAP authentication for TM1 9.5 If now...