Documentation for Administrators

Different LDAP configurations (known as “sections”) can be created in FirstSpirit Server. The name of a section is defined by the entry in the fs-jaas.conf configuration file (see Login process configuration (fs-jaas.conf)). A section is configured in the fs-server.conf configuration file (LDAP area). The section name (from the fs-jaas.conf file) is specified before each configuration parameter. The section name must follow the “LDAP_n” format, where n is the section number that is numbered sequentially starting with 1. If only 1 LDAP section is used, the section can also be called “LDAP”.

LDAP_n.parameter=value

The names of the LDAP attributes are case sensitive and must be entered using the same case used in the LDAP directory.

To comment out the following parameters, an empty string must be specified as the value.

LDAP.IMPORT_USER.LOGIN_ATTRIBUTE=
LDAP.IMPORT_USER.NAME_ATTRIBUTE=
LDAP.IMPORT_USER.EMAIL_ATTRIBUTE=
LDAP.IMPORT_USER.PHONE_ATTRIBUTE=
LDAP.IMPORT_USER.ABBREVIATION_ATTRIBUTE=

Commenting out this parameter using # does not work, since in this case the default value is used.

“LDAP” was selected as the section name in the following example configuration for connecting to the LDAP server of the Microsoft Active Directory (using LDAP.AUTHENTICATION= SEARCH_BIND). Depending on the configuration of the fs-jaas.conf file (see Login process configuration (fs-jaas.conf)), other section names can also be selected, and many different LDAP sections can be defined at the same time.

LDAP.NAME=e-spirit.de
LDAP.HOST_URL=ldap://server1 ldap://server2 ldap://server3
LDAP.SSL=FALSE
LDAP.AUTHENTICATION=SEARCH_BIND
LDAP.SEARCH.BIND_DN=cn=ldapuser,cn=users,dc=e-spirit,dc=de
LDAP.SEARCH.BIND_PASSWORD=ldappassword
LDAP.SEARCH.BASE_DN=ou=mitarbeiter,ou=Dortmund,dc=e-spirit,dc=de
LDAP.SEARCH.FILTER=(sAMAccountName=$USER_LOGIN$)
LDAP.IMPORT_USER=TRUE
LDAP.IMPORT_USER.LOGIN_ATTRIBUTE=sAMAccountName
LDAP.IMPORT_USER.NAME_ATTRIBUTE=givenName,sn
LDAP.IMPORT_USER.EMAIL_ATTRIBUTE=mail
LDAP.IMPORT_USER.GROUP_ATTRIBUTE=memberof
LDAP.IMPORT_USER.PHONE_ATTRIBUTE=telephoneNumber
LDAP.IMPORT_USER.ABBREVIATION_ATTRIBUTE=initials

LDAP.NAME

Description of the corresponding LDAP section, e.g. the domain name. The description appears in the “Edit user” dialog (see User).

LDAP.HOST_URL

LDAP URL of the LDAP section in the format ldap://hostname (if LDAP.SSL=false) or ldaps://hostname (if LDAP.SSL=true).

Each section contains at least one entry for an LDAP server which provisions LDAP data. To improve fail-safe performance, you can register multiple LDAP servers that have to provide the same LDAP data.

LDAP.TIMEOUT

If a server fails or takes too long to answer (>30 seconds), timeouts may arise:

timeout during login to the root web application
timeout of the LDAP connection

The time span after which a timeout occurs may be increased via the parameters

web.login.timeout (see Configuration FirstSpirit WebApp) and
LDAP.TIMEOUT

Example: Configuration of timeout of the LDAP connection (default value: 30):

// connect and read timeout in seconds
LDAP.TIMEOUT=30

LDAP.SSL

The encrypted SSL transfer can be enabled (value: true) or disabled (value: false) here (see Use TLS or SSL).

LDAP.AUTHENTICATION

There are different server login options available. Possible values are:

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. BIND can only be used when the LDAP DNs of the user accounts are all inside the same LDAP folder. The example for the LDAP.BIND.DN parameter (see below) contains the folder with the DN
ou=Benutzer,ou=Dortmund,dc=e-spirit,dc=de.
If the user accounts are distributed across different folders, either SEARCH_BIND must be entered into the fs-server.conf file or a unique LDAP section must be entered into the fs-server.conf file for each of the user folders.
SEARCH_BIND: if the “Distinguished Name” (DN) of a user is unknown, or the user accounts are entered in different branches of the LDAP tree, you can search for it within a subtree of the LDAP server. A search filter must be defined to do this. Example:
SEARCH.FILTER=(uid=$USER_LOGIN$)
SEARCH.BASE_DN=ou=department,dc=mycompany,dc=com
This filter searches for all entries in the LDAP tree in which the “uid” attribute is the same as the login name entered. The start node is the node with the DN “ou=department,dc=mycompany,dc=com”. The login is successful as soon as a matching user account is found on the SEARCH.FILTER and the user password passed is correct.
SEARCH_COMPARE: the function of this option is equivalent to SEARCH_BIND; in this case, however, it is not the password attribute that is used for authentication, but rather any other LDAP attribute. Example:
SEARCH.COMPARE.PASSWORD_ATTRIBUTE_NAME=mail
In this case, the password entered must match the content of the “mail” attribute.

When using LDAP.AUTHENTICATION=SEARCH_BIND or LDAP.AUTHENTICATION=SEARCH_COMPARE, it is usually necessary to provide entries for LDAP.SEARCH.BIND_DN and LDAP.SEARCH.BIND_PASSWORD (see below). Entry is not required if the LDAP server can be queried without authentication. However, this actually does not occur in production environments.

LDAP.BIND.DN

DN of the user accounts that can be used to log onto FirstSpirit. This parameter is only useful in conjunction with LDAP.AUTHENTICATION=BIND. $USER_LOGIN$ is entered as a placeholder for the FirstSpirit user name. Example:

LDAP_1.BIND.DN=cn=$USER_LOGIN$,ou=Dortmund,dc=e-spirit,dc=de

Complete configuration example using LDAP.AUTHENTICATION=BIND for Active Directory:

LDAP_1.NAME=e-Spirit
LDAP_1.HOST_URL=ldap://ldapserver1 ldap://ldapserver2
LDAP_1.SSL=FALSE
LDAP_1.AUTHENTICATION=BIND
LDAP_1.BIND.DN=cn=$USER_LOGIN$,ou=Benutzer,ou=Dortmund,dc=e-spirit,dc=de
LDAP_1.IMPORT_USER=TRUE
LDAP_1.IMPORT_USER.LOGIN_ATTRIBUTE=sAMAccountName
LDAP_1.IMPORT_USER.NAME_ATTRIBUTE=displayName
LDAP_1.IMPORT_USER.EMAIL_ATTRIBUTE=mail
LDAP_1.IMPORT_USER.GROUP_ATTRIBUTE=memberof
LDAP_1.IMPORT_USER.PHONE_ATTRIBUTE=telephoneNumber
LDAP_1.IMPORT_USER.ABBREVIATION_ATTRIBUTE=initials

LDAP.SEARCH.BIND_DN

LDAP DN of a technical user account used to search the LDAP server in order to find a DN of a FirstSpirit user who is to be logged in. The technical user account requires read access to all LDAP attributes of the editor's user accounts, with the exception of the password attribute. The editor's user accounts do not require read access to their LDAP attributes.

LDAP.SEARCH.BIND_PASSWORD

Password for LDAP DB of the technical user account used for SEARCH.BIND_DN.

LDAP.SEARCH.BASE_DN

The parameter defines the start node of the search for the LDAP DN of the FirstSpirit user to be logged in.

LDAP.SEARCH.FILTER

this parameter is used to define a search filter. The filter:

SEARCH.FILTER=(cn=$USER_LOGIN$)

Searches, for instance, for all entries in the LDAP tree in which the attribute “cn” is the same as the login name entered in FirstSpirit. The start node is the DN specified for SEARCH.BASE_DN.

LDAP.IMPORT_USER

In addition to strict authentication, it is possible to import any LDAP attributes into the user attributes of a CMS user. To do this, the value of the parameter LDAP.IMPORT_USER must be set to TRUE.

LDAP.IMPORT_USER.LOGIN_ATTRIBUTE

This assignment imports the login name of an LDAP user for a FirstSpirit user. The LDAP name assigned here is imported automatically after the particular user logs in for the first time. The Active Directory attribute sAMAaccountName is usually not unique across all domains if multiple LDAP sections (LDAP_1, LDAP_2, …) are present, i.e. users may be authenticated against multiple user domains. The complete attribute userPrincipalName, which includes account as well as domain names, should be used here.
If an invalid value is specified for this parameter (e.g. LDAP attribute returns an “void” value, invalid LDAP attribute, etc.), this is logged in the server log file as follows:

INFO  17.05.2010 14:50:24.102 
(de.espirit.firstspirit.server.usermanagement.LDAPAuthentication): 
[LDAP] ignoring empty LOGIN_ATTRIBUTE value!

LDAP.IMPORT_USER.NAME_ATTRIBUTE

This assignment imports the user name of an LDAP user for a CMS user. The LDAP name assigned here is imported automatically after the particular user logs in for the first time.

LDAP.IMPORT_USER.EMAIL_ATTRIBUTE

This assignment imports the e-mail address of an LDAP user for a CMS user. The LDAP e-mail address assigned here is imported automatically when the particular user logs in for the first time.

LDAP.IMPORT_USER.GROUP_ATTRIBUTE

The LDAP group attribute allows a user to assign a particular FirstSpirit group of a FirstSpirit project automatically using his or her group membership in LDAP.
The name of the LDAP attribute is specified which contains the LDAP DNs of the LDAP groups in which the particular user is a member. The attribute is read out again each time the user logs in so that the group membership can be imported into FirstSpirit. All externally marked FirstSpirit groups are assigned to the user account and have an “external name” assigned in FirstSpirit that matches the LDAP DN of the LDAP group. Instead of an LDAP DN, any string can be used; however, the LDAP server typically maps group membership via DNs.

LDAP.IMPORT_USER.PHONE_ATTRIBUTE

This assignment links the phone number of an LDAP user to a CMS user. The LDAP phone number assigned here is imported automatically the first time the particular user logs in.

LDAP.IMPORT_USER.ABBREVIATION_ATTRIBUTE

This assignment links the abbreviated name of an LDAP user to a CMS user. The LDAP abbreviation assigned here is imported automatically the first time the particular user logs in.

For additional information on connecting an LDAP server, see Connection LDAP server.

Print version | Page start