LDAP connection – file-based configuration


The LDAP server enables central management of the users in a network (e.g. a Microsoft Active Directory). The PLCnext user authentication can be connected to an LDAP server. A central user management allows to manage user accounts, their passwords and group memberships at a central level. With an LDAP server there is no need to setup user accounts and passwords on every single controller.
The benefits are:

  • If a password change is necessary, it only needs to be changed once inside the LDAP directory and not in every controller.
  • New users can be added without the need of configuring every controller.
  • New user permissions and rights can be rolled out in a very simple way.
  • A blocked user affects the entire system and not only a single controller. 

The User Manager supports the TLS protocol for the connection to an LDAP server (LDAPS, LDAP with StartTLS). It supports the authentication of users against the LDAP server with user name and password by using the LDAP bind command. 

The LDAP authentication is performed in addition to the local user data base.  If the authentication is successful for one of the two sources, the authentication is considered successful. No further authentication is necessary. 

If the authentication fails because of a wrong or unknown user name or due to a communication error with the source, the authentication is continued with the next source. The local user database (managed via WBM) is always the first source. After this the LDAP servers are used in the configured order.

If one authentication fails because a wrong password was entered, the login fails and no further sources are used.

The User Manager validates the server certificate of the LDAP server. The validity check is made using a configurable TrustStore which is referenced by its name.


Configuration of an LDAP connection

In order to set up an LDAP connection, you need to create an XML configuration file as described below.

Be aware of the XML entities when editing XML configuration files: 
There are symbols in the XML code that cannot be represented as attribute values because they have a syntactical function.

For example, the characters < and > are used for opening and closing XML tags. To be able to use these characters as attribute values in their genuine meaning "less than" or "greater than", entities are required.

The following entities are predefined in the XML specification. Make sure to use these entities in attribute values to avoid XML parsing errors.

Character Entity
Ampersand (& &amp;
Single quote (') &apos;
Double quote (") &quot;
Less than (<) &lt;
Greater than (>) &gt;

Overview on configuration options

It is possible to configure up to 10 LDAP server connections. To set up a User Manager to LDAP connection you have the following configuration options:

Option Description Default Optional/Mandatory
LDAP host/IP DNS name or IP address of the LDAP server   Mandatory
Port TCP port of the LDAP server "389" Optional
timeout The network timeout after a connection attempt to the ldap server failed "10s" Optional
Enable TLS Activate/deactivate TLS "true" Optional
Use StartTLS Usage of StartTLS instead of TLS (this option only has an effect when TLS is activated) "true" Optional
TrustStore name Name of the Trust Store, that is used for verification. "ldap" Optional
cipherList List of permitted TLS cipher suites for the LDAP connection "NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0:-SHA1:-SIGN-RSA-SHA1:-SIGN-ECDSA-SHA1:-RSA" Optional
Base DN DN (Distinguished Name) where the LDAP search for users starts   Mandatory
Search filter LDAP filter that is used for the search for users.   Mandatory
Bind DN DN that is used for the bind before the search   Optional
Bind password Password for the "Bind DN"   Optional
Group attributes

List of LDAP attributes that save the group membership of a user, e. g. "memberof"

LdapGroup / Role Mapping Mapping configuration of LDAP groups to PLCnext roles   Optional


Configuration files

The configuration for the LDAP connection is set using XML configuration files. All of the important settings can be configured directly in the Ldap.config configuration file on the controller. To modify the configuration, the XML file can be edited using any editor. You will find the file in the /opt/plcnext/config/System/Um directory of your controller. The file system is accessed via the SFTP protocol. Use a suitable SFTP client software for this, e.g., WinSCP. 

Example of an LDAP configuration fileClick to see an example of an LDAP configuration file  

<?xml version="1.0" encoding="UTF-8"?>
      <LdapServer hostname="" port="389" order="1">
          <LdapSecurityOptions tlsEnabled="true" useStartTls="true"  trustStore="ldap" />
          <LdapSearchOptions baseDN="dc=example,dc=org" searchFilter="(uid=$$USER$$)" />
          <LdapLoginOptions bindDN="cn=admin,dc=example,dc=org" bindPassword="admin" />
              <GroupAttribute name="memberOf" />
              <GroupMapping ldapGroup="cn=plcAdmin,dc=example,dc=org" localRole="Admin" />
              <GroupMapping ldapGroup="cn=plcReader,dc=example,dc=org" localRole="Viewer" />

One configuration file can be filled with the configuration of up to 10 LDAP servers. Every server is configured with the element <LdapServer> and </LdapServer>. The element can be extended with the following attributes:

  • hostname
    Add the host name or the IP address of the LDAP server. This information is obligatory.
  • port
    The port is chosen automatically. Port 389 for connections without TLS or StartTLS and port 636 for TLS connections. If necessary you can specify the port where the LDAP server can be reached.
  • order
    The server entries are ordered according to the order number (int32) specified in this attribute. They are sorted and processed according to this order number for an authentication request.
  • timeout
    The network timeout after a connection attempt to the LDAP server failed. Enter a value with one of the following units:
    • ns (nanoseconds)
    • us (microseconds)
    • ms (milliseconds)
    • s (seconds)
    • h (hours)

The LdapServer element can contain the following XML elements for further configuration:

  • LdapSecurityOptions
    Settings for TLS. The following attributes can be used to specify the settings:
    • tlsEnabled: Activate (true) or deactivate (false) TLS for the LDAP server
    • useStartTls: Activate (true) or deactivate (false) the usage of StartTLS. When the usage of StartTLS is deactivated and TLS is activated, a direct TLS connection to the LDAP server is established. 
    • trustStore: Specifies the name of  the TrustStore for the verification of the LDAP server certificate. In case the name contains an empty string (""), the certificate verification is switched off, which means that the connection to the LDAP server is established without verifying its certificate. In case a TrustStore is empty, the verification process fails, which means that the connection to the LDAP server cannot be established at all. 
      Note: If a TrustStore is changed that is referenced by an LDAP server configuration (e.g. by adding certificates for LDAP), a restart must be performed. The changes only take effect after the restart.
    • cipherList
      The cipherList attribute configures allowed TLS cipher suites which are supported by the LDAP client to establish a TLS connection to the LDAP server. This setting is only enabled, if TLS or StartTLS is activated. The format must follow the rules of GnuTLS (click for more information on gnutls.org).
      A secure setting is established by default (can only be ensured with a current firmware version). The rules comply with the recommendations of the Technical Guideline on the use of TLS (TR-02102-2) by the German government institution "Federal Office for Information Security", with the following exceptions:
      Curve25519 is enabled, CHACHA20 and POLY1305 are allowed.
      The following cipherString is set by default with firmware version 2019.9 and 2020.0 LTS.
      This settings disable TLS versions 1.0 and 1.1 and disable the SHA-1 algorithm for HMAC, PRF and Signature, and disable RSA key exchange:
      Note: The default value can be subject to change in new firmware versions.  The setting will be updated if new recommendations are published.
      If connection issues with your LDAP server occur, consider to use a less secure configuration, e.g.:
      • Enable RSA Key Exchange again:
      • Enable SHA-1 again:
      • Enable the TLS 1.1 protocol version:
      • Enable the TLS 1.0 protocol version and use the "Normal" setting of gnutls:
        You might also want to restrict algorithms even further for example to comply with very specific security policies at a particular location.
  • LdapSearchOptions
    Settings for the user search in the LDAP server. The following attributes can be used to specify the settings:
    • baseDN: The LDAP DN (Distinguished name) that serves as starting point for the search for users over all child nodes. 
    • searchFilter: LDAP search filter that is used for the search for users. The variable "$$USER$$" is automatically replaced with the login.
  • LdapLoginOptions
    Login settings for the LDAP server. Before the user search can be performed, a authentication (bind) is required.
    • bindDN:
      Distinguished Name of the user the search in the LDAP directory is performed with.  
    • bindPassword:
      Password of the "bindDN" user in the LDAP server.
Direct bind to LDAP server without user search

You have the possibility to configure the LDAP server so that the search for the correct user is not performed in the LDAP. For this purpose a bind with the user name and password that is entered into the login mask is executed. The bind will be performed with the configured bindDN. The attribute contains the $$USER$$ placeholder which is replaced with the login and the password which was entered for the login.

In order to activate the direct bind, proceed as follows:

  • Add "$$USER$$" to the attribute bindDN.
    Example: bindDN="uid=$$USER$$,dc=example,dc=org"

As a result the settings baseDN, searchFilter and bindPassword will be ignored.


•  Web browser recommendation: Chrome/Edge 88 or newer, Firefox ESR 90 or neweror Safari • 
• Published/reviewed: 2022-09-14 • Revision 046 •