Worked example of a Netcool ObjectServer LDAP configuration

Body

Introduction

This is a follow on to 'Enhancements to ObjectServer LDAP authentication'. This time I will walk through a step-by-step example of configuring an ObjectServer to authenticate using LDAP. I will demonstrate configuring an ObjectServer to authenticate users in multiple organizational units, which requires the LDAP search enhancement discussed in the previous blog. This article is aimed at someone who is familiar with ObjectServer configuration, but not familiar with LDAP.

I approach the configuration by gathering the information required and filling in the worksheet below. The worksheet guides me through configuring and testing the ObjectServer. Items in bold would typically be supplied by the person responsible for the LDAP server , items in italics will be set up by the OMNIbus administrator.

LDAP Worksheet

<LDAP worksheet>

LDAP information	Corresponding ldap.props	Ldap search	Configuration
IP address or hostname of LDAP server	HostName	-h
Port of ldap server	SSLPort	-p
SSL certificate for LDAP server	imported into ObjectServer keystore
SSL certificate label	SSLKeyStoreLabel	-N
Keystore location		-K
Keystore password
Directory to start searches from	LDAPSearchBase (where multiple directories are separated by ;;)	-b
LDAP password	LDAPBindPassword	-w
LDAP userid to connect with (for bind security)	LDAPBindDN	-D
LDAP attribute to map to OMNIbus username
LDAP Query	LDAPSearchFilter with %s in place of <username>	Main argument

Gathering the required information

I need the following connection information:

1. the IP address or hostname of the LDAP server

2. the LDAP server port

3. is the LDAP server configured to require bind security to connect and issue a search?

   • If bind security is required, I need an LDAP userid and password for the ObjectServer to connect with

4. is encryption of LDAP data via SSL required?

   • If SSL is required then a LDAP certificate is needed

I also need the following information on the LDAP directory structure:

5. the base distinguished name to start searches from.

   • This is one or more root directories where the userids are stored in the LDAP server.

6. The LDAP user attribute that corresponds to the OMNIbus user's logon name.

In my example configuration both bind security and SSL are required.

5. the base distinguished name to start searches from.

The base distinguished name depends on where the userids you wish to authenticate are and the LDAP directory structure. The ObjectServer searches recursively from each specified directory upwards. In my example, LDAP is configured with directories

COM

IBM

HURSLEY

Operations

DEV

Support

MANAGEMENT

The users I need to give access to the ObjectServer are located in

ou=Operations,dc=HURSLEY,dc=IBM,dc=COM

and

ou=DEV,dc=HURSLEY,dc=IBM,dc=COM

I could either make the base directory

(a) 'dc=HURSLEY,dc=IBM,dc=COM'

or specify both separated by double semicolons.

(b) 'ou=Operations,dc=HURSLEY,dc=IBM,dc=COM;;ou=DEV,dc=HURSLEY,dc=IBM,dc=COM'

Option (a) searches Support and MANAGEMENT in addition to the directories we are interested in which would possibly impact performance. Option (b) limits the search to the 'Operations' and 'DEV' groups. For this reason I will go for option (b)

6. The LDAP user attribute to map.

Attributes used vary across LDAP schemas. For example 'uid' is frequently used in Posix installations, whereas Microsoft Active Directory uses 'sAMAccountName';

In my example 'uid' is set to the abbreviated user name and is appropriate for us.

e.g. uid=aperkins  , uid=bsmith

Now I need to formulate an LDAP query. The search query is in the standard LDAP format with an additional ObjectServer specific parameter '%s' . The ObjectServer replaces '%s' with the logon name of the user at runtime.

A very simple form of the LDAP query is (attribute=value). LDAP query syntax and the query formulation can impact on LDAP server performance. Your LDAP administrator could advise on the best performing query to use. In my example I will use the simplest possible query, (uid=%s).

Configuring OMNIbus to use the SSL certificate

My LDAP administrator has given me an SSL certificate to use to connect to the LDAP server. I need to import the certificate into the keystore used by the ObjectServer. The keystore must be named 'omni.kdb' and put in $NCHOME/etc/security/keys on UNIX or %NCHOME%/ini/security/keys on Windows. OMNIbus ships with a tool called 'nc_ikeyman' to generate keystores and import certificates.

In my example there is no existig keystore so I create one by running $NCHOME/bin/nc_ikeyman and selecting

• key->database->file new
• key->database type → cms (default)
• filename → omni.dbd
• I leave 'location' as the default.
• This corresponds to 'Keystore location' in <LDAP worksheet>

• Enter a password and set 'stash password to file' to true.
• This corresponds to  'Keystore Password'  in <LDAP Worksheet>

• Select 'Signer Certificates' from 'Key database content'.

• I click 'Add' then specify the certificate file. I give the label a meaningful name 'LDAPSS' because I reference it in the ObjectServer configuration.
• This corresponds to 'SSL Certificate Label'  in <LDAP Worksheet>
  

 

Filling out the worksheet

Here is what the worksheet looks like now it has been filled out. (In practice I would print out a copy of the worksheet and fill it out as I went through the steps above).

 

<LDAP worksheet>

LDAP information	Corresponding ldap.props	Ldap search	Our sample configuration
IP address or hostname of LDAP server	HostName	-h	testhost.ibm
Port of ldap server	SSLPort	-p	636
SSL certificate for LDAP server	imported into ObjectServer keystore
SSL certificate label	SSLKeyStoreLabel	-N	LDAPSSL
Keystore location		-K	$NCHOME/etc/keys/ omni.dat (UNIX) and %NCHOME%\ini\security\keys\omni.kdb (WINDOWS)
Keystore password			omnibus
Directory to start searches from	LDAPSearchBase (where multiple directories are separated by ;;)	-b	ou=Operations,dc=HURSLEY,dc=IBM,dc=COM;;ou=DEV,dc=HURSLEY,dc=IBM,dc=COM
LDAP password	LDAPBindPassword	-w	a_password
LDAP userid to connect with (for bind security)	LDAPBindDN	-D	cn=searchuser,dc=HURSLEY,dc=IBM,dc=COM
LDAP attribute to map to OMNIbus username			uid
LDAP Query	LDAPSearchFilter with %s in place of <username>	Main argument	(uid=<username>)

Testing the information is correct:

I try connecting using an LDAP tool first  to test the configuration before configuring the ObjectServer. l used the 'ldapsearch' tool that ships with the IBM Tivoli Directory Server client. My filled out worksheet shows me which parameters to set on LDAP search.  (If you use a different version of ldapsearch the command line options may vary, see your product documentation for more details). The only parameter which differs between LDAP serach and the ObjectServer configuration is 'LDAP Query'. As mentioned previously, on the ObjectServer, you replace <username> with '%s'  on ldapsearch you search for a specific user.

I LDAP search for one of the users I wish to authenticate with the ObjectServer 'ouuser'.

ldapsearch -h testhost.ibm -p 636 -b "ou=Operations,dc=HURSLEY,dc=IBM,dc=COM" -D cn=searchuser,dc=HURSLEY,dc=IBM,dc=COM -w a_password -K %NCHOME%\ini\security\keys\omni.kbd -P omnibus -N LDAPSSL  -v (uid=ouuser)

This completes successfully and returns information about the user

uid=ouuser,ou=Operations,dc=HURSLEY,dc=IBM,dc=COM
userPassword={SHAZhefER11tLmB1WRdNnpEt8=
uid=ouuser
objectClass=inetorgperson
objectClass=organizationalPerson
objectClass=person
objectClass=top
sn=UserName
cn=Sample

The configuration information looks good, and I know the user entry 'ouuser' is available on the LDAP server. The next steps are configure the ObjectServer to authenticate with LDAP and set up userids on the object server which correspond to the LDAP users.

Defining the ObjectServer to LDAP connection.

First of all I copy the results from our worksheet into the  ldap.props file in $OMNIHOME/etc/
Hostname: 'testhost.ibm'    
LDAPBindDN: 'cn=searchuser,dc=HURSLEY,dc=IBM,dc=COM'        
LDAPBindPassword: 'a_password'        
LDAPSearchFilter: '(uid=%s)'     
LDAPSearchBase: 'ou=Operations,dc=HURSLEY,dc=IBM,dc=COM;;ou=DEV,dc=HURSLEY,dc=IBM,dc=COM'    
SSLPort: 636                
SSLKeyStoreLabel: 'LDAPSSL'            

In addition I also need to set
SSLEnabled: TRUE
in ldap.props to tell the ObjectServer to use a SSL connection.

Activating LDAP in the ObjectServer

I need to add the following entry  to the ObjectServer's .props file to tell it to authenticate external users via LDAP
Sec.ExternalAuthentication: 'LDAP'

Creating a user

I am now ready to start the ObjectServer and create users. After starting the ObjectServer I run the nco_config tool to create a user.
 I start by creating the user we tested with ldapsearch. I open the 'Users' tab on the LHS and right click the main pane , then I select Add User

The groups, restriction filters etc are created as normal. The important configuration from an LDAP perspective is to tick 'External Authentication'.   OMNIbus users can be locally authenticated by the ObjectServer or authenticated by an external system. The 'External Authentication' checkbox ensures that the ObjectServer will contact the LDAP server to verify the user's password. I also give the user access to the 'ISQL' group, so we can test the connection using the command line SQL tool.

Testing the OMNIbus configuration

I can now log onto the ObjectServer with a command line tool and test if the user can be authenticated. The command line tool to log on and run SQL commands is nco_sql on UNIX and ISQL on Windows.

The nco_sql options are
  $OMNIHOME/bin/nco_sql -user ouuser -server NCOMS
(I am prompted for a password)

That's it, I am successfully authenticated through the LDAP server. The next step would be to populate the ObjectServer with the other users that I intend to authenticate via LDAP.

Taking a look under the hood.

Now I've got it working, it might be interesting to see how the ObjectServer interacts with LDAP. I do this by switching on debug level logging in the ObjectServer and analyse the output. I've annotated the log entries below to explain what they show.

2014-01-30T15:05:01: Debug: D-AUT-105-001: Initialising SSL to use certificates stored at: /opt/IBM/Tivoli/netcool/etc/security/keys/omni.kdb
2014-01-30T15:05:01: Information: I-AUT-104-006: About to bind to LDAP server for user cn=searchuser,dc=HURSLEY,dc=IBM,dc=COM
2014-01-30T15:05:01: Information: I-AUT-104-007: Successful bind to LDAP server for user cn=searchuser,dc=HURSLEY,dc=IBM,dc=COM.
- the ObjectServer has connected to LDAP with the user credentials required to do an LDAP search
2014-01-30T15:05:01: Debug: D-AUT-105-005: About to issue LDAP search with filter '(uid=ouuser)' and base dn 'ou=Operations,dc=HURSLEY,dc=IBM,dc=COM'
2014-01-30T15:05:01: Debug: D-AUT-105-004: LDAP search on user 'ouuser' returned distinguished name 'uid=ouuser,ou=Operations,dc=HURSLEY,dc=IBM,dc=COM'
- a search on the userid returns the full distinguished name of the user. (The distinguished name is required in order to authenticate the user). Note '%s' in the LDAPSearchFilter setting is replaced by the specific userid to make a query of (uid=ouuser).
2014-01-30T15:05:01: Information: I-AUT-104-006: About to bind to LDAP server for user uid=ouuser,ou=Operations,dc=HURSLEY,dc=IBM,dc=COM
2014-01-30T15:05:01: Information: I-AUT-104-007: Successful bind to LDAP server for user uid=ouuser,ou=Operations,dc=HURSLEY,dc=IBM,dc=COM.
- we've authenticated the user successfully using the distinguished name returned from the search and the password supplied by the user when they logged onto the ObjectServer
2014-01-30T15:05:01: Information: I-OBX-104-007: User ouuser@testserver.hursley.ibm.com logged in successfully (connection ID 2)
- success!

Conclusion

You've seen a walk-through of configuring an ObjectServer to authenticate users LDAP and protecting the data via SSL encryption. I hope this was helpful in explaining the process and showing what information you need to gather to successfully set up the ObjectServer.