Introduction / FirstSpirit Server configuration / Connecting LDAP server

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:

  1. 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
  2. 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:
    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).
  3. 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.
    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:


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


the separator can be defined which is to be used to separate the read out attribute values. Use for example the configuration


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 -keystore 
conf/fs-truststore.jks –storepass changeit

Additionally enter the path and password of the keystore as Java parameters in fs-wrapper.conf:
Important The following applies to all* 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 -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.

© 2005 - 2023 Crownpeak Technology GmbH | All rights reserved. | FirstSpirit 2023.2 | Data privacy