Configuring an LDAP user registry

A basic user registry is installed by default after initial solution installation. However, the basic user registry does not have support for password policies, password length, password expiration dates, or user lockout. Configure the solution to work with a Lightweight Directory Access Protocol (LDAP) user registry. An LDAP user registry performs better than other user registry configurations, and is more scalable.

Before you begin

Note: Before you configure IBM® Intelligent Operations Center to use an LDAP user registry, you must ensure that your LDAP server has a secure Password Policy. Without a secure LDAP Password Policy, user passwords might be obtained by a brute force attack that uses HTTP basic authentication requests to IBM Intelligent Operations Center.

To use an LDAP user registry configuration, you must perform extra configuration steps after the initial solution installation is complete. The solution requires certain users and user groups to be present in the LDAP user registry. Your administrator can add the users by using the external user registry manager tool.

If this is the first time that you are configuring LDAP authentication for the solution, you must add IBM Intelligent Operations Center user groups and users to your LDAP directory.
1. Add user groups for the group names that are defined by the following system properties:
  PlatformAdminsGroup
  
  The PlatformAdminsGroup system property defines the platform administrator group, where the default value is PlatformAdmins.
  
  SolutionAdminsGroup
  
  The SolutionAdminsGroup system property defines the solution administrator group, where the default value is SolutionAdmins.
  
  SystemAdminsGroup
  
  The SystemAdminsGroup system property defines the system administrator group, where the default value is SystemAdmins.
2. Add an Operators user group.
3. Add a system administrator user as defined by the SystemAdminUser system property, and add this user to the system administrators group.
4. Add a soladmin user as a member of the solution administrator group.
5. Add a platformadmin user as a member of the platform administrator group.
The PlatformAdmins, SolutionAdmins, and SystemAdmins user groups are created by default in the ioc.ioc_user_group database table at installation. If you change the default values for the PlatformAdminsGroup, SolutionAdminsGroup, or SystemAdminsGroup system properties, you must create the new user groups in the database. For example, if you change the value of PlatformAdminsGroup to UserAdmins, then enter the following command as the db2.instance.user on the data server, where db2.instance.user is defined in the ioc.install.properties file:
```
db2 "insert into ioc.ioc_user_group (name) values ('UserAdmins')"
```
You must also ensure that these user groups and user members are added in the User Management view in IBM Intelligent Operations Center. For more information, see Managing users, user groups, and roles.

About this task

These instructions are specifically for a platform installation, and you must have the required privileges to update files and run DB2® commands on the application server and on the data server.
In the commands that are given in the following procedure, replace the db2.instance.user, ioc.user, liberty_install_dir, and liberty.instance.name variables with the values that are configured in your ioc.install.properties installation properties file.
- The default value for the DB2 instance user variable, db2.instance.user, is db2i1own, and the default value for ioc.user variable is iocadmin.
- The liberty_install_dir value is the WebSphere® Application Server Liberty Profile installation directory, and the liberty.instance.name value is the name of the Liberty instance.

Procedure

Configure the LDAP user directory settings by using either of the following steps:
- Create or update system properties, similar to the following example values:
  - LdapDNPrefix with an example value of uid. The property value specifies the string to add as a prefix to the user name to form the distinguished name.
  - LdapServerCredentials with an example value of {"uid":"cn=root","pw":"my_password"}. This property value specifies the credentials for the user with read/write privileges for the LDAP user registry.
  - LdapServerQueryOnlyCredentials with an example value of {"uid":"cn=binduser","pw":"my_bindpassword"}. This property value specifies the credentials for the user with read-only privileges for the LDAP user registry.
  - LdapProviderUrl with an example value of ldap://<ldap_server_name>:389
  - LdapUserFilter with an example value of ou=users,ou=swg,o=ibm,c=us
  - LdapGroupFilter with an example value of ou=groups,ou=swg,o=ibm,c=us
  - The LdapRoleFilter with an example value of ou=roles,ou=swg,o=ibm,c=us must be set to add roles to your solution. The value for the LdapRoleFilter system property is the DN for the roles organizational unit in your LDAP user registry. For more information, see Configuring LDAP support for roles.
  - LdapBaseDN with an example value of ou=swg,o=ibm,c=us
  - LdapUserObjectClass with an example value of inetOrgPerson.
- Log on to the data server as the DB2 instance user, db2.instance.user. For example, log on as db2i1own. Enter DB2 commands, similar to the following example commands, where root_password is the root password to the server where the user registry is installed, and LDAP_host_name is the host name of the user registry server. Enter each command on one line.
```
db2 connect to iocdb

db2 "update IOC.SysProp
    set value = '{\"uid\":\"cn=root\",\"pw\":\"root_password\"}' 
        where name = 'LdapServerCredentials'"

db2 "update IOC.SysProp
    set value = '{\"uid\":\"cn=root\",\"pw\":\"query_user\"}'
        where name = 'LdapServerQueryOnlyCredentials"

db2 "update IOC.SysProp
    set value = 'ldap://LDAP_host_name:389' 
        where name = 'LdapProviderUrl'"

db2 "update IOC.SysProp
    set value = 'DN' where name = 'LdapDNPrefix'"

db2 "update IOC.SysProp
    set value = 'ou=myg,o=abc,c=us' where name = 'LdapBaseDN'"

db2 "update IOC.SysProp 
    set value = 'ou=groups,ou=myg,o=abc,c=us' where name = 'LdapGroupFilter'"

db2 "update ioc.sysprop
    set value = 'ou=users,ou=myg,o=abc,c=us'
        where name = 'LdapUserFilter'"

db2 "update IOC.SysProp
    set value = 'inetOrgPerson' where name = 'LdapUserObjectClass'"

db2 "update IOC.SysProp
    set value = 'ou=roles,ou=myg,o=abc,c=us' where name = 'LdapRoleFilter'"
```
Note: Because of the system properties cache, there can be a delay of up to 15 minutes before changes take effect when you use DB2 commands to update the IOC.SysProp table. If you want to avoid this delay, update the system properties by using the system property REST service at the following URI:
```
/ibm/ioc/api/sysprop-service/sysprops
```

Update the LdapRegistry.xml file.

Log on to the application server as the ioc.user user. For example, log on as iocadmin.
Edit the LdapRegistry.xml file in the liberty_install_dir/usr/servers/liberty.instance.name directory, where liberty_install_dir is the WebSphere Application Server Liberty Profile installation directory and liberty.instance.name is the name of the Liberty instance. For example, edit the /opt/IBM/WebSphere/wlp/usr/servers/iocsvr1/LdapRegistry.xml file.

Modify the file with the correct values for the baseDN, host, bindDN, bindPassword, sslEnabled, and port attributes. For example:

<server description="LDAP registry configuration">
   <ldapRegistry realm="BasicRegistry"
	baseDN="ou=swg,o=abc,c=us" host="ldapserver.abc.com" port="389" ignoreCase="<true>"
      ldapType="IBM Tivoli Directory Server" 
	bindDN="cn=root" bindPassword="{xor}Lz4sLCgwlST=" 
	sslEnabled="false" searchTimeout="8m">
      <idsFilters groupMemberIdMap="groupOfUniqueNames:uniqueMember"
         userFilter="(&amp;(uid=%v)(objectclass=inetOrgPerson))" userIdMap="*:uid" groupFilter="(&amp;(cn=%v)(objectclass=groupOfUniqueNames))">
      </idsFilters>
      <contextPool enabled="true" initialSize="1" maxSize="0" preferredSize="3" timeout="0ms" waitTime="3000ms"/>
      <ldapCache>
         <attributesCache enabled="true" size="4000" sizeLimit="2000" timeout="1200ms"/>
         <searchResultsCache enabled="true" resultsSizeLimit="1000" size="2000" timeout="600ms"/>
      </ldapCache>
   </ldapRegistry>
</server>

Note: You can create an encrypted value for the bindPassword on the application server or on the analytics server with following command:

liberty_install_dir/bin/securityUtility encode passwrd

For example:

/opt/IBM/WebSphere/wlp/bin/securityUtility encode mybindpassword

Save your changes.

Update the user registry connection details in the server.xml file.
1. Edit the server.xml file in the liberty_install_dir/usr/servers/defaultServer directory. For example, edit the /opt/IBM/wlp/usr/servers/defaultServer/server.xml file.
2. Replace the <basicRegistry>...</basicRegistry> tags and all content between them with <include location="LdapRegistry.xml"/>
3. Save your changes.

As the ioc.user user, restart the server by running the following commands:

liberty_install_dir/bin/server stop liberty.instance.name
liberty_install_dir/bin/server start liberty.instance.name --clean

For example, run the following commands as the iocadmin user:

/opt/IBM/WebSphere/wlp/bin/server stop iocsvr1
/opt/IBM/WebSphere/wlp/bin/server start iocsvr1 --clean

To map user attributes to fields in LDAP, see the Mapping user attributes to fields in LDAP topic.
Repeat steps 2 - 5 on the analytics server.
Optional: If your LDAP server is configured to accept connections over Secure Sockets Layer (SSL), you can complete the following steps to configure SSL communication between IBM Intelligent Operations Center and your LDAP server.
1. Log on to the application server as the ioc.user user. For example, log on as iocadmin.
2. Run the following commands to extract the LDAP server certificate, where LDAP_host_name:port is the fully qualified host name and the SSL port number of your LDAP server:
```
su - ioc.user
cd liberty_install_dir/usr/servers/liberty.instance.name/resources/security
openssl s_client -showcerts -connect LDAP_host_name:port </dev/null 2>/dev/null | openssl x509 -outform PEM > LDAP_Server_cert.pem
```
  For example:
```
su - iocadmin
cd /opt/IBM/WebSphere/wlp/usr/servers/iocsvr1/resources/security
openssl s_client -showcerts -connect ldapserver.abc.com:636 </dev/null 2>/dev/null | openssl x509 -outform PEM > LDAP_Server_cert.pem
 
```
3. Run the following command to import the LDAP server certificates into WebSphere Application Server Liberty Profile, where keystore_password is the keystore password:
```
/opt/ibm/java-x86_64-80/jre/bin/keytool -import -keystore key.jks -alias LDAP_Server_cert\
 -file LDAP_Server1_cert.pem -storepass keystore_password -noprompt -trustcacerts
```
4. Edit the LdapRegistry.xml file in the liberty_install_dir/usr/servers/liberty.instance.name directory:
  - Set the sslEnabled attribute to "true".
  - Set port attribute to the SSL port number, for example, 636.
5. As the ioc.user user, restart the server by running the following commands:
```
liberty_install_dir/bin/server stop liberty.instance.name
liberty_install_dir/bin/server start liberty.instance.name --clean
```
  For example, run the following commands as the iocadmin user:
```
/opt/IBM/WebSphere/wlp/bin/server stop iocsvr1
/opt/IBM/WebSphere/wlp/bin/server start iocsvr1 --clean
```
6. Repeat steps a - e on the analytics server.

What to do next

If the password that is used by the solution to connect to the user registry expires or changes, see the Maintaining the LdapServerCredentials password topic for information about how to update the LdapServerCredentials system property.

Mapping user attributes to fields in LDAP
Each user of the solution has user attributes that can be edited using the Profile Settings view. If you want to retrieve values from your Lightweight Directory Access Protocol (LDAP) user registry for particular user attributes, rather than the solution database, you must map the attributes to fields in your LDAP user registry. Any changes that you make affect all users of the solution.
Maintaining the system properties for the LDAP credentials
The administrator is responsible for maintaining the passwords that are configured for the LdapServerCredentials and LdapServerQueryOnlyCredentials system properties. The LdapServerCredentials system property supports read/write access to the LDAP user registry and the LdapServerQueryOnlyCredentials system property supports read-only access. If the passwords that are used by the solution to connect to the user registry expires or changes, users cannot log on to the solution, which renders the system unusable. If this happens, you can recover by updating the value for each system property to reflect the correct password by using a DB2 command.
Configuring LDAP support for roles
You can define a role as a user group that has access to specific features of IBM Intelligent Operations Center. You can map multiple user groups to the role so that all the users in these groups have the same access to these features. To use roles, you must add the roles organizational unit to your LDAP user registry and configure the LdapRoleFilter system property. If your LDAP server is IBM Security Directory Server, configure the size of the group members cache to meet your requirements.
Configuring cache size for user groups and roles
If you are using IBM Security Directory Server for your LDAP user registry, configure the size of the group members cache to meet your requirements for the number of user groups and roles.

Parent topic: Securing the solution

Related tasks:

Configuring system properties