LDAP connection – file-based configuration

Concept 

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.

Reference

Configuration of an LDAP connection

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

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:

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"?>
      <LdapConfigurationDocument
        xmlns="http://www.phoenixcontact.com/schema/ldapconfiguration"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.phoenixcontact.com/schema/ldapconfiguration"
        schemaVersion="1.0">
       
      <LdapServer hostname="192.168.1.40" 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" />
          
          <GroupAttributes>
              <GroupAttribute name="memberOf" />
          </GroupAttributes>
       <GroupMappings>
              <GroupMapping ldapGroup="cn=plcAdmin,dc=example,dc=org" localRole="Admin" />
              <GroupMapping ldapGroup="cn=plcReader,dc=example,dc=org" localRole="Viewer" />
       </GroupMappings>
      </LdapServer>
              
      </LdapConfigurationDocument>

LDAPServer

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:
    "NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0:-SHA1:-SIGN-RSA-SHA1:-SIGN-ECDSA-SHA1:-RSA"
    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:
      "NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0:-SHA1:-SIGN-RSA-SHA1:-SIGN-ECDSA-SHA1"
    • Enable SHA-1 again:
      "NORMAL:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-DTLS1.0"
    • Enable the TLS 1.1 protocol version:
      "NORMAL:-VERS-TLS1.0:-VERS-DTLS1.0"
    • Enable the TLS 1.0 protocol version and use the "Normal" setting of gnutls:
      "NORMAL"
      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.