ldap-LdapAuthenticationScheme

Adding the LdapScheme manages Niagara 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 also keeps passwords centralized and in sync.

Common properties

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 connection, a login failure occurs with a message stating "Secure connection required". Enable TLS secure communication 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).

Property	Value	Description
Type	drop-down list of configuration types	Selects the type of configuration. The system supports sets of configuration properties: 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 Pooling	true (default) or false	Enables (true) and disables (false) the use of a connection pool. To speed processing, LDAP servers maintain a pool of connections. A request from the system that uses an existing connection saves valuable processing time, which improves system performance. Do not change the default (true = enabled) setting unless you know what you are doing.
Connection URL	ldap://`your.domain.net` orldap://`your.domain.net:nnn`	Identifies the URL (`your.domain.net`) for the LDAP server. Standard LDAP ports are 389, or 636 (if using SSL). If the server uses a non-standard port, include the port (`your.domain.net:nnn`) in the URL, for example, `ldap://your.domain.net.999`.
SSL	true or false	Enables (true) and disables (false) secure communication. If set to true, make sure that SSL (3.8) or TLS (4.0) is enabled in the station’s FoxService (for Workbench-to-station access) and WebService (for browser-to-station access). Note that in FoxService and WebService TLS must be enabled whether SSL is true here or not.
User Login Attr	textFor AD this value defaults to `sAMAccountName`	Identifies the specific attribute in the LDAP directory to store the LDAP user login name. For AD servers, this is always `sAMAccountName`. For OpenLDAP servers, it would be `uid`.
User Base	domain components	Identifies the sub-tree of the LDAP server in which users who can access this station are found. At the very least it must contain the domain components of the server’s domain, for example: `DC=domain`, `CD=net`.
Attr Email	Email address (AD defaults to: `mail`)	Identifies the specific attribute in the LDAP directory to store the user’s LDAP email address. This value populates the Niagara user’s Email property.
Attr Full Name	text (The AD defaults to: `name`)	Identifies the specific attribute in the LDAP directory to store the user’s full name. This value populates the Niagara user’s Full Name property.
Attr Language	two-letter language code (AD defaults to blank)	Identifies the specific attribute in the LDAP directory to store the user’s language. This value populates the Niagara user’s Language property.
Cell Phone Number	telephone number (AD defaults to mobile)	Identifies the attribute in the LDAP directory that stores the user’s mobile phone number. This value populates the Niagara user’s Cell Phone Number property.
Attr Prototype	text (AD defaults to `memberOf`).	Identifies the User Prototype with which the system populates a new user’s local properties. If this property is blank or the name does not match any user prototype, the system uses the Default Prototype to populate 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	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 station verifies the corresponding Kerberos user ticket against the cached user information.
Connection Timeout	time	Determines the length of time the station attempts to connect to 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 not be too short to cause false connection failures, but not so long as to cause excessive delays when a server is down.

Active Directory Config

This property is 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
Domain	text	Supplies the domain name used to contact the LDAP server.
Connection Pwd	password	Defines the password for the user specified in property Connection User. When used, requires a valid password in the LDAP server. The system uses this password to connect to the server for authentication.

LDAP V3 Config

These properties are unique to LDAP V3 Config.

Property	Value	Description
Bind Format	BFormat (Baja Format) syntax with a default value of `%userName%`	Specifies how to send the user name to the server. This feature applies to Ldap V3 only. Every LDAP server is different. For the most part, a user base and logon name are sufficient to find a user in the LDAP directory. However, when using DIGEST authentication, it may be necessary to specify the exact format of the logon name to send to the server. In Active Directory (AD) 2000, this might be: `%username%@domain.com`. Later versions of AD would reject this format, however, they would accept a 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: If the value of this property needs to be changed, consult with your onsite LDAP administrator for assistance .
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	password	Defines the password for the user specified in property Connection User. When used, requires a valid password in the LDAP server. The system uses this password to connect to the server for authentication.
Authentication Mechanism	dropdown list	LDAP v3 supports several methods for user validation. These 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.