Configuring the Active Directory settings

You can configure Rational® Test Control Panel to use the Active Directory security model by using Installation Manager during installation or by using the Modify option after the installation. You can also specify the settings by manually editing the security.config file.

Creating multiple Active Directory configurations

When you enable Rational® Test Control Panel to use the Active Directory, you can have multiple configurations by setting the configuration countproperty on the Installation Manager GUI. Each configuration can point to a different Active Directory domain (optionally, on a different Active Directory server).
Note: The Active Directory domains are completely different from the Rational® Test Control Panel domains.

When you configure the Active Directory security model by editing the security.config file, a second configuration is added by appending .1 to the end of each property name, .2 for the third configuration, and so on. For example, if url is the property that sets the URL for the first configuration, url.1 sets it for the second, url.2 for the third, and so on.

Specifying user names at logins

While logging in to Rational® Test Control Panel, specify only your username if you are part of the first configuration (Active Directory domain). For all the other configurations, specify your username in the following format: domain\username.

Setting up Active Directory domains

  • All configurations must have the domain property set; otherwise, they will not be used. If the properties are omitted from the additional configurations, they default to the value that is set in the first configuration.

  • Each Active Directory configuration must be for a specific Active Directory domain that holds a unique name amongst a set of Active Directory domains with which Rational® Test Control Panel is configured. The requirement holds true even if the Active Directory domains are on different servers. For example, you cannot have two configurations for a single Active Directory domain called DOMAIN that are on different servers or on the same server with different values set for the other properties.

Editing the security.config file

The security.config file is found in the security folder in the Rational® Test Control Panel workspace.
  • On Windows™ systems, the folder is typically at C:\IBM\RTCP-Workspace\security.
  • On Unix-like systems, the folder is typically at /var/rtcphqs/security.
Keep in mind the following guidelines while editing the security.config file:
  • If the backslash character \ needs to be used in any property value, escape it with another backslash character: \\. For example, if the value is C:\IBM, specify it as C:\\IBM.
  • Optional: If any of the characters =, :, #, or ! is used in a property value, escape it with a backslash.
  • Set the credentialsStore property to ACTIVEDIRECTORY. Unlike the other properties, you need to set this property only once and you cannot modify it for individual configurations (AD domains).
Property Description
Name in the Installation Manager GUI Name in the security.config file
url url Address of the Active Directory host. For example, ldap://host_name:port.
admin user adminuser An Active Directory user with group query permissions. This is the user account that Rational® Test Control Panel uses to log in to the Active Directory server to determine the groups to which a particular user account belongs. In the security.config file, specify this property in the following format: username@domain, where domain is the admin domain.
password adminpassword The password for the admin user. This is stored in the security.config file in an obfuscated form. To keep this password secure, restrict the access to the security.config file. Only the user account under which Rational® Test Control Panel will run, and those users of the host computer who are trusted to edit it need access to it. If you are editing the security.config file, ensure that you encrypt the password. For details, see Configuring the security settings after installation by updating the security.config file. For example, adminpassword=#com.ghc.1!b2b312954AC84469E34BA2E5.
admin domain NA The domain to which the admin user belongs. This value is required for logging in as the admin user to get the information about groups. In the security.config file, this is specified as part of the adminuser property in the format username@domain.
default domain domain The domain to which the users belong. Typically, this is the same as the admin domain.
group search base searchBase The base location where the directory group searches should begin - for example, dc=mycompany,dc=local. This value is a Distinguished Name (DN) for an Active Directory object that contains all groups to be used to control the roles within Rational® Test Control Panel.

For example, if you have groups named cn=employees,ou=myTeam,o=mycompany,dc=mycompany,dc=local and cn=employees,ou=yourOrg,o=mycompany,dc=mycompany,dc=local, set the group search base to either o=mycompany,dc=mycompany,dc=local or dc=mycompany,dc=local. Specifying ou=myTeam,o=mycompany,dc=mycompany,dc=local finds only the first group, and specifying ou=yourOrg,o=mycompany,dc=mycompany,dc=local finds only the second.

Specifying a more specific (longer) group search-base narrows down the list of groups to select from in the Installation Manager GUI for assigning roles to groups, and could marginally speed up certain operations. Specifying a less specific (shorter) group search base will make more groups available for assigning roles.
user search base userSearchBase This is a Distinguished Name (DN) for an Active Directory object that contains all users who need to log in at any level. It is not necessary that they are immediate child objects.

For example, if you have two organizations in your server, one represented by ou=myOrg,o=mycompany,dc=mycompany,dc=local, and the other, by ou=yourOrg,o=mycompany,dc=mycompany,dc=local, and you want the first organization's members alone to be able to log in, set the user search base to ou=myOrg,o=mycompany,dc=mycompany,dc=local. If members from both the organizations should be able to log in, set it to o=mycompany,dc=mycompany,dc=local.

For a user to be able to log in, they must match the user search base and they must be in an Active Directory group that has been assigned the role user.
group filter allGroupsFilter The filter expression for user groups. The default expression (objectClass=group) returns all groups. Use this property to control the number of groups available, to which the roles are assigned.
Directory Groups and Rational® Test Control Panel Roles groupMappings In the Installation Manager GUI, drag groups on to roles to create mappings and drag them off to remove. All users in a group assume roles that are assigned to that group.
For users to be able to log in, the following conditions must be met:
  • The user name must match the user search base and be in an Active Directory group that has been assigned the role user.
  • Users that have the role admin must also be in a group that is assigned the role user. Hence, you must assign user role to all the groups to which you assign the admin role.
The groupMappings property in the security.config file holds a comma-separated list of group=role pairs. The group is identified by its CN Active Directory attribute value.
Sample: security.config file with Active Directory settings for a single domain
credentialsStore=ACTIVEDIRECTORY
url=ldap\://ad.mycompany.example.com
adminuser=admin@DOMAIN1
adminpassword=#com.ghc.1!b2b312954AC84469E34BA2E5
domain=DOMAIN1
searchBase=OU\=Testing,DC\=DOMAIN1,DC\=domain
userSearchBase=DC\=DOMAIN1,DC\=domain
allGroupsFilter=(objectClass\=group)
groupMappings=MyCompanyEmployees\=user,MyCompanySysadmins\=admin,MyCompanySysadmins\=user,
Sample: security.config file with Active Directory settings for two domains
credentialsStore=ACTIVEDIRECTORY
url=ldap\://ad.mycompany.example.com
adminuser=admin@DOMAIN1
adminpassword=#com.ghc.1!b2b312954AC84469E34BA2E5
domain=DOMAIN1
searchBase=OU\=Testing,DC\=DOMAIN1,DC\=domain
userSearchBase=DC\=DOMAIN1,DC\=domain
allGroupsFilter=(objectClass\=group)
groupMappings=MyCompanyEmployees\=user,MyCompanySysadmins\=admin,MyCompanySysadmins\=user,
url.1=ldap\://ad.mycompany.example.com
adminuser.1=admin@DOMAIN2
adminpassword.1=#com.ghc.1!b2b312954AC84469E34BA2E5
domain.1=DOMAIN2
searchBase.1=OU\=Testing,DC\=DOMAIN2,DC\=domain
userSearchBase.1=DC\=DOMAIN2,DC\=domain
allGroupsFilter.1=(objectClass\=group)
groupMappings.1=MyCompanyEmployees\=user,MyCompanySysadmins\=admin,MyCompanySysadmins\=user,
Sample: security.config file with minimal Active Directory settings for two domains that share the same admin user and groups
credentialsStore=ACTIVEDIRECTORY
url=ldap\://ad.mycompany.example.com
adminuser=admin@DOMAIN1
adminpassword=#com.ghc.1!b2b312954AC84469E34BA2E5
domain=DOMAIN1
searchBase=OU\=Testing,DC\=DOMAIN1,DC\=domain
userSearchBase=DC\=DOMAIN1,DC\=domain
allGroupsFilter=(objectClass\=group)
groupMappings=MyCompanyEmployees\=user,MyCompanySysadmins\=admin,MyCompanySysadmins\=user,
domain.1=DOMAIN2