LDAP Guide

User Guide
LDAP Guide
Distech Controls, Inc.
Brossard, Quebec,
Canada
Legal Notice
©, Distech Controls Inc., 2020. All rights reserved. While all efforts have been made to verify the accuracy of in-
formation in this manual, Distech Controls is not responsible for damages or claims arising from the use of this
manual. Persons using this manual are assumed to be trained HVAC professionals and are responsible for us-
ing the correct wiring procedures, correct override methods for equipment control and maintaining safe working
conditions in fail-safe environments. Distech Controls reserves the right to change, delete or add to the informa-
tion in this manual at any time without notice.
Distech Controls, the Distech Controls logo, EC-Net, and Innovative Solutions for Greener Buildings are regis-
tered trademarks of Distech Controls, Inc. LON, LonMark, LonWorks, LNS, and Neuron are registered trade-
marks of Echelon Corporation registered in the United States and other countries. NiagaraAX and NiagaraAX
Framework are registered trademarks of Tridium, Inc. BACnet is a registered trademark of ASHRAE. Windows,
Windows XP, Windows Vista, Windows 7, Visual Basic.Net, Visual Basic.Net are registered trademarks of Mi-
crosoft Corporation. Intel and Pentium are registered trademark of Intel Corporation in the U.S. and/or other
countries. AMD is a registered trademark of Advanced Micro Devices, Inc. EnOcean is a registered trademark
of EnOcean GmbH. All other trademarks are property of their respective owners.
Contents
About this guide .................................................................................................5
Document change log .................................................................................5
Related documentation ...............................................................................5

Chapter 1 Setup and configuration...................................................................7

Prerequisites ..............................................................................................7
FAQs .........................................................................................................8
Setting up the authentication scheme ...........................................................9
Setting up user prototypes .........................................................................10
Setting up local users ................................................................................10
Setting up a client PC for Kerberos............................................................. 11
Setting up access to the Key Distribution Center .........................................13
Making sure you can connect using a browser ............................................13
Configuring Firefox .........................................................................13
Configuring Internet Explorer ...........................................................14
Configuring Chrome security ...........................................................15
Configuring Chrome registry keys ....................................................15
Configuring a Kerberos master-slave server ...............................................16

Chapter 2 Introduction to LDAP......................................................................17

LDAP implementations..............................................................................17
How LDAP benefits EC-Net .......................................................................17
Local vs LDAP users .................................................................................18
Configuration properties and LDAP user attributes ......................................18
Automatic new user creation......................................................................19
Kerberos and the single-sign-on feature .....................................................19
Logging in with Kerberos credentials ..........................................................19
Using a browser and Kerberos to log in with a single sign on ........................20
Using a browser and only LDAP credentials to log in ...................................20
Chapter 3 Components...................................................................................21
baja-AuthenticationService ........................................................................21
baja-UserPrototype...................................................................................21
baja-UserService ......................................................................................23
ldap-BasicKrb5ConfEditor .........................................................................29
ldap-AdvancedKrb5ConfEditor ..................................................................30
ldap-LdapScheme ....................................................................................30
ldap-KerberosAuthenticationScheme .........................................................33
Glossary ...........................................................................................................37

Index.................................................................................................................39

October 10, 2018 3

Contents LDAP Guide

4 October 10, 2018

About this guide
This topic contains important information about the purpose, content, context, and intended audience for this
document.
Product documentation
This document is part of the EC-NetTM technical documentation library. Released versions of EC-Net software
include a complete collection of technical information that is provided in both online help and PDF format. The
information in this document is written primarily for Systems Integrators. In order to make the most of the infor-
mation in this book, readers should have some training or previous experience with EC-NetTM 4 or EC-NetAXTM
software.
Document content
LDAP (Lightweight Directory Access Protocol) manages user authentication using a database stored on a sep-
arate server. This guide introduces LDAP user authentication in the context of the EC-Net Network.

Document change log

This topic summarizes changes and additions made to this document.
October 10, 2018
In the “Plugins and Components” chapter, added the topic “baja-UserPrototype”.
August 9, 2017
In the topic baja-UserService, added the description about “Effect of property changes on user session”

Related documentation
This topic lists the other documents that relate to the information contained in this guide.
• User authentication, FoxService, and WebService are documented in the Station Security Guide.

October 10, 2018 5

 LDAP Guide

6 October 10, 2018

Chapter 1 Setup and configuration
Topics covered in this chapter
♦ Prerequisites
♦ FAQs
♦ Setting up the authentication scheme
♦ Setting up user prototypes
♦ Setting up local users
♦ Setting up a client PC for Kerberos
♦ Setting up access to the Key Distribution Center
♦ Making sure you can connect using a browser
♦ Configuring a Kerberos master-slave server

The AuthenticationService manages all LDAP authentication requests. The types of authentication a station
supports, in this case LDAP, are determined solely by this service. The most important element in LDAP au-
thentication is the LDAP authentication scheme. A station supports multiple schemes, with each user account
tied to a specific scheme.
Use this checklist to guide the setup and configuration process:
• All prerequisites fulfilled. See Prerequisites, page 7.
• LDAP authentication scheme selected and properties configured. See Setting up the authentication
scheme, page 9.
• User prototypes set up. See Setting up user prototypes, page 10.
• Local super user and service users set up. See Setting up local users, page 10.
• If you are using the KerberosScheme, PC client configured for Kerberos. See Setting up a client PC for
Kerberos, page 11.
• Each host configured to access the Key Distribution Center. See Setting up access to the Key Distribution
Center, page 13.
• Connection using a browser confirmed. See Making sure you can connect using a browser, page 13.
• Browser configured for LDAP support.

Prerequisites
Before you can configure your hosts for LDAP authentication your stations need to be licensed, you need to col-
lect information from your LDAP and Kerberos administrators, as well as provide information to your LDAP
administrator.
Licensing
Each EC-Net platform (Supervisor and EC-BOS) must be licensed for LDAP user services.
• The LDAPv2-compatible authentication scheme does not require host licensing. This is effectively the same
LDAP authentication scheme provided since EC-Net 4. They do not offer Kerberos as an authentication
choice.
• To use Kerberos authentication, your host platform must be licensed for LDAPv3. The following is an exam-
ple of the license line:
<feature name=”ldapv3” expiration=”never” kerberos=”true” parts=”LDAPV3_PART”/>

October 10, 2018 7

Chapter 1 Setup and configuration LDAP Guide

LDAP environment and properties

Each EC-Net host (Supervisor and controller) must be on a network with an existing LDAP server. The server
must support LDAPv2 or later.
You need at least the following information from your LDAP system administrator:
• URL for the LDAP server (ldap://your.domain.net:nnn where your.domain.net:nnn is the URL for
the LDAP server, and nnn is any port other than the standard, default LDAP port. To use a standard port
(389, or 636 if you are using SSL/TLS), you do not need to include the port in the URL.
• User names for logging in to each station as they appear in the LDAP directory.
Information your LDAP system administrator may need from you
• The name of the user prototype (group) to associate with each user (such as, manager, operator, etc.).
• Your name for each station.
Kerberos prerequisites
You need the following information from your Kerberos administrator:
• Kerberos realm name (should be in UPPERCASE).
• Key Distribution Center URL.
• A service name (based on the station name you provided) for each station. This URL-style name must be
set up by your Kerberos administrator on the LDAP server. This name should be in the form:
http/somename.domain.com
where somename is the name by which you will access your station via a browser, and domain.com is your
realm.
This name must be trusted for delegation. If you are not planning for Kerberos authentication via the brows-
er, you can use a regular user name (not a service).
• A keytab file or a password for each service name (station). Services typically require a keytab file, whereas
users typically use a password.

FAQs
Use these questions and answers to broaden your understanding of LDAP and EC-Net.
Q: Can I use SSL/TLS with LDAP?
A: Yes, in fact, you should configure all platforms and stations for TLS (Transport Layer Security). Refer to the
Station Security Guide.
Q: Can a system use a combination of LDAP or Active Directory along with the network user feature in
a NiagaraNetwork?
A: No. the EC-Net network-user feature is incompatible with LDAP (and no hybrid system is supported). All cen-
tralized user management is provided by the LDAP server. Local station users, which are unique to each sta-
tion, are supported.
Q: Is Kerberos always associated with LDAP in EC-Net?
A: Kerberos is an available authentication scheme for LDAPv3.
Q: Can a station support an older LDAPv2 level server or Active Directory using the newer LDAPv3–
compatible LDAP schemes?
Yes. These schemes are backwards-compatible with LDAPv2-based systems. However, Kerberos authentica-
tion is not available.
Q: Can I configure my stations to run in FIPS mode (FIPS 140-2) and also use LDAPv3 with Kerberos
authentication?

8 October 10, 2018

LDAP Guide Chapter 1 Setup and configuration

A: No. When running in FIPS mode, the set of permitted cryptographic algorithms is smaller—only algorithms
that are FIPS-approved may be used. Due to this restriction, Kerberos cannot be used when running in FIPS
mode, as the algorithms it requires are not supported by the FIPS cryptographic provider.

Setting up the authentication scheme

The LDAP scheme defines the properties that are unique to LDAP authentication.
Prerequisites: You are working on a computer using a secure connection to the network. You have opened
EC-Net 4 Pro
Step 1 Open the ldap palette.
Step 2 Drag an LDAP scheme (LdapScheme or KerberosScheme) to the station’s Config→Service-
s→AuthenticationService→AuthenticationSchemes container.
Step 3 To open the scheme property sheet, double-click the scheme name.
The property sheet opens.
Step 4 If you are configuring the LdapScheme, select the configuration type.
The LdapScheme supports three separate sets of configuration properties identified by the scheme
type: Active Directory, Ldap V2, and Ldap V3. While all types share the same basic properties
(Enable connection Pooling, Connection URL, SSL, and the attributes (attr) properties), each
includes one or more additional properties.
The KerberosScheme supports a single set of configuration properties that include some of the
same properties used by the LdapScheme.
Step 5 For each attribute property, enter the mnemonic required by the LDAP directory.
The attribute properties correspond to the names of the attributes in the LDAP directory. For example,
to populate the Full Name property, enter Fname. The following lists some of the mnemonics you
may use. For a complete list, contact your LDAP administrator.

For this Property enter this mnemonic in the property field.

User Login Attr
• For ActiveDirectory use sAMAccountName.
• For OpenLDAP, use uid.
Attr Email Email
Attr Full Name Fname
Attr Language Preferred Language

Attr Prototype Prototype

The following is an example of the attribute properties returned from an LDAP server.

Step 6 Configure the other properties based on the type of scheme and click Save.

October 10, 2018 9

Chapter 1 Setup and configuration LDAP Guide

Setting up user prototypes

When a new LDAP user logs in to a station for the first time, the system creates a user account in the UserSer-
vice and names it based on the user name portion of the person’s login credentials as stored on the LDAP serv-
er. The system then populates the Attr (attribute) properties, such as Full Name, Email, and Language,
directly from the LDAP server. It populates other properties, such as Permissions, from the local user proto-
type in the station. If no prototype is identified for the user, the system populates a new user's properties (all ex-
cept password) using values defined in the Default Prototype. Assigning a user prototype is a way to group
users who share the same permissions. Customizing the Default Prototype properties before you create users
can simplify the creation process even in a non-network-user scenario.
Prerequisites: The station is open in EC-Net 4 Pro.
Step 1 To configure the Default Prototype, right-click the UserService in the Nav tree and click
Views→Property Sheet.
Step 2 Expand the User Prototypes node and double-click the Default Prototype node.
Step 3 Make changes to the properties that you wish to apply to all system users, and click Save.
To ease the burden of making new users, consider changing these properties: Expiration, Au-
thentication Scheme Name and Prototype Name.
When they log in, any new LDAP users inherit these values as the default properties, including per-
missions. And these values appear as the defaults when you create a new user. You can change
them for a specific user at any time.
Step 4 To make a custom prototype, get a list of the attrPrototype names from your LDAP administrator.
The attr prototype property usually defines the group to which the user belongs.
For example, if you have user prototypes named "sysIntegrator" and "buildingManager", an Ldap user
who is a member of the buildingManager group on the LDAP server inherits permissions from the buil-
dingManager prototype.
Step 5 To make a custom prototype, right-click the Default Prototype in the Nav tree and click Duplicate.
The Name window opens with the default name of defaultPrototype1.
Step 6 Change this name to the same name for the user group (type of user) on the LDAP server, such as
Manager, Operator, Engineer, etc. and click OK.
Step 7 Repeat duplicating the Default Prototype and configuring properties until you have set up a separate
prototype for all user groups.
LDAP users may belong to multiple groups on the LDAP server, but they can only be assigned one
prototype. If an LDAP user belongs to multiple groups that match prototype names, the system de-
faults to the first prototype in the prototypes folder.
For example, if you have prototypes named "sysIntegrator" and "buildingManager", with “sysIntegra-
tor” being first in the list, and an LDAP user who is a member of both groups on the LDAP server, the
user inherits permissions from the “sysIntegrator” prototype.
Step 8 When you are finished, save the station by right-clicking the station Config node on the Nav tree and
clicking Actions→Save.
NOTE: It may be desirable to use the baja-UserPrototype as the default prototype instead of using the legacy
default prototype. To accomplish this, the Alternate Default Prototype property on the User Proto-
types folder can be set to the desired prototype. For details, see baja-UserPrototype, page 21.

Setting up local users

A local user, such as the admin, or other super user, may log in to a station using the standard login. This type
of login provides access to only the resources of the local station.
Prerequisites: EC-Net 4 Pro is open and you are connected to the station

10 October 10, 2018

LDAP Guide Chapter 1 Setup and configuration

Step 1 To open the platform, choose one of the following:

• If you are working on a remote host, open a platform connection to the host. If you are upgrading
this remote host, use the Station Copier tool to install the modified station back to the host.
• If you are working on a locally running station, such as on a Supervisor, open a local platform con-
nection and Start the station from the Application Manager view.
Step 2 Allow sufficient time for the station to restart.
If you are configuring a controller, a station transfer results in a controller reboot first.
Step 3 In EC-Net 4 Pro, open a station connection to the host as the admin super user.
Step 4 Double-click the UserService container in the Nav tree.
The property sheet opens.
NOTE: The Authenticator properties apply to local users only. LDAP authentication properties, in-
cluding user name and password, are configured in the LDAP server/system, and not in EC-Net. The
Prototype Name applies only to users supported by LDAP.
Step 5 Create a new super user to replace the admin user.
For this user you do not need to enter LDAP attribute mnemonics. A local user does not appear in the
LDAP directory on the LDAP server.
Step 6 After creating the new super user, delete the admin user since it is no longer a frozen property.
NOTE: Do not delete the admin user before you create the new super user.
Step 7 Create a new local user as a super user. Assign a user name that easily identifies the host platform,
and a strong password.
Step 8 Update the other stations in the network with the proper credentials under Client Connection→Nia-
garaStation to recognize the newly-configured station.
Your local station now has two local users in addition to the now disabled admin user and the standard guest
user.

Setting up a client PC for Kerberos

For any computer to access (as a client) a station that supports Kerberos authentication, you must update a
Kerberos configuration file (krb5) in the PC with the default realm and define which flags to set on acquired
tickets. (Kerberos authentication requires the ability to acquire Kerberos tickets that can be forwarded.) In addi-
tion, you must update the Windows registry.
Step 1 In EC-Net 4 Pro, click Tools→Kerberos Configuration Tool.
Step 2 In the Basic Krb5 Conf Editor view, click the Forwardable checkbox to set the property value to
“true” and click the toolbar icon to save your change, as shown here.

October 10, 2018 11

Chapter 1 Setup and configuration LDAP Guide

NOTE: If your Kerberos setup requires a more advanced krb5.conf configuration, you can man-
ually configure the file using the Advanced Krb5 Conf Editor view, located under the View dropdown
list, as shown here.

Step 3 If your PC is running Windows XP SP2 or later, and you would like to access your native Kerberos
ticket, you must set a registry key to allow Java to access the ticket.
a. Before setting a registry key, back up your Windows registry.
b. To set the key, start the registry editor (Start→Run... and enter regedit) and add or edit the fol-
lowing key:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\
Kerberos\Parameters

Value name: AllowTgtSessionKey

Value type: REG_DWORD
Value: 0x01
If configuring Windows XP, add or edit this key:
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\Kerberos
Value name: AllTgtSessionKey
Value type: REG_DWORD
Value: 0x01

NOTE: If necessary, you can return to the default Windows security setting by changing the value of
this registry key to zero (0).

12 October 10, 2018

LDAP Guide Chapter 1 Setup and configuration

On completion of this procedure, you have successfully updated the Kerberos configuration file (krb5.conf)
and set up a registery key in the PC.

Setting up access to the Key Distribution Center

Kerberos authentication issues authentication tickets, which the system uses in a similar manner to private-key
authentication. Ticket processing involves retrieving a key from a KDC (Key Distribution Center). Kerberos uses
reverse DNS (Domain Name System) to find the referenced Key Distribution Center. You must specify a re-
verse DNS entry for both the client and station DNS servers. Otherwise, users are unable to acquire Kerberos
tickets and log in.
This procedure documents how to configure both a PC client and station to access a KDC. While modifying the
hosts file is simple enough for a single station, and can be useful for testing your Kerberos setup, this ap-
proach can be tedious and prone to error when dealing with multiple stations and multiple client machines. Set-
ting up DNS servers with reverse DNS entries is the recommended best practice.
Step 1 Contact your IT administrator to see if the appropriate entry exists on the LDAP server.
If you do not have a workable reverse DNS entry, you may configure an entry in the hosts file on
each client PC and station. This entry maps the IP address of the Key Distribution Center.
NOTE: Configuring mapping in the hosts file is acceptable for testing purposes, but is not recom-
mended on a production system where the site is live and many people need to access it. It is impor-
tant to note that having the proper DNS entries is far more desirable than modifying hosts files. If you
find that the DNS entries do not already exist, request that your IT administrator add them.
On Windows PCs, the hosts file is located at C:\Windows\System32\drivers\etc\hosts.
Step 2 Add the following entry in your client hosts file:
nnn.nnn.nnn.nnn kdc.domain.net
where nnn.nnn.nnn.nnn is the IP address of the KDC and kdc.domain.net is the domain name.
Step 3 On each platform, use the platform TCP/IP Configuration view (or equivalent view on the station’s
TcpIpPlatformService) to access and edit the hosts file with the same entry.

Making sure you can connect using a browser

Kerberos processes names and not IP addresses. The IP address of your PC must map to the name of the
service you intend to use.
Step 1 Attempt to connect to the station using a fully-qualified domain name: http://some.domain.com/
somepage, where
some.domain.com/somepage is the LDAP server’s domain name and home page name.
Step 2 If you are unable to connect, edit your client PC’s hosts file to add an entry similar to:
nnn.nnn.nnn.nnn some.domain.com,
where nnn.nnn.nnn.nnn is the IP address of the LDAP server,
and some.domain.com is the domain name of the server.
For example,
172.16.10.10 kerbtest2.mydomain.net
This Ip address maps to the Kerberos service associated with kerbtest2 on mydomain.net.

Configuring Firefox
Using Firefox for browser access (as a Kerberos authenticated LDAP user) to a station requires that you add to
the browser’s security configuration the stations to which you wish the browser to connect .
NOTE: The following instructions are subject to change due to browser updates. Refer to the browsers' docu-
mentation for the latest instructions.

October 10, 2018 13

Chapter 1 Setup and configuration LDAP Guide

Step 1 Open a Firefox window.

Step 2 Type about:config in the location bar and press Enter.
If a warning appears, continue (promise to be careful).
Step 3 In the Search box near the top of the page type negotiate.
This filters the Firefox configuration attributes to six or seven. You need to edit these entries:
network.negotiate-auth.delegation-uris
network.negotiate-auth.trusted-uris
Step 4 Include the URLs of the station(s) that the browser needs to be able to access. Use a comma to sepa-
rate multiple stations.
For example, if two stations have the following URLs: http://host1.domain.com/somepage,
and http:/ /host2.domain.com/somepage, enter the URLs as follows:
host1.domain.com,host2.domain.com
Firefox is ready for Kerberos authentication and you should be able to log in to stations without being prompted
for a user name and password.

Configuring Internet Explorer

To configure Internet Explorer on a client LDAP host to use Kerberos, you must change security settings.
NOTE: The following instructions are subject to change due to browser updates. Refer to the browsers' docu-
mentation for the latest instructions.
Step 1 Open an Internet Explorer window.
Step 2 Using the menu bar, click Tools→Internet Options.
The Internet Options window opens.
Step 3 Click the Security tab and select the Local intranet zone.
Step 4 Click Sites→Advanced.
The Add a website to this zone window opens.
Step 5 Type in the URL for a station and click Add.
http://host1.domain.com
where host1.domain.com is the station’s URL.
If you have multiple stations to add, continue typing in URLs and clicking Add.
Step 6 To return to the Security tab, click Close→OK.
Step 7 With the Local intranet zone selected, click the Custom level... button.
The Security Settings — Local intranet window opens.
Step 8 To use Kerberos authentication without a prompt, scroll down to the User Authentication section
(near the bottom), and click to enable Automatic logon only in Intranet zone.
If you prefer to be prompted, enable Prompt for user name and password.
Step 9 To close Internet Options, click OK twice.
Internet Explorer should now be ready for Kerberos authentication and you should be able to log in to stations
without being prompted for a user name and password.

14 October 10, 2018

LDAP Guide Chapter 1 Setup and configuration

Configuring Chrome security

Using Google Chrome for browser access (as a Kerberos authenticated LDAP user) to stations requires some
client side setup.
NOTE: If you previously configured Internet Explorer to use Kerberos for LDAP access to stations, this may al-
ready be done. However, the Chrome startup arguments still need configuration.
Also, note that the following instructions are subject to change due to browser updates. Refer to the browsers'
documentation for the latest instructions.
Step 1 Open a Google Chrome window.
Step 2 Click Customize→Settings or type chrome:settings in the location bar and press Enter.
The Chrome Settings page opens.
Step 3 Near the bottom of the page, click Show advanced settings..., scroll down to the Network section
and click the Change proxy settings... button.
The Internet Options window opens.
Step 4 Click the Security tab, select the Local intranet zone, click Sites→Advanced.
The Add website to this zone window opens.
Step 5 Type in the URL for a station and click Add.
http://host1.domain.com
If you have multiple stations to add, continue typing in URLs and clicking Add.
Step 6 To return to the Security tab, click Close→OK.
Step 7 With the Local intranet zone selected, click the Custom level... button.
The Security Settings — Local intranet window opens.
Step 8 To use Kerberos authentication without a prompt, scroll down to the User Authentication section
(near the bottom), and click to enable Automatic logon only in Intranet zone.
If you prefer to be prompted, enable Prompt for user name and password.
Step 9 To close Internet Options, click OK twice.
Step 10 Close all Chrome windows.

Configuring Chrome registry keys

In order for Kerberos authentication (without a logon prompt) to work correctly, you must configure a registry
key in the client PC to hold the Kerberos delegation server whitelist for Chrome. This whitelist is the list of host
names of each EC-Net station you intend to authenticate to.
Step 1 To add the key, first start the Registry Editor (Start→Run... regedit).
CAUTION: Incorrectly editing the registry may damage your system. Before making changes to the
registry, you should back up any valued data on your computer. Refer to the Registry Editor Help for
complete details on configuring the registry.
Step 2 Expand the HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google directories and create a new
Key named: “Chrome”.
Step 3 Edit the newly created Chrome key to add a new String Value named:
“AuthNegotiateDelegateWhitelist”.
Step 4 Edit the new string value to configure its Value data field with a comma separated list (without
quotes) of the host names of each station you would like to authenticate to.
For example: "host1.domain.com,host2.domain.com".
Step 5 Close the registry window.

October 10, 2018 15

Chapter 1 Setup and configuration LDAP Guide

Google Chrome is now configured for Kerberos authentication. You should be able to log in to stations without
being prompted for a user name and password.

Configuring a Kerberos master-slave server

Many Kerberos/LDAP systems have redundant Kerberos/LDAP servers to provide load balancing and high
availability. Typically, there will be one DNS entry that will resolve to each of the Kerberos/LDAP servers. For
example, example.com may resolve to dc1.example.com and dc2.example.com. If the client fails to con-
nect to the first entry, it will fail over to the next one. There are a few extra steps necessary to configure master-
slave fail-over in EC-Net.
Step 1 In the Kerberos Authentication Scheme, set your connection URL to one that will resolve to each of
your LDAP servers (ldap://example.com in our example above).
Step 2 Set the Connection Timeout property to a reasonable time for your scenario.
For more detailed information on the property see, ldap-KerberosAuthenticationScheme, page 33.
Step 3 Set the Key Distribution Center to a hostname that will resolve to each of your key distribution centers
(e.g. asexample.com in our example above).
Step 4 Open the Basic Krb5 Conf Editor view on the Kerberos Authentication Scheme.

Step 5 Select and enter values for the Kdc Timeout and Kdc Max Retries properties.
For more detailed information on these properties see, ldap-BasicKrb5ConfEditor, page 29.
Step 6 For any EC-Net 4 Pro client that will authenticate to the station with Kerberos, navigate to Tool-
s→Kerberos Configuration Tool and set the Kdc Timeout and Kdc Max Retries properties to the
same values that you configured for the station, and set the Forwardable property to true.

16 October 10, 2018

Chapter 2 Introduction to LDAP
Topics covered in this chapter
♦ LDAP implementations
♦ How LDAP benefits EC-Net
♦ Local vs LDAP users
♦ Configuration properties and LDAP user attributes
♦ Automatic new user creation
♦ Kerberos and the single-sign-on feature
♦ Logging in with Kerberos credentials
♦ Using a browser and Kerberos to log in with a single sign on
♦ Using a browser and only LDAP credentials to log in

LDAP (Lightweight Directory Access Protocol) uses a separate server to provide an IP-network-accessible, hi-
erarchical, and distributed database for storing information about authorized system users and their access
privileges. Many network hosts can use the LDAP services, which are administered from a central location.

LDAP implementations
LDAP is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distrib-
uted directory information services for an IP network. A common usage of LDAP is to provide a single sign on
where a single user logs in to multiple network services using but one password.
EC-Net supports two LDAP server implementations:
• Windows AD (Active Directory)
This widely-implemented type of LDAP server is a Microsoft-supplied service used on Windows domain net-
works, and is included in most Windows Server operating systems. AD provides an interface for these proto-
cols: LDAP (LDAPv2 or LDAPv3) and Kerberos (for authentication). With AD, users can access resources
anywhere on the network with a single login.
The Windows AD is structured as a hierarchical tree of objects.
To integrate a Windows AD system with a network of EC-Net stations, in the Services container and under
the AuthenticationService, add one of the authentication schemes:
– LdapScheme is for ADs versions LDAPv2, and LDAPv3.
– KerberosScheme is for ADs that support Kerberos authentication. The host EC-Net platform must be li-
censed for LDAPv3. If Kerberos authentication is used, the LDAPv3 requires the attribute: Kerberos=
”true”.
• Open source implementations
These implementations, including Apache Directory Server and OpenLDAP, support both LDAPv2 and
LDAPv3 (with the possibility of Kerberos authentication).
Each of these implementations is structured as a hierarchical tree of objects. Each object has a set of
attributes.

How LDAP benefits EC-Net

LDAP communicates record-based, directory-like data between programs. It defines database access permis-
sions and provides a schema, which is a way to describe the format and attributes of data stored in a server.
Corporate and campus installations that already use Windows Active Directory, or other LDAP-based directory
services to manage user access across distributed network resources, can benefit from configuring EC-Net sta-
tions to use an LDAP user service. Benefits include:

October 10, 2018 17

Chapter 2 Introduction to LDAP LDAP Guide

• Ease of implementation. Installations that already use Windows AD or an open-source implementation of

LDAP can easily include stations in their existing user management configuration.
• Automatic new user account creation. When a user logs in to a station for the first time, the system automati-
cally creates a user account (component) in the station and populates it with pre-defined properties (based
on user prototype), such as permissions, and predefined LDAP properties (from the LDAP server), such as
email address, full name, and language.
• Security. Kerberos authentication (available for LDAPv3-based AD or open source systems) offers a high
level of security. Implementing Kerberos requires client setup of hosts and browsers.
• Simplified login. Current users may log in without needing to enter credentials.
NOTE: All stations on the network (both Supervisors and controllers) must use the LDAP server. The system
does not support a mixture of stations using the standard UserService with other stations using an LDAP
user service.

Local vs LDAP users

Once an LDAP authentication scheme is configured and running, most user access to a station comes from
LDAP users. However, most configurations benefit from at least two regular station users that are not depend-
ent upon LDAP server communications.
The two local users are:
• A replacement user for the admin user. The name “admin” is commonly used and easy for hackers to guess.
Creating a new local super user with a unique name and strong password is a simple way to improve overall
system security.
• A local service user you can reference in other remote stations when configuring the Client Connection
properties under the remote station’s NiagaraStation device.
In theory, an LDAP user could serve as a service user, however, this is not recommended. A local service
user makes the initial configuration of a NiagaraNetwork more straightforward and provides immunity from
station-to-station communication issues that might arise, say from LDAP password expiration rules, or in
the unlikely event of LDAP server problems.
NOTE: Do not allow any person to log in to the station using this user account. A service user is only for Fox
station-to-station communications.

Configuration properties and LDAP user attributes

An LDAP server maintains a directory of information about system users. Each entry (record) in an LDAP direc-
tory consists of multiple attributes, which may or may not be assigned values. Users within the NiagaraNet-
work require additional properties, such as permissions and facets that apply only within the NiagaraNetwork
context.
A sample LDAP user entry might contain the following information from the LDAP server:

Figure 1 Example LDAP directory record

Several key configuration properties in each of the LDAP authentication schemes correspond directly to the
names of attributes in the LDAP directory.

18 October 10, 2018

LDAP Guide Chapter 2 Introduction to LDAP

The property names for these LDAP properties begin with Attr (attribute). The system pulls the values for
these properties from the LDAP directory on the LDAP server and uses them to fill out information about the
user.
In the example above, the station user is jdoe. To populate the Full Name property value, you enter dis-
playName in the Attr Full Name field.
The user properties that are not maintained by the LDAP server appear in the UserService property sheet for
each user.

Automatic new user creation

All users must exist in the LDAP directory on the LADP server. When a new employee joins your team, make
sure you set them up in the LDAP server before they attempt to log in to a station. An appropriate user proto-
type that contains default properties for each type of user should exist in each station. (User prototypes allow
you to group users, for example: manager, operator, engineer, etc.).
When a new user logs in to a station for the first time, the system automatically creates a new user account
(component) in the station. It uses the user name that the person logged in with (the person’s user login name
on the LDAP server) as the account name. The system populates (maps) this component’s properties from two
sources:
• It populates the properties the attr properties with attributes supplied from the LDAP server.
One of those attributes identifies the group within your organization to which the user belongs. This attribute
is the Attr Prototype.
• EC-Net uses the Attr Prototype name to identify the user prototype in the station from which to populate
the component’s local user properties, including user permissions, facets, Nav file, default Web and Mobile
profiles, and other specific properties required by a station.
For Active Directory, this is the memberOf attribute.
NOTE: For the automatic populating of EC-Net user properties to work, the name of the Attr Prototype
in the LDAP server must exactly match the name of a user prototype in the station.
• If the Attr Prototype does not match a user prototype name or this property is blank, the system uses
the Default Prototype as its source.
An LDAP user may be a member of multiple groups.

Kerberos and the single-sign-on feature

EC-Net supports Kerberos authentication when logging in to a station. Kerberos is a widely used authentication
protocol that helps to keep your credentials and station safe.
SSO (Single Sign On) is an access control feature of Kerberos that allows the automatic logging in to multiple
related, but independent software systems. When you use a browser to log in with LDAP and Kerberos, you
provide a single set of credentials and receive a ticket, which allows you to automatically gain access to all net-
worked stations. SSO also makes it possible to log in to individual stations without being prompted for user
name or password each time.

Logging in with Kerberos credentials

Kerberos is an open-source computer network authentication protocol that uses tickets to verify the identity of
users before allowing them to access network resources.
Prerequisites: Your client host (your PC) is part of the same LDAP realm as the station.
Step 1 Launch EC-Net 4 Pro and open a platform or station.
If EC-Net 4 Pro is able to acquire your native Kerberos credentials, it displays the Authentication
window with credentials filled in.

October 10, 2018 19

Chapter 2 Introduction to LDAP LDAP Guide

Step 2 Do one of the following:

• If EC-Net 4 Pro fills in your credentials with credentials from the LDAP server, click OK to log in.
• If EC-Net 4 Pro is unable to acquire your native Kerberos credentials from the LDAP server, it dis-
plays a simple login window.
• To log in as a different LDAP user or as a local user, enter different credentials.
You are logged in using Kerberos authentication.

Using a browser and Kerberos to log in with a single sign on

A single sign-on saves time because the system requires a user to enter credentials only once.
Step 1 Do one of the following:
• If the station shares the current realm, log in as the current user by clicking the realm login button.
For this choice to work, the station must reside on the same realm that you are on. For example, if
you are logged in to the FACTORY realm, the system cannot use your credentials to access a sta-
tion set up for the HQ realm.
• For SSO access, go to the /login-kerb page (instead of this default /login page) and the sys-
tem directly logs you in to the station without having to click a Login button.
Step 2 If you can successfully log in using SSO and want to bypass the login window in the future, click to se-
lect the Remember my choice check box at the bottom of the window.
This is effectively the same as going to the station’s /login-kerb page.
Step 3 If you are not using the SSO feature, click the OR (Hide) link.
This reduces the size of the login Window to include just credentials.

Step 4 To restore the login window, click the OR (Show) link.

Browser cache maintains the configuration of the last-used login window.
NOTE: All EC-Net 4 EC-BOS controllers support the Kerberos SSO (Single Sign On) feature from a browser,
while EC-NetAX controllers do not, with the exception of EC-BOS-8s. The reason for this is that Kerberos SSO
via the browser is not supported in Java 5 (used in EC-NetAX PPC EC-BOSs), but all EC-Net 4 EC-BOSs use
Java 8 (which does support it) including EC-BOS-8s running EC-NetAX-3.8U1.

Using a browser and only LDAP credentials to log in

There may be several reasons to log in with your LDAP credentials each time you access a controller or station.
One reason is that you wish to log in as a different LDAP user, or you wish to log in as a local station user (such
as admin).
Step 1 Open your browser and enter the IP address for your controller in the locator field.
The system displays a login window.
Step 2 Enter your credentials and click the Login button.
NOTE: An https secure connection is required whenever logging in with username and password for Kerberos
or LDAP, and foxs connection is required when logging in with LDAP. If using a nonsecure connection you will
see a login failure and a “secure connection required” message. .

20 October 10, 2018

Chapter 3 Components
Topics covered in this chapter
♦ baja-AuthenticationService
♦ baja-UserPrototype
♦ baja-UserService
♦ ldap-BasicKrb5ConfEditor
♦ ldap-AdvancedKrb5ConfEditor
♦ ldap-LdapScheme
♦ ldap-KerberosAuthenticationScheme

Components include services, folders and other model building blocks associated with a module. You may drag
them to a property or wire sheet from a palette.
Descriptions included in the following topics appear as context-sensitive help topics when accessed by:
• Right-clicking on the object and selecting Views→Guide Help
• Clicking Help→Guide On Target

baja-AuthenticationService
This component manages how users verify their identity to the station, using authentication schemes. Some
schemes require password configuration, others do not. The AuthenticationService node is located in the
Services container.
The New Station wizard installs two default authentication schemes:
• DigestScheme provides SCRAM-SHA256 (Salted Challenge Response Authentication Mechanism) tech-
nology for connecting EC-Net 4 entities. Several messages are passed back and forth to prove the client
knows the password.
• AXDigestScheme provides compatibility with stations running a previous software version.
Schemes available in the ldap palette include:
• LdapScheme
• KerberosScheme
Additional schemes may reside in other palettes. Developers may also create authentication schemes for spe-
cial circumstances. You pick the one or two schemes you wish to use, drag them from the palette and drop
them directly under the AuthenticationService in the Nav tree.

baja-UserPrototype
The baja-UserPrototype (an alternative to the legacy User Prototype workflow) was created to provide better
control over how LDAP users are created and where their properties come from.
To add an LDAP user:
1. Click and drag a User Prototype from either the baja or ldap palette to the User Prototypes folder under
the User Service, as shown.

October 10, 2018 21

Chapter 3 Components LDAP Guide

2. Rename this User Prototype to a name that matches the desired attrPrototype value, just as you would with
a legacy User Prototype.
When you open the User Prototype, you will see that it has the following properties:
• Full Name
• Enabled
• Expiration
• Language
• Email
• Facets
• Nav File
• Cell Phone Number
• Roles
• Allow Concurrent Sessions
• Web_WebProfileConfig
• Web_MobileProfileConfig
Each of these properties have two sub-properties, as shown:

Name Value Description

Overridable true, false (default) Determines whether or not the property can be manually over-
ridden on an LDAP user that was created from this prototype.
Value string Determines what the matching property on the user will be set to
when creating or updating from a prototype.

Usage Notes
Each time an LDAP user logs in, a prototype will be selected for the user based on the attrPrototype, just as
with legacy prototypes.
The user will have any attribute properties (email, full name, language, cell phone number) set from the LDAP
server attributes based on the values in the Ldap Scheme. If any of these attributes are missing, the property
will be set from the User Prototype. Every other property will be set from the User Prototype.
Any property on the user whose matching User Prototype property is not set to Overridable will be set to read
only. Any changes made to these properties will be overwritten the next time the user logs in.
If a User Prototype’s property is set to Overridable, any users created from that prototype will be writable. If they
are modified, that property will never be updated from LDAP attributes or the User Prototype again unless the
user is deleted and recreated at next login, or the User Prototype’s property is set back to non-Overridable.
It may be desirable to use a baja-UserPrototype as the default prototype instead of using the legacy default pro-
totype. To accomplish this, the Alternate Default Prototype property on the User Prototypes folder can be set to
the desired prototype, as shown here.

22 October 10, 2018

LDAP Guide Chapter 3 Components

NOTE: This will only apply to Ldap and any future authentication schemes/features that support the new baja-
UserPrototype. The NiagaraNetwork and User Manager will still use the legacy default prototype.

baja-UserService
This service manages all system users: human and machine. You access it by right-clicking UserService and
clicking Views→Property Sheet.
The User Manager is the primary view of this service. By default, the UserService is included when you create
a new station using the New Station wizard. The UserService component is available in the baja module.

Figure 2 User Service property sheet view

Effect of property changes on user session

Starting in EC-Net 4 v4.3, any active session associated with a user will be terminated if the following changes
are made in UserService propery sheet.
• If you remove the User from the UserService Property Sheet.
• If the Enabled property is set to false.
• If the Expiration property is changed to a date which has already expired.
• If the Authentication Scheme Name is changed.
• If the Allow Concurrent Sessions is set to false.

October 10, 2018 23

Chapter 3 Components LDAP Guide

Property Value Description

Lock Out Enabled true or false If enabled (true), a number of consecutive authentication fail-
ures temporarily disables login access to the user account for
the duration of the lock out period (next property). Using lock out
makes it difficult to automate the guessing of passwords.
NOTE: Each user has a Clear Lock Out action.
Lock Out Period hours minutes sec- If lock out is enabled, this property defines the period of time a
onds (default is 10 user account is locked out before being reset. While locked out,
seconds) any login attempt (even a valid one) is unsuccessful.
NOTE: The default Lock Out value guards against an auto-
mated, brute-force password attack, where a computer applica-
tion issues hundreds of login attempts a second. The 10 second
latency thwarts such an attack, as the attacker must wait 10 sec-
onds after each five unsuccessful login attempts. If deemed nec-
essary, you can adjust this value to guard against human attack.
Max Bad Logins number from 1 — If lock out is enabled in conjunction with the Lock Out Window,
Before Lock Out 10 (default is 5) this property specifies the number of consecutive failed user log-
in attempts that trigger a lock out after a window of time.
Lock Out Window hours minutes sec- If lock out is enabled, and a user fails to log in successfully be-
onds (default is 30 fore the Max Bad Logins Before Lock Out window (period)
seconds) expires, the user is locked out for the Lock Out Period
duration.
The system enforces changes to lock out properties the next
time the user logs in. For example, if Max Bad Logins Before
Lock Out is set to 5, user ScottF fails to log in four times within
the Lock Out Window, and an admin-level user changes Max
Bad Logins Before Lock Out to 3, the change does not lock
ScottF out. User ScottF still has one more chance to log in be-
fore getting locked out.
If ScottF’s fifth attempt to log in fails, the system locks him out
the next time he attempts to log in because five failed attempts
is greater than or equal to the Max Bad Logins Before Lock
Out of 3.
Default Auto Logoff 0000h 15m Specifies the amount of time that a period of inactivity may last
Period (default) before a station connection is automatically disconnected. The
acceptable range of values is two minutes to four hours. This
limit is observed only when the User’s Use Default Auto
Logoff Period property is set to true.
SMA Notification multiple properties See the next section
Settings
User Prototypes multiple properties See the next section.

SMA Notification Settings

These are the properties to configure the Software Maintenance Agreement (SMA) expiration reminder. For de-
tails, see the EC-Net 4 Platform Guide.

24 October 10, 2018

LDAP Guide Chapter 3 Components

Figure 3 SMA expiration reminder properties

Type Value Description

Show Expiration true (default), false When set to true, the initial SMA expiration reminder displays
Date in the browser-connected station Login window at 45 days prior
to expiry. When set to false, the initial SMA expiration re-
minder is hidden, it does not display.
NOTE: Once the SMA expires, the SMA expiration reminder
cannot be hidden.
Expiration 45 day (default) By default, this is set to 45 days before expiration.
Reminder [30–365 days]

User Prototypes
UserPrototypes is a frozen slot on a station’s UserService. It contains a frozen Default Prototype (proper-
ties shown in the following figure) to support centralized users in the station’s NiagaraNetwork, as well as a fro-
zen Alternate Default Prototype for any additional user prototypes needed to support remote authentication
schemes such as LDAP, Kerberos, and SAML.
Default Prototype
The User Service and EC-Net Network still use the existing default user prototype functionality and there are no
current plans to migrate them to the new UserPrototype. Also, LDAP and Kerberos will continue to support the
default user prototypes.
Alternate Default Prototype
This property allows you to specify an alternate user prototype to start with when creating a new user (instead
of only using defaultPrototype). For example, you would use this to select a prototype (other than default proto-
type) specifically created to support a remote authentication scheme, such as SAML.

October 10, 2018 25

Chapter 3 Components LDAP Guide

Figure 4 Default Prototype user properties

Property Value Description

Full Name text The user’s name.
Enabled true (default) or Unchecked (false) disables this user. Disabled users cannot
(false access the system.
Expiration radio buttons
• Never Expires permits this user to always log in.
• Expires On [date and time] allows this user to log in until
the expiration date and time.
Lock Out true or false Checked enables a user to log in. Unchecked (true) prohibits
(default) this user from logging in.
Language two lower-case Defines the ISO 639 language code. For a list of codes, see the
letters following: http://www.loc.gov/standards/iso639-2/langcodes.
html.
Email email address Defines the user’s email address.
Authenticator additional Manages user password.
properties
Facets timeFormat and Configures the time format and units to use when this user logs
unitConversion in to the system.
Nav File file:^nav/Nav- Identifies the file to use for displaying a customized navigation
File.nav tree.
Prototype Name text Identifies the name of the prototype used to create this user.

26 October 10, 2018

LDAP Guide Chapter 3 Components

Property Value Description

Network User true or false When true, this user account can be synchronized to other sta-
(default) tions on the network.
Cell Phone Number number Defines the user’s mobile phone number.
Authentication drop-down list Identifies the authentication scheme used to verify this user.
Scheme Name
Roles radio buttons Identifies the user’s role.
Allow Concurrent true (default) or When checked, allows multiple sessions. When unchecked, a
Sessions false new session invalidates the old session.
Auto Logoff additional Refer to the below section in this document.
Settings properties
Default Web Profile additional Refer to the below section in this document.
properties
Mobile Web Profile additional Refer to the below section in this document.
properties

Auto Logoff Settings

Property Value Description
Auto Logoff true (default) or When true, a station connection (via EC-Net 4 Pro or web
Enabled false browser) automatically disconnects if a period of inactivity ex-
ceeds the amount of time specified for the Default Auto Log-
off Period (in the UserService).
When false, the station does not automatically terminate a
user’s session due to inactivity.
NOTE: Separate auto logoff options exist for EC-Net 4 Pro
which functions independently of these station settings. For de-
tails, see the Getting Started with EC-Net 4.
Use Default Auto true (default) or If the property is set to true, the Default Auto Logoff Pe-
Logoff Period false riod (configured in the UserService) displays the specified
time.
When false, the specified Default Auto Logoff Period is
not observed. Instead, use the Auto Logoff Period property
to set a different auto logoff time period.
Auto Logoff Period 0h 15m (default) (2- When Use Default Auto Logoff Period property is set to
4 hours) false, use this property to specify a different time period . The
range is 2 minutes to 4 hours.
Otherwise, this property is read only, showing the value speci-
fied in the UserService’s Default Auto Logoff Period.

Authenticator—Password Config
Property Value Description
Force Reset at true or false Requests that the user create a new password the next time
Next Login (default) they log in.
Expiration radio button Configures a password change for a specific date and time.

October 10, 2018 27

Chapter 3 Components LDAP Guide

Default Web Profile

These properties configure the information available to a specific user who accesses the system through a
browser. By default all information is visible.

Property Value Description

Type Spec (type of drop-down list Identifies the type of profile:
profile)
• hx (default)
• axvelocity
• mobile
• EC-Net 4 Pro
Type Spec (type of drop-down list Identifies the type of profile:
profile)
• BasicHxProfile
• DefaultHxProfile
• HTML5HxProfile (default)
• HandHeldHxProfile
Hx Theme drop-down list Selects the look of the user interface:
• Zebra
• Lucid
Enable Hx EC-Net yes (default) Removing the check mark disables the views.
4 Pro Views
Enable Nav Tree yes (default) Removing the check mark disables the Nav tree.
Side Bar
Enable Search Side yes (default) Removing the check mark disables the use of the search side
Bar bar.
Enable Palette Side yes (default) Removing the check mark disables the use of the palette side
Bar bar.
Enable Nav File yes (default) Removing the check mark disables the Nav tree.
Tree
Enable Config Tree yes (default) Removing the check mark disables the Config tree.
Enable Files Tree yes (default) Removing the check mark disables the Files tree.
Enable Histories yes (default) Removing the check mark disables the Histories tree.
Tree
Enable Hierarchies yes (default) Removing the check mark disables the Hierarchies tree.
Tree

Mobile Web Profile

Property Value Description
Type Spec (type of drop-down list Identifies the type of profile:
profile)
• Hx
• Mobile
Type Spec (type of drop-down list Identifies the type of profile:
profile)
• BasicHxProfile

28 October 10, 2018

LDAP Guide Chapter 3 Components

Property Value Description

• DefaultHxProfile
• HTML5HxProfile (default)
• HandHeldHxProfile
Mobile Nav File ord Identifies the location of the file that defines the mobile nav tree
for this user.
Hx Theme drop-down list Selects the look of the user interface:
• Zebra
• Lucid

ldap-BasicKrb5ConfEditor
In EC-Net 4 v4.3 and later, an added editor view available under the Tools menu, Basic Krb5 Conf Editor, al-
lows you to configure certain properties of an existing Kerberos configuration file (krb5.conf).
Kerberos authentication requires the ability to acquire Kerberos tickets that can be forwarded. The editor allows
you to enable/disable the Forwardable property.

Figure 5 Basic Krb5 Conf Editor view

For more details see the setup and configuration procedures for Kerberos in the LDAP Guide.

Properties
Property Value Description
Forwardable true (default), Enables and disables forwarding of Kerberos tickets.
false
Kdc Timeouts 30 (default) Required for redundant server support, specifies the length of
time the station attempts to connect to the key distribution center
before failing the connection attempt.
Kdc Max Retries 3 (default) Required for redundant server support, specifies the maximum
number of times the station attempts to connect to one key distri-
bution center before to the next one.

NOTE: Values entered for the Kdc Timeouts and Kdc Max Retries properties should be tailored to your specific
scenario based on how long successful kdc connections generally take and when the cut off time should be to
consider the connection failed. As with the connection timeout above, this time needs to be not too short to
cause false connection failures, but not so long as to cause excessive delays when a server is down.

October 10, 2018 29

Chapter 3 Components LDAP Guide

ldap-AdvancedKrb5ConfEditor
In EC-Net 4 v4.3 and later, an added editor view available in the EC-Net 4 Pro. Located under Tools→Ker-
beros Configuration Tool and the views dropdown list, the Advanced Krb5 Conf Editor provides a simple
text editor which you can use to manually edit an existing Kerberos configuration file (krb5.conf) or to create
a new one.

The file requires only the two lines contained in this view.
On a Windows host the primary location for the file is: NIAGARA_HOME/security/krb5.conf. Only if this file
is missing would you fall back to the Java krb.conf or operating system specific krb.conf/ini.

ldap-LdapScheme
Adding the LdapScheme manages EC-Net 4 user authentication using an LDAP (Lightweight Directory Access
Protocol) server. This allows you to connect to a previously existing database of users—a huge advantage
when setting up new users (you don’t have to manually create new users in each station). The LDAP server al-
so keeps passwords centralized and in sync.
One common example of an LDAP server is ActiveDirectory, which is used by Windows to manage users.
NOTE: TLS is required for LDAP authentication. If an LDAP user attempts to login over a nonsecure connec-
tion, a login failure occurs with a message stating "Secure connection required". Enable TLS secure communi-
cation in the FoxService (Foxs enabled) and WebService (Https enabled). Additionally, if the
LdapScheme is not set to Ldap V3 with either the CRAM-MD5 or DIGEST-MD5 authentication mechanism, the
system sends the username and password to the LDAP server in plain text. Again, ensure that TLS is enabled
in the LdapScheme. This may require you to configure the LDAP server to support communication security
(SSL/TLS).

30 October 10, 2018

LDAP Guide Chapter 3 Components

Common properties
Property Value Description
Type drop-down list of The system supports sets of configuration properties:
configuration types
• Active Directory Config
• Ldap V2 Config
• Ldap V3 Config
Each type supports slightly different properties. Choose the type
that best fits your Ldap server’s requirements.
Enable Connection true or false Setting this property to true allows connections to be shared
Pooling and reused. This can improve performance.
Connection URL ldap://your.do- Identifies the URL (your.domain.net) for the LDAP server.
main.net Standard LDAP ports are 389, or 636 (if using SSL). If the server
or uses a non-standard port, include the port (your.domain.
ldap://your.do- net:nnn) in the URL, for example, ldap://your.domain.
main.net:nnn net.999..
SSL true or false Enables and disables secure communication. If set to true,
make sure that SSL (3.8) or TLS (4.0) is enabled in the station’s
FoxService (for EC-Net 4 Pro-to-station access) and Web-
Service (for browser-to-station access). Note that in FoxSer-
vice and WebService TLS must be enabled whether SSL is
true here or not.
User Login Attr text
For AD this value Identifies the specific attribute in the LDAP directory to store the
defaults to sAMAc- LDAP user login name. For AD servers, this is always sAMAc-
countName. countName. For OpenLDAP servers, it would be uid.

User Base domain Identifies the sub-tree of the LDAP server in which users who
components can access this station are found. At the very least it must con-
tain the domain components of the server’s domain, for exam-
ple: DC=domain, CD=net
Attr Email Email address Identifies the specific attribute in the LDAP directory to store the
The AD default val- user’s LDAP email address. This value populates the EC-Net
ue is: mail. user’s Email property.
Attr Full Name Text Identifies the specific attribute in the LDAP directory to store the
The AD default val- user’s full name. This value populates the EC-Net user’s Full
ue is: name. Name property.
Attr Language Two-letter language Identifies the specific attribute in the LDAP directory to store the
code user’s language. This value populates the EC-Net user’s Lan-
The AD default is guage property.
blank.
Cell Phone Number telephone number Identifies a user’s smart phone.
format
Attr Prototype Text Identifies the User Prototype with which the system popu-
The AD default is lates a new user’s local properties.
memberOf.
If this property is blank or the name does not match any user
prototype, the system uses the Default Prototype to popu-
late local user properties.

October 10, 2018 31

Chapter 3 Components LDAP Guide

Property Value Description

If a user belongs to multiple user groups (user prototypes), the

top-to-bottom order of prototypes determines which prototype
the system uses. If the value of a user prototype property
changes, the system dynamically updates user properties
accordingly.
Cache Expiration Date and time Defines a future date after which the system no longer stores a
user’s password in cache. When an LDAP server is unavailable
a user can still log on with the cached credentials until this date
and time.
This property applies to Kerberos authentication even though
the station never receives the user’s password. Instead, the sta-
tion verifies the corresponding Kerberos user ticket against the
cached user information.
Connection time Determines the length of time the station attempts to connect to
Timeout the LDAP server before the connection fails.
The station will not fail over to the next LDAP server until the first
connection attempt is unresponsive for the amount of time
specified in the connection timeout. This time should be not too
short to cause false connection failures, but not so long as to
cause excessive delays when a server is down.

Active Directory Config

These properties are unique to Active Directory.

Property Value Description

Domain text Supplies the domain name used to contact the LDAP server.

LDAP V2 Config
These properties are unique to LDAP V2 Config.

Property Value Description

Connection User text Defines the user name for the initial LDAP server connection. It
may be required if users, who will be logging in, are in different
sub-trees of the LDAP directory. If the LDAP server supports
anonymous connections, leave this property empty (blank).
When used, requires a valid user name in the LDAP server. The
system uses this name to connect to the server for
authentication.
Connection Pwd text The password for the user specified in property Connection
User. When used, requires a valid password in the LDAP serv-
er. The system uses this password to connect to the server for
authentication.

LDAP V3 Config
These properties are unique to LDAP V3 Config.

32 October 10, 2018

LDAP Guide Chapter 3 Components

Property Value Description

Bind Format (N4) BFormat (Baja For- This property applies to Ldap V3 only. Every LDAP server is dif-
mat) syntax with a ferent. For the most part, a user base and logon name are suffi-
default value of % cient to find a user in the LDAP directory. However, when using
userName% DIGEST authentication, it may be necessary to specify the exact
format of the logon name to send to the server. In Active Direc-
tory (AD) 2000, this might be: %username%@domain.com. Lat-
er versions of AD would reject this format, however, they would
accept username based on how the server stores passwords.
Bind Format allows you to specify how to send the name to
the server, for example, using a BFormat this property would be:
%username%@domain.net or cn=%username,%userBase%.
For details, see the engineering notes document, BFormat (Baja
Format) Property Usage.
NOTE: For assistance, consult with your onsite LDAP adminis-
trator for assistance if the value of this property needs to be
changed.
Connection User text Defines the user name for the initial LDAP server connection. It
may be required if users, who will be logging in, are in different
sub-trees of the LDAP directory. If the LDAP server supports
anonymous connections, leave this property empty (blank).
When used, requires a valid user name in the LDAP server. The
system uses this name to connect to the server for
authentication.
Connection Pwd text The password for the user specified in property Connection
User. When used, requires a valid password in the LDAP serv-
er. The system uses this password to connect to the server for
authentication.
Authentication dropdown list LDAP v3 supports several methods for user validation. These
Mechanism are known as SASL (Simple Authentication and Security Layer)
mechanisms.
None
Simple (default) sends the user name and password to the
server in clear text.
CRAM-MD5 obscures the password for security.
DIGEST-MD5 obscures the password for security.

ldap-KerberosAuthenticationScheme
This component provides Kerberos authentication for logging in users to a station.
Kerberos is a network authentication protocol that allows nodes communicating over a network that is not se-
cure to prove their identity to one another in a secure manner. Aimed primarily at a client–server model, it pro-
vides mutual authentication—both the user and the server verify each other's identity.

October 10, 2018 33

Chapter 3 Components LDAP Guide

Figure 6 Kerberos authentication properties

Property Value Description

Enable Connection true or false Setting this property to true allows connections to be shared
Pooling and reused. This can improve performance.
Connection URL ldap://your.do- Identifies the URL (your.domain.net) for the LDAP server.
main.net Standard LDAP ports are 389, or 636 (if using SSL). If the server
or uses a non-standard port, include the port (your.domain.
ldap://your.do- net:nnn) in the URL, for example, ldap://your.domain.
main.net:nnn net.999..
SSL true or false Enables and disables secure communication. If set to true,
make sure that SSL (3.8) or TLS (4.0) is enabled in the station’s
FoxService (for EC-Net 4 Pro-to-station access) and Web-
Service (for browser-to-station access). Note that in FoxSer-
vice and WebService TLS must be enabled whether SSL is
true here or not.
User Login Attr text
For AD this value Identifies the specific attribute in the LDAP directory to store the
defaults to sAMAc- LDAP user login name. For AD servers, this is always sAMAc-
countName. countName. For OpenLDAP servers, it would be uid.

User Base domain Identifies the sub-tree of the LDAP server in which users who
components can access this station are found. At the very least it must con-
tain the domain components of the server’s domain, for exam-
ple: DC=domain, CD=net
Attr Email Email address Identifies the specific attribute in the LDAP directory to store the
The AD default val- user’s LDAP email address. This value populates the EC-Net
ue is: mail. user’s Email property.
Attr Full Name Text Identifies the specific attribute in the LDAP directory to store the
The AD default val- user’s full name. This value populates the EC-Net user’s Full
ue is: name. Name property.

34 October 10, 2018

LDAP Guide Chapter 3 Components

Property Value Description

Attr Language Two-letter language Identifies the specific attribute in the LDAP directory to store the
code user’s language. This value populates the EC-Net user’s Lan-
The AD default is guage property.
blank.
Attr Cell Phone Telephone num- Identifies the attribute in the LDAP directory that stores the
Number berThe AD default user’s mobile phone number. This value populates the EC-Net
is mobile. user’s Cell Phone Number property.
Attr Prototype Text Identifies the User Prototype with which the system popu-
The AD default is lates a new user’s local properties.
memberOf.
If this property is blank or the name does not match any user
prototype, the system uses the Default Prototype to popu-
late local user properties.
If a user belongs to multiple user groups (user prototypes), the
top-to-bottom order of prototypes determines which prototype
the system uses. If the value of a user prototype property
changes, the system dynamically updates user properties
accordingly.
Cache Expiration 00168h 00m 00s Allows users to continue to log in if the LDAP server is not reach-
(default) able (the Key Distribution Center still has to be reachable for
Kerberos). A user can continue to log in as long as the last time
that user logged in when the server was up is less than the
specified Cache Expiration. There are no limits on the property.
Connection time Determines the length of time the station attempts to connect to
Timeout the LDAP server before the connection fails.
The station will not fail over to the next LDAP server until the first
connection attempt is unresponsive for the amount of time
specified in the connection timeout. This time should be not too
short to cause false connection failures, but not so long as to
cause excessive delays when a server is down.
Realm UPPERCASE Identifies the system on which the LDAP server resides. You get
letters this information from your Kerberos administrator.
EXAMPLE.COM
Key Distribution Text Example: Specifies the name of the Kerberos Key Distribution Center that
Center kd.example.com the system contacts to get a ticket, which, like a key, is used to
authenticate the user to the EC-Net system. You get this infor-
mation from your Kerberos administrator.
Station Kerberos Text As part of securely delegating Kerberos tickets, this property
Name represents the station as a user in the Kerberos database. If log-
ging in only via EC-Net 4 Pro, this user can be any user or serv-
ice in the Kerberos directory.
However, if the user logs in via a browser, the user must be a
service in the form: HTTP/service-Name.domain.com, where
serviceName.domain.com is how the station is to be accessed
in the browser, (for example, http://stationkerb1.mydomain.
com).
The service name for the station Kerberos name typically omits
a bit of the normal http URL syntax, for example: http/station-
kerb1.mydomain.net instead of http://stationkerb1.mydomain.

October 10, 2018 35

Chapter 3 Components LDAP Guide

Property Value Description

net. You may need to ask the Kerberos administrator to create
the service for you in the Kerberos database.
NOTE: Kerberos is very particular about names. You must enter
the station name in the “Station Kerberos Name” property ex-
actly as it appears in the Kerberos database. Upper/lowercase
can sometimes be an issue, so make sure you have an exact
match.
Station Kerberos Text Specifies the password for the Kerberos station user identified
Password default: blank by the Station Kerberos Name property. If you are using a
keytab file, you can leave this property blank.
Key Tab File File name Kerberos services usually do not use a password to authenti-
cate. Instead, they use a file that contains a key table (keytab
file). To authenticate from a web browser you must specify an
associated service in the Station Kerberos Name property
and reference a keytab file supplied by the Kerberos
administrator.
You must copy that keytab file to this secure location on the EC-
Net 4 platform: protected_station_home/ldap. You need
to create the ldap directory manually. For the KeyTab File
property, select the keytab file from the drop-down. Again, if you
are using a keytab, you can leave the Station Kerberos
Password property blank (default).

36 October 10, 2018

Glossary
LDAP user A user whose access permissions are managed by an LDAP (Lightweight Direc-
tory Access Protocol) server.
local user A user that has been set up using the standard EC-Net user properties. The sys-
tem cannot validate a local user against the LDAP database. This type of user
can only log in to a local host. Two local users are common: the admin user and
a service user. The admin user logs in to the host during initial setup and rarely
thereafter to update EC-Net software. A service user represents the host to other
remote users.
realm A set of EC-Net Station devices that share the same Kerberos database. The
Kerberos database resides on the LDAP server.
service user A user created within a station for the sole purpose of representing the station as
the client of another remote host. No one ever logs in to host as the service user.
It represents the host to other remote hosts on the NiagaraNetwork when config-
uring the remote host’s Client Connection properties under the Niagara
Station device.
super user A type of local user that has full read-write permissions within a station. This user
can set up and update station software as well as create users and manager ac-
cess permissions. The default admin user is an example of a super user.

October 10, 2018 37

Chapter 3 Components LDAP Guide

38 October 10, 2018

Index
A K
Advanced Krb5 Conf Editor view ..........................30 Kerberos
authentication schemes .........................................7 configuring the client PC................................... 11
AuthenticationService...................................... 7, 21 krb5.conf......................................................... 11
AXDigestScheme................................................21 krb5.ini............................................................ 11
login................................................................19
tickets .............................................................13
B Kerberos authentication.......................................33
Kerberos master-slave server
baja-UserPrototype .............................................21 configuring ......................................................16
Basic Krb5 Conf Editor view .................................29 KerberosScheme ..................................................9
browser Key Distribution Center........................................13
login................................................................20
browser configuration ..........................................13
browserlogin ................................................. 19–20 L
LDAP
C attributes.........................................................18
benefits ...........................................................17
Chrome definition .........................................................17
configuring ......................................................15 LDAP implementations ........................................17
components........................................................21 LDAP users ........................................................18
ldap-LdapAuthenticationScheme..........................30
LdapScheme ........................................................9
D legal notices .........................................................2
local service user
defaultPrototype..................................................10
configuring ......................................................10
DigestScheme ....................................................21
local users ..........................................................18
DNS configuration ...............................................13
document change log ............................................5
P
F PC setup for Kerberos ......................................... 11
prerequisites.........................................................7
FAQ .....................................................................8
prototype
Firefox
default user properties......................................10
configuring ......................................................13

G R
related documentation ...........................................5
Google Chrome
configuring ......................................................15
S
H scheme
configuring ........................................................9
HTTPBasicScheme.............................................21
setup and configuration .........................................7
single sign on................................................ 19–20
SSO ............................................................. 19–20
I
Internet Explorer
configuring ......................................................14 T
tickets used in Kerberos authentication .................13

October 10, 2018 39

Index LDAP Guide

U
user groups ........................................................19
user prototypes ...................................................19
users
admin .............................................................18
LDAP ..............................................................18
local................................................................18
prototype.........................................................10

40 October 10, 2018

Index LDAP Guide

41 October 10, 2018

LDAP EC-Net4_UG_14_EN