Connection to an LDAP server
Authentication via LDAP
In FirstSpirit you have the option of using an LDAP server to handle user authentication. A user is assigned a flag, which shows if he is or is not an external user. Different LDAP configurations (called “sections”) can be created and configured in FirstSpirit Server. An LDAP user is associated with one section only (see Edit user). Authentication can potentially take place three different ways:
- LDAP Bind: the name and password are sent to the LDAP server. The “Distinguished Name” (DN), i.e. the unique user identification key, must be known within the LDAP server. If the DN exists, the password passed is checked using the “Bind” operation. Example of using LDAP Bind
- LDAP Search & Bind: if the “Distinguished Name” (DN) of a user is unknown, you can search for it within a subtree of the LDAP server. A search filter and start node must be defined to do this. Example:
SEARCH.FILTER=(cn=$USER_LOGIN$)
SEARCH.BASE_DN=dc=mycompany,dc=com
This filter searches for all entries in the LDAP tree in which the attribute “cn” is the same as the login name entered. The start node is the node with the DN dc=mycompany,dc=com. If this type of node is found, a “Bind” is executed (see LDAP Bind). - LDAP Search & Compare: the function of this option is equivalent to option 2. However, after a matching node is found, no “Bind” operation is carried out. Instead, the password entered is compared to any LDAP attribute desired.
Example:
SEARCH.COMPARE.PASSWORD_ATTRIBUTE_NAME=mail
In this case, the password entered must match the content of the “mail” attribute of the LDAP node.
Once LDAP authentication is successful, the user is added to the FirstSpirit server as an external user if the user was previously unknown to the FirstSpirit system (see Adding users to the project). To do this, the configuration parameter JAAS.autoCreateUser must be configured to the value true (default setting, see General notes about the JAAS configuration). The external LDAP user login is automatically copied to FirstSpirit. The external LDAP user password, however, is cleared after it is successfully authenticated for the first time in FirstSpirit. Logins with an empty password are rejected by the FirstSpirit server. An external LDAP user can therefore only log in to the FirstSpirit server when the LDAP server is available during the login procedure. In the case of internal LDAP users, the password is retained in FirstSpirit. The user in this case can log in using the FirstSpirit password and the LDAP password.
The server administrator (login: “Admin”) has a special role for LDAP login. The user is created automatically when the FirstSpirit server is installed. The server administrator password is never cleared, regardless of whether the user has been configured as “external” or “internal”. It is therefore recommended that the server administrator password (initially “Admin”) be changed immediately after FirstSpirit Server has been installed.
Bind LDAP attributes to a FirstSpirit user
Besides pure authentication, it is possible to bind any LDAP attribute to the user attributes of a CMS user. To achieve this, set parameter LDAP.IMPORT_USER in configuration file fs-server.conf to TRUE.
Additionally allocate an attribute in fs-server.conf:
LDAP.IMPORT_USER.<cms-attribute>_ATTRIBUTE=<ldap-attribute->
All LDAP attributes defined in this manner are automatically imported during initial login of the respective user.
If several attributes from the LDAP server are to be mapped onto an attribute in FirstSpirit, separate the individual attributes via comma (,). Via the parameter
LDAP.MULTI_VALUE_SEPARATOR=[separator]
the separator can be defined which is to be used to separate the read out attribute values. Use for example the configuration
LDAP.MULTI_VALUE_SEPARATOR=:
LDAP.IMPORT_USER.NAME_ATTRIBUTE=givenName,sn
to output first and last name, divided by a colon.
The following CMS user attributes can be overwritten by LDAP attributes during login:
- User name: Name of the FirstSpirit user
- Email: Email address of the FirstSpirit user
- Telephone: Telephone number of the FirstSpirit user
- Initials: Initials of the FirstSpirit user
Use TLS or SSL
If the FirstSpirit Server is to connect the LDAP server via TLS/SSL, the certificate of the LDAP server has to be imported into the FirstSpirit keystore first. The Java tool keytool from the “bin” directory of the JDK is used for this task. If the certificate has a different format, it can be converted into the keytool importable PEM format via the external service program openssl. Example call for conversion:
openssl x509 -inform DER -in mycompany.der -outform PEM -out mycompany.crt
If the certificate is, e.g., located in file “mycompany.crt” and has previously been moved to the FirstSpirit Server installation directory, it can be imported into the keystore as follows:
keytool -import -file mycompany.crt -alias ldapserver.mydomain.net -keystore
conf/fs-truststore.jks -storepass changeit
Additionally enter the path and password of the keystore as Java parameters in fs-wrapper.conf:
wrapper.java.additional.X=-Djavax.net.ssl.trustStore=conf/fs-truststore.jks
wrapper.java.additional.X=-Djavax.net.ssl.trustStorePassword=changeit
 |
The following applies to all wrapper.java.additional.* parameters: only one Java parameter per line. All specified Java parameters have to contain consecutive, unique numbering (X). As long as the parameter wrapper.ignore_sequence_gaps is set to true the numbering need not to be consecutive. |
A self-signed certificate which is created as follows after changing to the FirstSpirit Server installation directory can be used for test installations:
keytool -genkey -alias ldapserver.mydomain.net -keyalg RSA -validity 1000 -
keystore conf/fs-keystore.jks -storepass changeit
If the “first and last name” are requested, the fully qualified host name (host name incl. domain) has to be specified.
After a FirstSpirit Server restart, communication to the LDAP server can take place via TLS or SSL.