CentraSite and LDAP
1 Introduction
CentraSite offers two mechanisms for user authentication namely 'internal' and LDAP. Per default CentraSite uses internal authentication, but most customer scenarios require LDAP. Internal being the authentication method in place for a freshly installed CentraSite means that login is possible with user 'INTERNAL\Administrator' (password 'manage') or 'Administrator' only because INTERNAL is the default domain.
In the following we will configure CentraSite to authenticate against different LDAP repositories. We start with a very simple configuration and continue with configurations using a technical user and/or SSL.The simple repository in our first example contains sailors in a domain named 'sevenSeas'. The screenshot shows the repository as browsed with the Apache Directory Studio. The samples are run with CentraSite in version 10.1.
CentraSite maintains information about each kind of user repository in authentication configurations, also referred to as domains. An authentication configuration specifies the type of user repository to be used and any parameters that are required to configure the user repository.
Maintaining configurations is done either via Command Central or via the CentraSiteCommand utility's 'set Authentication' command. Within here we will use the latter.
Open a command prompt, go to the install directory's 'CentraSite/utilities' folder. 'CentraSiteCommand set Authentication' without any further parameters shows the syntax of the command. Adding '-domain' plus a domain-name to the call creates or modifies a configuration depending on whether a configuration with the respective name yet exists. Since the utility later on updates files that may only be modifiable by administrators, the command prompt should be started as an administrator user.
2 Simple LDAP Configuration
To configure CentraSite to base its authentication upon an LDAP, a respective configuration needs to be created. This is done via 'CentraSiteCommand set Authentication -domain <domain-name>'. The domain-name is the name of the domain to-be. It should not be 'INTERNAL' and it should be the same as the LDAP entry the configuration will correspond to which in our case is 'sevenSeas'. So the command to establish the new authentification is 'CentraSiteCommand set Authentication -domain sevenSeas'.
Creating a configuration that allows CentraSite authentication to be based on LDAP is done in seven steps, namely server configuration (1), specify how to identify the users (2) and the groups (3), which attributes are relevant for users (4) and groups (5), how the relationship between users and groups is manifested (6), and whether the configuration should be saved (7). At the end of a step, the user input gets validated to ensure that the input is in accordance with the respective LDAP server's settings.
During the first step (server configuration), four questions are asked. The first question is whether the configuration should be enabled at once. The default here is Y(es). N(o) only makes sense if the configuraion is to be created but to be activated later. The next input is the LDAP server's URL starting with 'ldap://' or 'ldaps://' if SSL is used. The suggested Connection Timeout of 5000 milliseconds should be ok in most cases. For this simple scenario we do not need a technical user. The input is validated, i.e. the utility tries to access the specified LDAP server.
In the second step the system learns how users are represented in the LDAP repository. This is firstly, which attribute is the one identifying the user. This is often 'cn' ( = common name) as suggested, but in our case it is 'uid' ( = unique id). The second question asks where the users are located. The path starts with the domain node. Here this is a 'ou' ( = organizational unit) 'people' placed directly below the domain which is 'o' ( = organization) 'sevenSeas'. The third question asks for the respective node's object class. Two more entries, namely a uid and a password of a user, need to be provided to verify that the settings idetify users properly. Note that when specifiying an LDAP domain as such the password must be known for at least one of the users.
The third step is about defining how the attributes CentraSite can store for a user are to be filled from values stored in LDAP. The left side subsequently lists all CentraSite attributes and asks for the LDAP fields these should be filled from (if any). For our purpose it suffices to specify 'description: description' and leave the remaining field mappings empty. After all fields are dealt with, again the input gets validated. The utility asks for a user and provides the respective values (description only in our case).
For the fourth step, telling CentraSite how the groups are obtained, we'll have a look at our LDAP. The users are sorted into crews which again are listed below groups. The identifying attribute for crews is cn (the default), the Group Root DN is (from right to left) from the domain to the 'groups' sub-node to 'crews', and object class is 'groupOfUniqueNames'. We choose the crew cn = HMS SAG to validate.
As attribute mapping for groups it usually suffices to just specify that the decription is taken from the LDAP to CentraSite. Same as with users, a group Id is asked to validate the mapping.
The group resolution, dealt with in step no. six, is the means by which the LDAP establishes the relationship between users and the groups they belong to. In our case the relationship is from the group towards the user and thus the answer to the first question is y(es). The attribute pointing to the user is 'uniqueMember'. The depth parameter tells, how far upwards in the group hirarchie a membership should be recognized. The default here is '0', i.e. a user is only a member of those groups that point directly to the user. We select '2', i.e. the user is also considered as a member of super- and super-super-groups of the ones that point to the user.
The seventh and last step asks whether the configuration shall be saved. Answering n(o) leaves no footprint. Answering y(es) saves the configuration which manifests in the CentraSite installation's jaas.config file and properties folder.
3 Using the Configuration
Having saved the new authentication configuration, the CentraSite installation is modified accordingly.
A new authentication configuration is represented by two things in the installation. Firstly a new login module is entered in the jaas.config file's 'CentraSite' element. The jaas.config file can be found in the install-dir's 'profiles/CTP/configuration' folder.
In addition to the modifications in jaas.config, three files representing the new means of access are added to the sub-folder 'com.softwareag.platform.config.propsloader' also below 'profiles/CTP/configuration'. These files contain general connection information, group-mapping and user-mapping information respectively.
Note that in case of previous authentication configuration actions, already existing files may be modified. This especially means that any configuration settings entered previously either by tools or manually might be overwritten.
To enable CentraSite to base its authentication mechanism to the newly created authentication configuration, a first user needs to be introduced to CentraSite to allow LDAP access. In version 10.1 this is done using CentraSite Control. In more recent versions this is also possible via a new CentraSiteCommand action, namely 'CentraSiteCommand add Admin'.
Open CentraSiteControl and login using the yet existing, internal, authentication, i.e. INTERNAL\Administrator. From the main menu choose Administration > Users > Users.
In the Users listing click the 'Add User' button in the left upper corner. In the 'Add User' panel, click on 'Associate ...' on the right, to define the association of the to-be-defined CentraSite user with the user defined in the sevenSeas LDAP domain.
In the 'Associate User' pop-up, enter the qualified user name in the field next to 'Type Domain User'. In our case this would be sevenSeas\user-id using a known user in the LDAP domain sevenSeas. Pressing 'OK' goes back to the 'Add User' panel. The new user can be saved after having provided the necessary fields, i.e. first name and last name.
To check the new user log off from Control and subsequently log in using the new, qualified, user-id. As long as the default domain is still INTERNAL, users belonging to the domain sevenSeas must be specified in a qualified way. This can be changed by declaring the sevenSeas domain to be the default domain. Also, when logging on to Control using the new sevenSeas user, Control will not offer all the menu items it offered to INTERNAL\Administrator. This is due to the fact that no roles allowing for further actions are yet granted to the new user.
More users from the sevenSeas domain can now be added via bulk loading. For this again log in as INTERNAL\Administrator and give the CentraSite Administrator role to the new LDAP user. Role assignments are possible both in CentraSite Control as in the Business UI. Mark though that in the BusinessUI, user management is available per organization. Click the 'Organizations' menu item and select the respective organization from the listing.
Then log in to Control with this new user and go to the 'Add User' panel via Administration > Users > Users. There click on the button for bulk user loading. When clicking on 'Search' in the bulk user loading pop-up without further changes, all users in the LDAP domain are presented for selection.
4 Utilizing a Technical User
In cases where LDAP is not configured for anonymous access CentraSite needs to know about a user that has sufficient privileges to read all that is necessary about the users and groups in the respective domains. Such a user is called a technical user (also referred to as technical principal) since it does often not correspond to a real person. This user may hang directly below the uppermost node above all other users. The technical user's password must be known to the CentraSite administrator.
In the following we will configure CentraSite to use a domain 'sag' whilst utilizing a technical user 'admin' to gain access. As explained previously we start with 'CentraSiteCommand set Authentication -domain sag'. After having provided the proper LDAP URL the question whether a technical user is to be used needs to be ansered with (y)es. Afterwards provide the path to the technical user and its password. The remaining procedure (configuration of users and groups and their relationship) remains the same.
Looking at the effect the new configuration has upon the installation, the jaas.config file is in no way different than for configurations without a technical user. The difference is solely in the properties file 'com.softwareag.security.ldap.server.pid-<domain-name>' where there is, of cause, a change in the setting about whether a principal is used (noPrinIsAnonymous=false) and an additional line for the principal's identification (prin=uid\=admin,ou\=system).
5 Using LDAP over SSL
In case the LDAP repository is itself secured by means of SSL, certificates must be in place to allow access from both the CentraSiteCommand tool for configuration, as well as from a running CentraSite for verification. Thus when entering an LDAP server URL starting with "ldaps" the set authentication command asks additional questions concerning the truststore and the keystore to use. The keystore needs to contain a certificate that the LDAP server recognizes as an allowance to access and the truststore needs to contain a certificate that allows the CentraSite to listen to what the LDAP server has to say.
The truststore keeps the certificates that are accepted when accessing the LDAP server. One option here is to start with the truststore in the CentraSite installation tree under com.softwareag.platform.config.propsloader. Another starting point is the cacerts file of the JVM (<install-dir>/jvm/jvm/jre/lib/security/cacerts). The truststore needs to contain a certificate that allows to trust the LDAP server.
The keystore contains the certificates that the command line tool uses to access the LDAP server. A suitable keystore may be created using a tool as Keystore Eplorer. Another option here is again the cacerts file. The keystore needs to contain a certificate that allows to access the LDAP server.
For demonstration we here choose the cacerts file as both trust- and keystore after having added a certificate from the LDAP server using the keystore explorer downloaded from https://keystore-explorer.org/. In customer scenarios there are usually trust- and keystores in place that rule the security surroundings for the customer's internal and external communication.
So, when undertaking step 1 (server configuration) of the 'set authentication' command additional questions are asked concerning the trust- and keystore to be used when dealing with SSL-secured LDAP servers. The rest of the set authentication procedure remains the same.
The effect of the SSL-enabled LDA access upon the installation tree is just a slightly bigger 'com.softwareag.security.ldap.server.pid-<domain-name>' file (below 'com.softwareag.platform.config.propsloader'). In addition to the lines described above it contains the URLs, types and passwords of the respective trust- and keystore. The passwords are not provided literally but as pointers into a password maintaining device also being part of the CentraSite installation.
